README

Automate the complete 12-step Zuse RBAC integration process in just 2 minutes!

This package transforms the manual 2-4 hour integration process into a single automated command that handles everything for you.

✨ What This Package Does

Instead of manually following 12 complex steps, this package automatically:

• ✅ Step 2: Installs required dependencies (firebase/php-jwt, guzzlehttp/guzzle)
• ✅ Step 3: Configures environment variables in .env
• ✅ Step 4: Adds Keycloak service configuration
• ✅ Step 5: Creates secure KeycloakController with best practices
• ✅ Step 6: Registers authentication routes
• ✅ Step 7: Enhances User model with RBAC methods
• ✅ Step 8: Creates and registers RoleMiddleware
• ✅ Step 9: Creates database migration for Keycloak fields
• ✅ Step 10: Creates beautiful dashboard view
• ✅ Step 11: Runs comprehensive integration tests

📦 Installation & Usage

Prerequisites

1. Get your credentials from the Lyceum RBAC middleware panel:
   • Login to the Lyceum RBAC panel
   • Create a new application (Laravel type)
   • Copy your Client ID and Client Secret

Quick Setup (2 minutes)

# 1. Install the package
composer require zuse/laravel-rbac-auto

# 2. Run the automated integration
php artisan zuse:integrate \
  --client-id="your-client-id-from-lyceum-panel" \
  --client-secret="your-client-secret-from-lyceum-panel" \
  --test

# 3. Apply database changes
php artisan migrate

# 4. Test your integration
php artisan serve
# Visit: http://localhost:8000/auth/keycloak

That's it! 🎉 Your Laravel app now has complete RBAC integration.

⚙️ Command Options

php artisan zuse:integrate [options]

Required Options

• --client-id: Your client ID from Lyceum RBAC panel
• --client-secret: Your client secret from Lyceum RBAC panel

Optional Options

• --base-url: Keycloak base URL (default: https://keycloak.zuse.lk)
• --realm: Keycloak realm (default: zuse)
• --redirect-uri: Custom redirect URI (default: auto-generated)
• --test: Run integration tests after setup
• --force: Force overwrite existing files

Examples

# Basic integration
php artisan zuse:integrate --client-id="abc123" --client-secret="secret456"

# With custom settings
php artisan zuse:integrate \
  --client-id="abc123" \
  --client-secret="secret456" \
  --base-url="https://auth.mycompany.com" \
  --realm="mycompany" \
  --test

# Force overwrite existing integration
php artisan zuse:integrate \
  --client-id="abc123" \
  --client-secret="secret456" \
  --force

🔐 What Gets Created

1. Environment Configuration (.env)

KEYCLOAK_BASE_URL=https://keycloak.zuse.lk
KEYCLOAK_REALM=zuse
KEYCLOAK_CLIENT_ID=your-client-id
KEYCLOAK_CLIENT_SECRET=your-client-secret
KEYCLOAK_REDIRECT_URI=http://localhost:8000/auth/keycloak/callback

2. Service Configuration (config/services.php)

'keycloak' => [
    'base_url' => env('KEYCLOAK_BASE_URL'),
    'realm' => env('KEYCLOAK_REALM'),
    'client_id' => env('KEYCLOAK_CLIENT_ID'),
    'client_secret' => env('KEYCLOAK_CLIENT_SECRET'),
    'redirect_uri' => env('KEYCLOAK_REDIRECT_URI'),
    // ... complete configuration
],

3. Authentication Controller

• app/Http/Controllers/Auth/KeycloakController.php
• Includes security best practices from your proven implementation
• JWT signature verification for production
• Refresh token rotation
• State parameter validation

4. User Model Enhancement

Your User model gets enhanced with RBAC methods:

public function hasRole($role): bool
public function hasAnyRole(array $roles): bool  
public function belongsToGroup($group): bool

5. Role Middleware

• app/Http/Middleware/RoleMiddleware.php
• Automatically registered in Kernel.php

6. Authentication Routes

Route::get('/auth/keycloak', [KeycloakController::class, 'login']);
Route::get('/auth/keycloak/callback', [KeycloakController::class, 'callback']);
Route::post('/auth/keycloak/logout', [KeycloakController::class, 'logout']);
Route::post('/auth/keycloak/refresh', [KeycloakController::class, 'refreshToken']);

7. Database Migration

Adds Keycloak fields to your users table:

• keycloak_id (string, nullable, indexed)
• roles (json, nullable)
• groups (json, nullable)

8. Dashboard View

Beautiful dashboard at resources/views/dashboard.blade.php showing:

• User information
• Roles and groups
• Role-based content examples
• Authentication status

🛡️ Usage Examples

Protecting Routes with Roles

// Protect routes with role middleware
Route::middleware(['auth', 'role:admin'])->group(function () {
    Route::get('/admin', [AdminController::class, 'index']);
});

// Multiple roles
Route::middleware(['auth', 'role:admin,manager'])->group(function () {
    Route::get('/reports', [ReportsController::class, 'index']);
});

Using RBAC in Controllers

class UserController extends Controller
{
    public function index()
    {
        // Check if user has specific role
        if (!Auth::user()->hasRole('admin')) {
            abort(403, 'Admin access required');
        }

        // Check for any of multiple roles
        if (!Auth::user()->hasAnyRole(['admin', 'manager'])) {
            abort(403, 'Management access required');
        }

        return view('users.index');
    }
}

Using RBAC in Blade Views

@if(Auth::user()->hasRole('admin'))
    <div class="admin-panel">
        <a href="/admin">Admin Panel</a>
    </div>
@endif

@if(Auth::user()->hasAnyRole(['developer', 'admin']))
    <div class="dev-tools">
        <a href="/dev-tools">Developer Tools</a>
    </div>
@endif

🧪 Integration Testing

The package includes comprehensive tests that verify:

• ✅ All required files are created
• ✅ Environment variables are configured
• ✅ Routes are properly registered
• ✅ Middleware is configured
• ✅ Database migration is created
• ✅ Service configuration is valid
• ✅ User model is properly enhanced

Run tests with the --test flag:

php artisan zuse:integrate --client-id="abc123" --client-secret="secret456" --test

🔧 Manual Steps (No Longer Needed!)

This package replaces these manual steps:

1. Create New Laravel Project (you do this)
2. ✅ Install Required Dependencies - AUTOMATED
3. ✅ Configure Environment Variables - AUTOMATED
4. ✅ Configure Services - AUTOMATED
5. ✅ Create Authentication Controller - AUTOMATED
6. ✅ Add Authentication Routes - AUTOMATED
7. ✅ Update User Model - AUTOMATED
8. ✅ Create Role Middleware - AUTOMATED
9. ✅ Database Migration - AUTOMATED
10. ✅ Create Dashboard View - AUTOMATED
11. ✅ Test Your Integration - AUTOMATED
12. Deploy & Configure (you do this)

Result: 2-4 hours → 2 minutes! 🚀

❓ Troubleshooting

Common Issues

"Client ID and Client Secret are required"

• Make sure you've created an application in the Lyceum RBAC middleware panel
• Copy the exact Client ID and Client Secret from the panel

"Authentication routes not registered"

• Clear your route cache: php artisan route:clear
• Check that web routes file was updated

"Token validation failed"

• Verify your client credentials are correct
• Check that your redirect URI matches the one configured in Lyceum panel

"User model missing RBAC methods"

• The package modifies your existing User model
• If it fails, manually add the RBAC methods from the generated migration

Getting Help

• 📖 Documentation: https://docs.zuse.lk/rbac
• 🎯 Support: support@zuse.lk
• 🐛 Issues: GitHub Issues

📊 Performance Benefits

🎯 Requirements

• PHP 8.1 or higher
• Laravel 10.x, 11.x, or 12.x
• Access to Lyceum RBAC middleware panel
• Valid Keycloak client credentials

📝 License

This package is open-source software licensed under the MIT license.

Made with ❤️ by Zuse Technologies