Idp Openid Connect Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require coddin-web/idp-openid-connect-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       CoddinWeb\IdpOpenIdConnectBundle\CoddinWebIdpOpenIdConnectBundle::class => ['all' => true],
   ];
   

2. Configuration: Define your OpenID Connect (OIDC) provider settings in config/packages/coddin_web_idp_openid_connect.yaml:

   coddin_web_idp_openid_connect:
       providers:
           my_provider:
               client_id: 'your_client_id'
               client_secret: 'your_client_secret'
               issuer: 'https://your-issuer-url'
               authorization_endpoint: 'https://your-issuer-url/auth'
               token_endpoint: 'https://your-issuer-url/token'
               userinfo_endpoint: 'https://your-issuer-url/userinfo'
               scopes: ['openid', 'profile', 'email']
   

3. First Use Case: Authenticate a user via OIDC in a controller:

   use CoddinWeb\IdpOpenIdConnectBundle\Security\Authenticator\OpenIdConnectAuthenticator;
   
   class AuthController extends AbstractController
   {
       public function login(string $providerName): Response
       {
           $authenticator = $this->container->get(OpenIdConnectAuthenticator::class);
           return $authenticator->start($providerName, new Request());
       }
   }
   

Key Files to Review

• config/packages/coddin_web_idp_openid_connect.yaml: Main configuration.
• src/Security/Authenticator/OpenIdConnectAuthenticator.php: Authenticator logic.
• src/DependencyInjection/Configuration.php: Schema for configuration validation.

Implementation Patterns

Workflows

1. Authentication Flow

• Redirect to Provider:

  $authenticator->start($providerName, $request);
  

• Handle Callback:

  $authenticator->onAuthenticationSuccess($request, $token, $user);
  

• Logout:

  $authenticator->logout($request, $response);
  

2. User Provisioning

Fetch and map user data from the OIDC provider:

$userInfo = $authenticator->fetchUserInfo($accessToken);
$user = $this->userMapper->mapUser($userInfo);

3. Token Management

Refresh access tokens silently:

$refreshToken = $authenticator->getRefreshToken();
$newAccessToken = $authenticator->refreshAccessToken($refreshToken);

Integration Tips

Symfony Security Integration

• Extend the authenticator to support custom user loaders:

  class CustomOpenIdConnectAuthenticator extends OpenIdConnectAuthenticator
  {
      public function getUser($credentials, UserProviderInterface $userProvider)
      {
          // Custom logic to load user from OIDC response
      }
  }
  

API Clients

Use the bundle to secure API endpoints:

# config/packages/security.yaml
security:
    firewalls:
        api:
            pattern: ^/api
            oidc:
                provider: my_provider
                check_path: /api/login_check
                login_path: /api/login

Multi-Provider Support

Configure multiple providers in config/packages/coddin_web_idp_openid_connect.yaml:

coddin_web_idp_openid_connect:
    providers:
        google:
            # Google OIDC config
        github:
            # GitHub OIDC config

Gotchas and Tips

Pitfalls

1. Missing Endpoints: Ensure all required endpoints (authorization_endpoint, token_endpoint, userinfo_endpoint) are correctly configured. Missing endpoints will cause runtime errors.

2. Token Storage: The bundle does not persist tokens by default. Implement a custom token storage strategy (e.g., database or cache) to handle token refreshes:

   $tokenStorage = new SessionTokenStorage($request->getSession());
   $authenticator->setTokenStorage($tokenStorage);
   

3. CSRF Protection: The bundle relies on Symfony’s CSRF protection. Ensure csrf_token_manager is properly configured in your security firewall.

4. User Mapping: The default user mapper assumes a flat structure. Customize it if your OIDC provider returns nested or non-standard claims:

   $userMapper = new CustomUserMapper();
   $authenticator->setUserMapper($userMapper);
   

Debugging

1. Enable Debug Mode: Set debug: true in the bundle configuration to log detailed OIDC responses:

   coddin_web_idp_openid_connect:
       debug: true
   

2. Check Redirect URIs: Mismatched redirect_uri values between the provider and your app will cause authentication failures. Validate these in the provider’s admin panel.

3. Token Validation: Use tools like jwt.io to decode and inspect tokens for debugging.

Extension Points

1. Custom Authenticators: Extend OpenIdConnectAuthenticator to add provider-specific logic (e.g., SAML hybrid flows).

2. Event Listeners: Subscribe to events like oidc.authentication.success to modify user data before persistence:

   $dispatcher->addListener(
       'oidc.authentication.success',
       function (AuthenticationEvent $event) {
           $event->setUser($this->enrichUser($event->getUser()));
       }
   );
   

3. Token Services: Replace the default token service to implement custom token handling (e.g., JWT validation):

   $tokenService = new CustomTokenService();
   $authenticator->setTokenService($tokenService);
   

Configuration Quirks

1. Scopes: Ensure scopes like openid are included. Missing openid will break the OIDC flow.

2. State Parameter: The bundle generates a state parameter for CSRF protection. If disabled, ensure alternative protection is in place.

3. PKCE: For public clients (e.g., SPAs), enable PKCE by setting:

   coddin_web_idp_openid_connect:
       providers:
           my_provider:
               use_pkce: true