Relay Core Connector Oidc Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dbp/relay-core-connector-oidc-bundle
   

   Ensure your project uses Laravel 8+ (or Lumen 8+) and Relay Core Bundle (dbp/relay-core-bundle).

2. Publish Configuration

   php artisan vendor:publish --provider="DBP\Relay\Core\Connector\OIDCBundle\OIDCBundle" --tag="config"
   

   This generates config/relay-connector-oidc.php. Configure your OIDC provider (e.g., Keycloak, Auth0) with required fields:

   'providers' => [
       'default' => [
           'authority' => 'https://your-oidc-provider.com',
           'client_id' => env('OIDC_CLIENT_ID'),
           'client_secret' => env('OIDC_CLIENT_SECRET'),
           'scopes' => ['openid', 'profile', 'email'],
           'redirect_uri' => env('OIDC_REDIRECT_URI'),
       ],
   ],
   

3. Register Bundle Add to config/app.php under providers:

   DBP\Relay\Core\Connector\OIDCBundle\OIDCBundle::class,
   

4. First Use Case: Authenticate a Relay Request Use the OIDCConnector service to validate tokens in incoming requests:

   use DBP\Relay\Core\Connector\OIDCBundle\Service\OIDCConnector;
   
   public function handle(Request $request, OIDCConnector $connector)
   {
       $token = $request->bearerToken();
       $userInfo = $connector->validateAndFetchUserInfo($token);
   
       // Proceed with authenticated logic...
   }
   

Implementation Patterns

Workflows

1. Token Validation in API Gateways Integrate with Laravel middleware to validate OIDC tokens before processing Relay requests:

   // app/Http/Middleware/ValidateOIDCToken.php
   public function handle(Request $request, Closure $next)
   {
       $connector = app(OIDCConnector::class);
       if (!$connector->validateToken($request->bearerToken())) {
           abort(401, 'Invalid OIDC token');
       }
       return $next($request);
   }
   

2. Dynamic Provider Switching Use the provider config key to switch OIDC providers per environment or route:

   $connector = app(OIDCConnector::class)->setProvider('custom_provider_key');
   

3. User Info Caching Cache user info responses to reduce OIDC provider load:

   $userInfo = $connector->validateAndFetchUserInfo($token, 300); // Cache for 5 minutes
   

Integration Tips

• Relay Core Integration: Use the RelayRequest facade to attach OIDC user data:

  RelayRequest::setUser($userInfo);
  

• Lumen Compatibility: Register the bundle in bootstrap/app.php:

  $app->register(\DBP\Relay\Core\Connector\OIDCBundle\OIDCBundle::class);
  

• Testing: Mock the OIDCConnector in unit tests:

  $this->mock(OIDCConnector::class)->shouldReceive('validateToken')->andReturn(true);
  

Gotchas and Tips

Pitfalls

1. Token Expiry Handling

   • OIDC tokens expire. Always handle OIDCException for expired tokens:

     try {
         $connector->validateToken($token);
     } catch (\DBP\Relay\Core\Connector\OIDCBundle\Exception\OIDCException $e) {
         abort(401, 'Token expired or invalid');
     }
     

   • Use short-lived access tokens and refresh them via OIDCConnector::refreshToken().

2. Redirect URI Mismatch

   • Ensure redirect_uri in config matches the callback URL registered with your OIDC provider. Mismatches cause invalid_redirect_uri errors.

3. Scope Restrictions

   • If your OIDC provider requires specific scopes (e.g., profile), ensure they’re included in the scopes config array. Missing scopes return insufficient_scope errors.

4. HTTPS Requirement

   • OIDC providers often reject non-HTTPS endpoints. Test locally with trust in config/app.php or use tools like ngrok for HTTPS tunneling.

Debugging

• Enable Logging Set debug: true in the config to log OIDC requests/responses:

  'debug' => env('APP_DEBUG', false),
  

  Logs appear in storage/logs/laravel.log.

• Token Introspection Use the introspectToken() method to debug token validity:

  $response = $connector->introspectToken($token);
  dd($response); // Check 'active' field
  

Extension Points

1. Custom Claims Mapping Override default claim mapping (e.g., sub to user_id) in a service provider:

   $connector->setClaimMapper(function ($claims) {
       return [
           'user_id' => $claims['sub'],
           'email' => $claims['email'] ?? null,
       ];
   });
   

2. Event Listeners Listen for OIDC events (e.g., token validation failures) via the OIDCEvents facade:

   use DBP\Relay\Core\Connector\OIDCBundle\Events\OIDCEvents;
   
   OIDCEvents::listen('validation.failed', function ($event) {
       // Log or notify on failure
   });
   

3. Custom Providers Extend the OIDCProvider class to support non-standard OIDC endpoints:

   class CustomOIDCProvider extends \DBP\Relay\Core\Connector\OIDCBundle\Provider\OIDCProvider
   {
       protected function getUserInfoEndpoint(): string
       {
           return 'https://custom-provider.com/userinfo';
       }
   }
   

   Register it in the config:

   'providers' => [
       'custom' => [
           'provider_class' => CustomOIDCProvider::class,
           // ... other config
       ],
   ],