nahidferdous/laravel-shield

Shield - A comprehensive Laravel package for authentication (Sanctum, Passport, JWT), socialite and role/permission management with social login support.

1.0.8 2025-12-15 11:41 UTC

Requires

• php: ^8.2
• laravel/framework: ^12.0
• laravel/sanctum: ^4.0
• laravel/socialite: ^5.23
• socialiteproviders/manager: ^4.0
• spatie/laravel-permission: ^6.23

Requires (Dev)

• laravel/pint: ^1.25
• nunomaduro/collision: ^8.6
• orchestra/testbench: ^10.0
• pestphp/pest: ^3.0
• pestphp/pest-plugin-laravel: ^3.0

Suggests

• laravel/passport: Install if you want to use the Passport auth driver ^11.0|^12.0
• tymon/jwt-auth: Install if you want to use the JWT auth driver ^2.2

MIT

• Nahid Ferdous

• api
• laravel
• passport
• roles
• socialite
• sanctum

README

Laravel Shield - Complete Authentication Package

A comprehensive Laravel package for authentication (Sanctum, Passport, JWT) and role/permission management with social login support.

Features

• 🔐 Multiple authentication drivers (Sanctum, Passport, JWT)
• 👥 Social login (Google, Facebook, GitHub, Twitter, LinkedIn)
• 🛡️ Role-based access control (RBAC)
• 🔑 Permission/Privilege management
• 💾 Caching support
• 🚀 Production-ready out of the box
• 📝 Comprehensive CLI commands

Installation

composer require nahidferdous/shield

Quick Start

1. Install Shield

php artisan shield:install

This will:

• Publish configuration file
• Run migrations
• Prepare your User model
• Seed default roles

2. Choose Authentication Driver

Edit .env:

SHIELD_AUTH_DRIVER=sanctum  # Options: sanctum, passport, jwt

3. Configure Authentication Driver

For Sanctum (Default)

php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"

For Passport

php artisan passport:install
composer require laravel/passport

Add to .env:

PASSPORT_PERSONAL_ACCESS_CLIENT_ID=your-client-id
PASSPORT_PERSONAL_ACCESS_CLIENT_SECRET=your-client-secret

For JWT

composer require firebase/php-jwt

Add to .env:

JWT_SECRET=your-secret-key
JWT_TTL=60
JWT_REFRESH_TTL=20160

4. Enable Social Login (Optional)

composer require laravel/socialite socialiteproviders/manager

Edit .env:

SHIELD_SOCIAL_LOGIN_ENABLED=true

# Google
GOOGLE_LOGIN_ENABLED=true
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URL="${APP_URL}/api/auth/google/callback"

# Facebook
FACEBOOK_LOGIN_ENABLED=true
FACEBOOK_CLIENT_ID=your-app-id
FACEBOOK_CLIENT_SECRET=your-app-secret

# GitHub
GITHUB_LOGIN_ENABLED=true
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret

API Endpoints

Authentication

Register

POST /api/register
Content-Type: application/json

{
  "name": "John Doe",
  "email": "[e-mail]",
  "password": "password123"
}

Login

POST /api/login
Content-Type: application/json

{
  "email": "[e-mail]",
  "password": "password123"
}

Response:

{
  "error": 0,
  "id": 1,
  "name": "John Doe",
  "email": "[e-mail]",
  "token": "your-access-token",
  "token_type": "Bearer"
}

Logout

POST /api/logout
Authorization: Bearer your-access-token

Refresh Token

POST /api/refresh
Authorization: Bearer your-access-token

Get Current User

GET /api/me
Authorization: Bearer your-access-token

Social Authentication

Get Enabled Providers

GET /api/auth/providers

Response:

{
  "error": 0,
  "providers": ["google", "facebook", "github"]
}

Redirect to Provider

GET /api/auth/{provider}/redirect

Example: GET /api/auth/google/redirect

Handle Callback

GET /api/auth/{provider}/callback

This endpoint is called automatically by the OAuth provider.

User Management

List Users

GET /api/users
Authorization: Bearer your-access-token

Get User

GET /api/users/{id}
Authorization: Bearer your-access-token

Update User

PUT /api/users/{id}
Authorization: Bearer your-access-token
Content-Type: application/json

{
  "name": "Updated Name",
  "email": "[e-mail]"
}

Delete User

DELETE /api/users/{id}
Authorization: Bearer your-access-token

Role Management

List Roles

GET /api/roles
Authorization: Bearer your-access-token

Create Role

POST /api/roles
Authorization: Bearer your-access-token
Content-Type: application/json

{
  "name": "Editor",
  "slug": "editor",
  "description": "Can edit content"
}

Assign Role to User

POST /api/roles/{roleId}/users/{userId}
Authorization: Bearer your-access-token

Remove Role from User

DELETE /api/roles/{roleId}/users/{userId}
Authorization: Bearer your-access-token

Privilege Management

List Privileges

GET /api/privileges
Authorization: Bearer your-access-token

Create Privilege

POST /api/privileges
Authorization: Bearer your-access-token
Content-Type: application/json

{
  "name": "Edit Posts",
  "slug": "edit-posts",
  "description": "Can edit blog posts"
}

Attach Privilege to Role

POST /api/privileges/{privilegeId}/roles/{roleId}
Authorization: Bearer your-access-token

CLI Commands

User Management

php artisan shield:create-user           # Create a new user
php artisan shield:list-users            # List all users
php artisan shield:update-user           # Update user details
php artisan shield:delete-user           # Delete a user
php artisan shield:suspend-user          # Suspend a user
php artisan shield:unsuspend-user        # Unsuspend a user
php artisan shield:login                 # Login via CLI
php artisan shield:logout                # Logout current session

Role Management

php artisan shield:add-role              # Create a new role
php artisan shield:list-roles            # List all roles
php artisan shield:update-role           # Update role details
php artisan shield:delete-role           # Delete a role
php artisan shield:assign-role           # Assign role to user
php artisan shield:delete-user-role      # Remove role from user

Privilege Management

php artisan shield:add-privilege         # Create a privilege
php artisan shield:list-privileges       # List all privileges
php artisan shield:update-privilege      # Update privilege
php artisan shield:delete-privilege      # Delete privilege
php artisan shield:attach-privilege      # Attach privilege to role
php artisan shield:detach-privilege      # Detach privilege from role

Middleware

Role-Based Middleware

// Single role
Route::middleware(['auth:sanctum', 'role:admin'])->group(function () {
    // Admin only routes
});

// Multiple roles (any)
Route::middleware(['auth:sanctum', 'roles:admin,moderator'])->group(function () {
    // Admin or Moderator routes
});

Privilege-Based Middleware

// Single privilege
Route::middleware(['auth:sanctum', 'privilege:edit-posts'])->group(function () {
    // Routes for users with edit-posts privilege
});

// Multiple privileges (any)
Route::middleware(['auth:sanctum', 'privileges:edit-posts,delete-posts'])->group(function () {
    // Routes for users with any of these privileges
});

Configuration

Publish and edit config/shield.php:

return [
    // Authentication driver
    'auth_driver' => env('SHIELD_AUTH_DRIVER', 'sanctum'),
    
    // Default user role
    'default_user_role_slug' => env('DEFAULT_ROLE_SLUG', 'user'),
    
    // Delete previous tokens on login
    'delete_previous_access_tokens_on_login' => env('DELETE_PREVIOUS_ACCESS_TOKENS_ON_LOGIN', false),
    
    // Social login
    'social' => [
        'enabled' => env('SHIELD_SOCIAL_LOGIN_ENABLED', false),
        'auto_create_user' => true,
        'auto_verify_email' => true,
    ],
    
    // JWT configuration
    'jwt' => [
        'secret' => env('JWT_SECRET'),
        'ttl' => env('JWT_TTL', 60),
        'refresh_ttl' => env('JWT_REFRESH_TTL', 20160),
    ],
    
    // Cache
    'cache' => [
        'enabled' => env('SHIELD_CACHE_ENABLED', true),
        'ttl' => env('SHIELD_CACHE_TTL', 300),
    ],
];

Switching Between Authentication Drivers

Simply change the SHIELD_AUTH_DRIVER in your .env:

# Use Sanctum
SHIELD_AUTH_DRIVER=sanctum

# Use Passport
SHIELD_AUTH_DRIVER=passport

# Use JWT
SHIELD_AUTH_DRIVER=jwt

No code changes required! Shield handles the rest automatically.

User Model Setup

Your User model should use the Shield traits:

use NahidFerdous\Shield\Traits\HasRoles;
use Laravel\Sanctum\HasApiTokens;  // or Laravel\Passport\HasApiTokens for Passport

class User extends Authenticatable
{
    use HasApiTokens, HasRoles;
    
    protected $fillable = [
        'name',
        'email',
        'password',
        'provider',
        'provider_id',
        'avatar',
    ];
}

Testing Social Login Locally

Use ngrok or similar tool to expose your local server:

ngrok http 8000

Then update your OAuth app redirect URLs to use the ngrok URL.

Security

• Always use HTTPS in production
• Keep your JWT secret secure
• Rotate tokens regularly
• Enable token blacklisting for JWT
• Implement rate limiting on login endpoints

License

MIT License

Support

For issues and questions, please open an issue on GitHub.