Openid Connect Provider Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • Built atop league/oauth2-server-bundle, a battle-tested OAuth2 library, ensuring compliance with OAuth2/OpenID Connect (OIDC) standards.
  • Supports Authorization Code Flow (recommended) and Implicit Flow (legacy), with RP-Initiated Logout (OIDC 1.0) and Discovery endpoints.
  • Lightweight Symfony bundle with minimal dependencies, leveraging existing Symfony services (e.g., Twig, Doctrine).
  • MIT-licensed, permissive for commercial use.

• Gaps:

  • No explicit support for PKCE (critical for modern OAuth2 security). Requires manual configuration via league/oauth2-server-bundle.
  • Limited documentation (TBD in README). Assumes familiarity with OAuth2/OIDC concepts and Symfony bundles.
  • No built-in user management—relies on custom UserClaimsResolveEvent for claim resolution (e.g., sub, email).
  • No JWT validation library included (though steverhoades/oauth2-openid-connect-server handles token generation).

• Key Use Cases:

  • Ideal for Symfony-based identity providers (e.g., internal SSO, third-party auth delegation).
  • Fits Laravel/Lumen indirectly via Symfony bridge (e.g., Symfony in Laravel), but native Laravel support would require custom integration.

Integration Feasibility

• Symfony Ecosystem:

  • Native fit: Designed for Symfony 6.4+, 7.4+, 8.0+ with PHP 8.2+ (8.5 supported).
  • Dependencies:
    • Requires league/oauth2-server-bundle (v1.x) and steverhoades/oauth2-openid-connect-server (v3.x).
    • Optional: Doctrine ORM for user storage (not enforced).
  • Configuration: Minimal YAML-based setup with route definitions for OIDC endpoints (/authorize, /token, /jwks, /end_session).

• Laravel/Lumen:

  • Non-trivial: Not Laravel-native. Options:
    1. Symfony Bridge: Use spatie/symfony-laravel to embed Symfony components.
    2. Standalone: Deploy as a microservice (e.g., Docker) and proxy requests via Laravel’s HTTP client.
    3. Fork/Adapt: Rewrite as a Laravel package (high effort; consider php-openid/light-openid-connect instead).

• Database:

  • Flexible: Uses league/oauth2-server-bundle’s storage layer (supports Doctrine, Redis, or custom adapters).
  • Schema: No migrations provided—requires manual setup for oauth2_authorization_codes, oauth2_clients, etc.

Technical Risk

• High:

  • OIDC Complexity: Misconfigurations (e.g., incorrect issuer, redirect_uris, or claim mappings) can break client integrations.
  • Security:
    • PKCE Missing: Without PKCE, vulnerable to authorization code interception. Must configure manually in league/oauth2-server-bundle.
    • Token Validation: Relies on clients to validate ID tokens (no built-in revocation or introspection endpoints).
  • Compatibility:
    • Symfony Version Lock: Dropped support for Symfony 7.2/7.3 (v0.2.4). Ensure alignment with your stack.
    • PHP 8.2+: May require updates to Laravel’s PHP version (e.g., Laravel 10+ uses PHP 8.2+).

• Medium:

  • Documentation: Lack of tutorials or troubleshooting guides may slow adoption.
  • Event System: Custom UserClaimsResolveEvent requires understanding of Symfony’s event dispatcher.

• Low:

  • License: MIT is permissive.
  • Testing: Active CI (unit tests, static analysis) suggests code quality.

Key Questions

1. Authentication Flow Requirements:

   • Do you need PKCE? If yes, how will you configure it in league/oauth2-server-bundle?
   • Are you using Implicit Flow (deprecated in OIDC 1.0)? If so, plan for deprecation.

2. User Management:

   • How will you resolve OIDC claims (e.g., sub, email)? Custom UserClaimsResolveEvent logic required.
   • Do you need userinfo endpoint? Not provided by default (would require extension).

3. Deployment:

   • Will this run as a monolith (Symfony/Laravel) or microservice? Affects routing, CORS, and scaling.
   • How will you handle HTTPS? OIDC requires TLS for all endpoints.

4. Client Integration:

   • What Relying Parties (RPs) will consume this? Test with tools like oidcdebugger.com.
   • Do you need dynamic client registration? Not supported (static clients only).

5. Observability:

   • How will you log OIDC events (e.g., token issuance, logout)? No built-in logging—requires custom instrumentation.

6. Upgrade Path:

   • How will you handle future Symfony/PHP version upgrades? Bundle drops support aggressively (e.g., PHP 8.1 removed in v0.2.3).

Integration Approach

Stack Fit

• Symfony:

  • Native: Zero friction. Follow the quick start.
  • Recommended Add-ons:
    • Doctrine: For user storage (if using ORM).
    • Symfony Security: Integrate with UserClaimsResolveEvent to sync OIDC claims with Symfony’s security system.
    • Mercure: For real-time logout notifications (if using RP-Initiated Logout).

• Laravel/Lumen:

  • Option 1: Symfony Bridge (Recommended for tight coupling):

    • Install spatie/symfony-laravel.
    • Configure Symfony as a sub-application in Laravel’s AppServiceProvider.
    • Proxy OIDC routes (e.g., /oidc/authorize) to Symfony.
    • Pros: Reuses existing Symfony bundle logic.
    • Cons: Complex setup; performance overhead.

  • Option 2: Standalone Microservice (Recommended for scalability):

    • Deploy the bundle as a separate Symfony app (e.g., Docker container).
    • Use Laravel’s HTTP client to forward requests:

      $response = Http::asForm()->post('https://oidc-service.example/token', [...]);
      

    • Pros: Isolated, scalable, easier to update.
    • Cons: Network latency; requires API gateway (e.g., Envoy, Nginx).

  • Option 3: Fork and Port (High Effort):

    • Rewrite as a Laravel package using:
      • php-openid/light-openid-connect (Laravel-native).
      • league/oauth2-server (standalone).
    • Pros: Native Laravel integration.
    • Cons: Maintenance burden; reinvents wheel.

Migration Path

1. Assessment Phase:

   • Audit existing auth flows (e.g., OAuth2, JWT, custom sessions).
   • Define OIDC requirements (e.g., claims, flows, logout).
   • Validate Symfony/Laravel compatibility (PHP/Symfony versions).

2. Proof of Concept (PoC):

   • Set up a Symfony sandbox with the bundle.
   • Test with a single client (e.g., oidcdebugger.com).
   • Verify:
     • Token issuance (/token endpoint).
     • ID token claims (sub, email, etc.).
     • RP-Initiated Logout (/end_session).

3. Integration:

   • Symfony:

     • Install dependencies:

       composer require ajgarlag/openid-connect-provider-bundle league/oauth2-server-bundle steverhoades/oauth2-openid-connect-server
       

     • Configure routes (config/routes/ajgarlag_openid_connect_provider.yaml).
     • Set up Doctrine storage (if using ORM):

       # config/packages/doctrine.yaml
       doctrine:
           orm:
               mappings:
                   LeagueOAuth2ServerBundle: ../vendor/league/oauth2-server-bundle/Resources/config/doctrine-mapping
       

     • Customize claims resolution via UserClaimsResolveEvent.

   • **Laravel (Microservice