README

Enterprise-grade, multi-tenant ready authentication and authorization engine for Laravel.

Build secure, scalable API authentication processes with built-in role & permission management, seamless stancl/tenancy integration, and automated setup — right out of the box.

Table of Contents

• Features
• Requirements
• Installation
• Configuration
• Multi-Tenancy
• Quick Start
  • 1. Update Your User Model
  • 2. Authenticate
  • 3. Fetch User Profile
  • 4. Manage Roles & Permissions
• API Reference
  • Public Authentication Routes
  • Authorization Admin Routes

Features

Requirements

• PHP ≥ 8.3
• Laravel 11.x or 12.x
• Database MySQL 8+ or PostgreSQL 14+

Installation

1. Add the Package

Run the following command in your main project terminal to download the package:

composer require elgibor-solution/laravel-authentication

2. Automated Setup (Highly Recommended)

Instead of configuring migrations and settings manually, run this automation command:

php artisan elgibor-auth:install

The wizard will automatically:

1. Publish all migration files (roles, permissions tables, etc.).
2. Ask if you are using stancl/tenancy. (If yes, it smartly moves migrations to the tenant/ directory and generates keys securely).
3. Install Passport encryption keys (php artisan passport:install or passport:keys).
4. Update your config/auth.php file by injecting the api guard.
5. Automatically append the necessary traits into your project's app/Models/User.php model.

3. Publish Configuration (Optional)

To customize the flexibility of this package, publish the configuration file to your application's root directory:

php artisan vendor:publish --tag=authentication-config

This publishes config/authentication.php where you can customize all settings.

Configuration

The full configuration lives in config/authentication.php. Below are the most important sections:

// config/authentication.php
return [
    // Base URL prefix for all authentication endpoints
    'prefix' => 'api/auth',
    
    // Core middleware required for the package to function
    'middleware' => ['api', 'tenant'],

    // Require extra fields during login (e.g., 'tenant_id' for single-db tenancy)
    'login_extra_fields' => [],
    
    // Automatically eager-load relationships when calling the `/me` endpoint
    'load_relations' => ['profile', 'agency'], 
];

Multi-Tenancy

This package is designed to work seamlessly with stancl/tenancy for database-per-tenant isolation.

Automated Integration

If you run php artisan elgibor-auth:install and select "Yes" for stancl/tenancy:

• The package will automatically move oauth_* migrations into database/migrations/tenant/ (roles and permissions migrations remain in the central database).
• It will generate central Passport keys without forcing client creation on the central DB.

1. Register Tenant Middleware

In Laravel 11, you must ensure the tenant middleware is registered in your application. Open your project's bootstrap/app.php file and add the alias:

->withMiddleware(function (Middleware $middleware): void {
    $middleware->alias([
        'tenant' => \Stancl\Tenancy\Middleware\InitializeTenancyByDomain::class,
    ]);
})

2. Configure Package Middleware

Ensure the tenant middleware is injected into the package's configuration:

// config/authentication.php
'middleware' => ['api', 'tenant'],

3. Tenant Client Generation

Since the database is isolated, you must create a Personal Access Client inside each newly created tenant:

php artisan tenants:run passport:client --personal

Quick Start

1. Update Your User Model

Ensure the User Model in your project uses the traits provided by the package (this is done automatically if you used the install command):

use ElgiborSolution\Authentication\Traits\HasCustomRole;
use Laravel\Passport\HasApiTokens;

class User extends Authenticatable {
    use HasApiTokens, HasCustomRole;
}

2. Authenticate

Submit credentials to retrieve your access token:

curl -X POST http://your-app/api/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "password123"
  }'

3. Fetch User Profile

Retrieve the authenticated user's profile, including their flattened permissions array and active tenant object:

curl http://your-app/api/auth/me \
  -H "Authorization: Bearer <your-access-token>"

4. Manage Roles & Permissions

Create a new role with assigned permissions:

curl -X POST http://your-app/api/auth/roles \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "role_name": "Manager",
    "role_description": "Store manager",
    "permissions": [1, 2, 5]
  }'

API Reference

Public Authentication Routes

The login route is public and has '/auth' stripped from the prefix.

Protected Authentication Routes

These routes require the auth:api middleware and are prefixed with /api/auth.

Authorization Admin Routes

All routes require the auth:api middleware.