Symfony Oidc Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony-Centric Design: The bundle is tightly integrated with Symfony’s authentication system (v5.4+), leveraging its Authentication Manager and Firewall architecture. This aligns well with Symfony’s modern security stack but excludes legacy Symfony (pre-5.4) or non-Symfony PHP applications.
• OIDC Abstraction: Encapsulates OpenID Connect (OIDC) logic (token validation, user info fetching, PKCE flows) behind a clean API (OidcClientInterface), reducing boilerplate for common IdPs (Auth0, Keycloak, etc.).
• Extensibility: Supports multiple OIDC clients (e.g., for multi-tenancy or partner integrations) and custom user providers, making it adaptable to complex auth flows.
• PHP8+ Dependency: Requires PHP 8+, which may necessitate runtime upgrades if not already compliant.

Integration Feasibility

• Symfony Ecosystem: Seamless integration with Symfony’s security.yaml, UserProvider, and Firewall components. Minimal custom code needed for basic OIDC flows.
• IdP Agnosticism: Works with any OIDC-compliant provider (tested with Auth0, Keycloak, Microsoft Entra ID, etc.), but provider-specific quirks (e.g., ADFS, Entra ID) require manual configuration (see docs).
• Flexible User Mapping: Allows customization of user identification (e.g., sub, email) via user_identifier_property, accommodating diverse backend schemas (e.g., databases, LDAP).
• Remember-Me & Logout: Supports advanced features like remember-me cookies and end-session endpoints, but logout behavior is opt-in due to SSO complexities.

Technical Risk

• Symfony Version Lock: Hard dependency on Symfony 5.4+ (Authentication Manager). Migrating from older Symfony versions or non-Symfony apps requires significant refactoring (e.g., v1.x branch).
• PHP8 Requirement: May block adoption if the codebase isn’t PHP8-compatible (e.g., legacy traits, type hints).
• IdP-Specific Gotchas:
  • Microsoft Entra ID: Requires custom JWKS handling (documented in docs/ms-entra-id.md).
  • ADFS: Needs allow_discovery_access_token_issuer: true for on-prem deployments.
  • Non-Standard IdPs: Untested providers may expose edge cases (e.g., malformed userinfo responses).
• Caching Dependencies: Uses Symfony Cache for JWKS/well-known config caching, adding a dependency on symfony/cache if not already present.
• Token Leeway: Default token_leeway_seconds: 300 may cause issues with strict clock-skew environments (e.g., Kubernetes with misconfigured NTP).

Key Questions

1. Symfony Compatibility:
   • Is the application on Symfony 5.4+ with the Authentication Manager enabled? If not, can you upgrade or use v1.x?
   • Are you using Symfony Flex? If so, the bundle auto-generates .env and drenso_oidc.yaml files.
2. IdP Selection:
   • Which IdP(s) are you integrating with? Are there known issues (e.g., Entra ID, ADFS)?
   • Do you need support for multiple OIDC clients (e.g., for different tenants or partner logins)?
3. User Backend:
   • How are users stored (database, LDAP, etc.)? Will you need to implement OidcUserProviderInterface?
   • What user identifier (sub, email, etc.) should be used for authentication?
4. Advanced Features:
   • Do you need remember-me functionality? If so, is the REMEMBERME cookie acceptable?
   • Should logout trigger end-session endpoints? Are you aware of SSO limitations?
5. Performance:
   • Will you use caching for JWKS/well-known configs? If so, is symfony/cache already in use?
   • What’s the expected token validation leeway? Should token_leeway_seconds be adjusted?
6. Monitoring:
   • How will you handle OIDC-related errors (e.g., token validation failures, IdP downtime)? Are there fallback mechanisms?

Integration Approach

Stack Fit

• Primary Fit: Symfony 5.4+ applications requiring OIDC authentication with minimal custom code.
• Secondary Fit:
  • Multi-IdP Environments: Supports multiple OIDC clients (e.g., Auth0 for employees, Keycloak for partners).
  • Custom User Providers: Works with databases, LDAP, or headless user backends via OidcUserProviderInterface.
• Non-Fit:
  • Legacy Symfony: Pre-5.4 or without Authentication Manager (use v1.x branch).
  • Non-Symfony PHP: Requires significant rework to adapt the bundle’s Symfony-specific components.
  • Non-OIDC Auth: If using SAML or other protocols, this bundle is irrelevant.

Migration Path

1. Prerequisites:
   • Upgrade to Symfony 5.4+ and enable enable_authenticator_manager: true in security.yaml.
   • Ensure PHP 8+ compatibility (check for deprecated functions, type hints).
   • Install dependencies:

     composer require drenso/symfony-oidc-bundle
     

2. Configuration:
   • IdP Setup: Register your app in the IdP (e.g., Auth0, Keycloak) and note:
     • well_known_url (e.g., https://your-idp.com/.well-known/openid-configuration)
     • client_id and client_secret.
   • Symfony Config:
     • Update config/packages/drenso_oidc.yaml with IdP credentials.
     • Configure the firewall in security.yaml:

       firewalls:
         main:
           oidc:
             client: default
             user_identifier_property: email  # Optional: override 'sub'
       

3. User Provider:
   • Implement OidcUserProviderInterface in your user provider:

     class CustomUserProvider implements OidcUserProviderInterface {
         public function ensureUserExists(string $userIdentifier, OidcUserData $userData, OidcTokens $tokens): UserInterface {
             // Create/update user in your backend.
         }
         public function loadOidcUser(string $userIdentifier): UserInterface {
             // Load user by identifier (e.g., from DB).
         }
     }
     

   • Register the provider in security.yaml:

     providers:
       oidc_provider:
         id: App\Security\CustomUserProvider
     

4. Routing:
   • Add a route to trigger OIDC login (e.g., /login_oidc):

     #[Route('/login_oidc', name: 'login_oidc')]
     public function login(OidcClientInterface $oidcClient): RedirectResponse {
         return $oidcClient->generateAuthorizationRedirect();
     }
     

5. Testing:
   • Test with the IdP’s authorization code flow (PKCE enabled by default).
   • Verify token validation, user mapping, and post-auth redirects.
   • Check edge cases: token expiration, IdP downtime, malformed responses.

Compatibility

• Symfony Components:
  • Requires symfony/security-bundle, symfony/http-client, and symfony/cache (for caching).
  • Uses Symfony’s PropertyAccess for dynamic user identifier resolution.
• IdP Compatibility:
  • Tested IdPs: Auth0, Keycloak, Entra ID, ADFS, OpenConext.
  • Untested IdPs: May require adjustments (e.g., custom well_known_parser).
• Protocol Compliance:
  • Supports OIDC Core 1.0, PKCE, JWT validation, and userinfo endpoint calls.
  • Non-Standard Extensions: Some IdPs (e.g., ADFS) need flags like allow_discovery_access_token_issuer.

Sequencing

1. Phase 1: Setup
   • Configure IdP and Symfony bundle.
   • Implement OidcUserProviderInterface.
2. Phase 2: Basic Auth
   • Test login/logout flows with the default client.
   • Validate token handling and user mapping.
3. Phase 3: Advanced Features
   • Enable remember-me (configure enable_remember_me and REMEMBERME cookie).
   • Enable logout (configure enable_end_session_listener).
   • Add multiple OIDC clients if needed.
4. Phase 4: Optimization
   • Enable caching for JWKS/well-known configs.
   • Adjust token_leeway_seconds based on observed clock skew.
5. Phase 5: Monitoring
   • Log OIDC events (e.g., token failures, IdP errors).
   • Set