Relay Keycloak Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The dbp/relay-keycloak-bundle appears tailored for integrating Keycloak identity and access management (IAM) into a Laravel application, specifically for authentication, authorization, and user federation. This aligns well with Laravel-based systems requiring SSO, OAuth2/OIDC, or role-based access control (RBAC).
• Modularity: As a Symfony/Laravel bundle, it leverages dependency injection (DI) and service containers, making it modular and composable. This fits seamlessly into Laravel’s ecosystem (e.g., Illuminate\Contracts compatibility).
• Keycloak-Specific Features:
  • Token relay (JWT validation/propagation).
  • User provisioning (syncing Keycloak users to Laravel).
  • Role/permission mapping (Keycloak realms → Laravel policies).
  • Event-driven hooks (e.g., Authenticate, UserCreated).
• Gaps:
  • No built-in multi-tenancy support (would require custom logic).
  • Limited documentation (risk of unclear implementation paths).
  • Keycloak version lock-in (e.g., if the bundle targets Keycloak 18+, but your instance runs 20+).

Integration Feasibility

• Laravel Compatibility:
  • Uses Symfony components (e.g., HttpFoundation, DependencyInjection), which Laravel supports via symfony/http-foundation and symfony/dependency-injection.
  • Service Provider pattern is familiar to Laravel devs (registers routes, middleware, and services in config/app.php).
  • Middleware Integration: Can replace or extend Laravel’s default Auth middleware for Keycloak-backed auth.
• Keycloak Prerequisites:
  • Requires a running Keycloak instance (self-hosted or cloud).
  • Needs client configuration (realm, client ID, secret, redirect URIs).
  • JWT validation may need tuning (e.g., leeway for token clock skew).
• Database Schema:
  • Assumes user tables exist (or expects custom provisioning logic).
  • May require migrations to store Keycloak-specific fields (e.g., keycloak_sub, keycloak_realm).

Technical Risk

Key Questions

1. Keycloak Setup:
   • Is Keycloak already deployed? What version?
   • Are there existing clients/realms to integrate with?
2. Auth Flow:
   • Should users log in via Keycloak’s UI or Laravel’s routes (with Keycloak redirect)?
   • Is passwordless auth (e.g., OTP, social login) required?
3. Data Model:
   • Should Laravel’s users table be read-only (Keycloak as source of truth) or writable (sync both ways)?
4. Fallbacks:
   • What happens if Keycloak is down? (e.g., local auth fallback?)
5. Compliance:
   • Are there GDPR/privacy requirements for user data sync?
6. Extensibility:
   • Will custom attributes/roles need mapping beyond the bundle’s defaults?

Integration Approach

Stack Fit

• Laravel Version: Tested on Laravel 8+ (Symfony 5.4+). If using Laravel 9/10, check for symfony/http-client v6+ compatibility.
• Keycloak Client:
  • Admin REST API: Required for user provisioning (if enabled in Keycloak).
  • OIDC Endpoints: Must be publicly accessible (e.g., auth/realms/{realm}/protocol/openid-connect).
• Dependencies:
  • league/oauth2-server (for JWT validation) – may conflict with Laravel’s lcobucci/jwt.
  • symfony/http-client – for Keycloak API calls.
• Alternatives Considered:
  • Laravel Socialite: For simpler OAuth2 (but lacks Keycloak-specific features).
  • Custom Middleware: If bundle is overkill (e.g., only need JWT validation).

Migration Path

1. Preparation:
   • Set up Keycloak client with valid redirect URIs (e.g., https://app.example.com/login/callback).
   • Configure token relay in Keycloak (enable Use Refresh Tokens if needed).
2. Bundle Installation:

   composer require dbp/relay-keycloak-bundle
   

   • Publish config:

     php artisan vendor:publish --provider="DBP\RelayKeycloakBundle\RelayKeycloakBundle" --tag="config"
     

3. Configuration:
   • Update .env with Keycloak details:

     KEYCLOAK_REALM=your-realm
     KEYCLOAK_CLIENT_ID=your-client
     KEYCLOAK_CLIENT_SECRET=your-secret
     KEYCLOAK_URL=https://keycloak.example.com/auth
     

   • Configure config/relay_keycloak.php:

     'jwt' => [
         'leeway' => 30, // seconds
         'supported_algs' => ['RS256'],
     ],
     'user_provisioning' => [
         'enabled' => true,
         'sync_roles' => true,
     ],
     

4. Middleware Setup:
   • Replace Laravel’s auth middleware in app/Http/Kernel.php:

     'auth' => \DBP\RelayKeycloakBundle\Http\Middleware\Authenticate::class,
     

   • Add Keycloak relay middleware for protected routes:

     \DBP\RelayKeycloakBundle\Http\Middleware\RelayKeycloakToken::class,
     

5. Routing:
   • Use bundle’s routes for login/logout:

     use DBP\RelayKeycloakBundle\Routing\KeycloakRoutes;
     KeycloakRoutes::register($router);
     

   • Or extend existing routes with Keycloak guards:

     Route::get('/dashboard', function () {
         // Access Keycloak user via auth()->user()->keycloakAttributes
     })->middleware('auth:keycloak');
     

6. Testing:
   • Validate JWT relay with Postman/curl:

     curl -H "Authorization: Bearer $KEYCLOAK_JWT" https://app.example.com/api/user
     

   • Test user provisioning by creating a user in Keycloak and verifying Laravel’s DB.

Compatibility

• Laravel Services:
  • Extend Illuminate\Auth\UserProvider to fetch users from Keycloak via keycloak_sub.
  • Use auth()->user()->getKeycloakRoles() if bundle supports role mapping.
• Third-Party Packages:
  • Laravel Passport: Can coexist if using Keycloak as an identity provider (not OAuth2 server).
  • Spatie Laravel Permission: Map Keycloak roles to Spatie permissions via events.
• Caching:
  • Cache Keycloak public keys (JWKS) to reduce API calls:

    Cache::remember('keycloak_jwks', now()->addHours(1), fn() => file_get_contents($keycloakUrl . '/protocol/openid-connect/certs'));
    

Sequencing

1. Phase 1: Token Relay (MVP)
   • Implement JWT validation for API routes.
   • Use Keycloak as a stateless auth provider.
2. Phase 2: User Provisioning
   • Sync users from Keycloak to Laravel.
   • Handle role/permission mapping.
3. Phase 3: Full SSO
   • Redirect all auth flows to Keycloak.
   • Replace Laravel’s login system entirely.
4. Phase 4: Advanced Features
   • Multi-realm support.
   • Custom attribute mapping.

Operational Impact

Maintenance

• Bundle Updates:
  • Monitor for Keycloak version support (e.g., upgrade to Keycloak 22+).
  • Patch dependencies (e.g., symfony/http-client).
• Keycloak Admin: