## Getting Started

### Minimal Setup for First Use
1. **Installation**
   ```bash
   composer require ajgarlag/openid-connect-provider-bundle

Ensure league/oauth2-server-bundle is installed (required dependency).

Enable Routes Add to config/routes/ajgarlag_openid_connect_provider.yaml:

ajgarlag_openid_connect_provider:
    resource: '@AjgarlagOpenIDConnectProviderBundle/config/routes.php'
    type: php

Configure Discovery Endpoints Update config/packages/ajgarlag_openid_connect_provider.yaml:

ajgarlag_openid_connect_provider:
    discovery:
        authorization_endpoint_route: 'oauth2_authorize'
        token_endpoint_route: 'oauth2_token'
        jwks_endpoint_route: 'openid_connect_jwks'
        end_session_endpoint_route: 'openid_connect_end_session'

First Test Case Use Postman/cURL to hit the discovery endpoint:
```
curl http://your-app/.well-known/openid-configuration
```
Verify responses include authorization_endpoint, token_endpoint, and jwks_uri.

Implementation Patterns

Core Workflows

Authorization Code Flow

Trigger /oauth2/authorize with response_type=code.

Use UserClaimsResolveEvent to customize claims before token issuance:

// src/EventListener/CustomClaimsListener.php
use Ajgarlag\OpenIDConnectProviderBundle\Event\UserClaimsResolveEvent;

public function onUserClaimsResolve(UserClaimsResolveEvent $event): void {
    $user = $event->getUser();
    $claims = $event->getClaims();
    $claims['custom_claim'] = $user->getCustomAttribute();
    $event->setClaims($claims);
}

RP-Initiated Logout
- Redirect clients to /openid_connect_end_session with id_token_hint and post_logout_redirect_uri.
- Configure default logout path in config/packages/ajgarlag_openid_connect_provider.yaml:
```
ajgarlag_openid_connect_provider:
    end_session:
        cancel_logout_default_path: '/logout-success'
```

JWKS Management

Auto-generated keys stored in config/packages/ajgarlag_openid_connect_provider.yaml:

ajgarlag_openid_connect_provider:
    jwks:
        private_key_path: '%kernel.project_dir%/config/jwks/private.pem'
        public_key_path: '%kernel.project_dir%/config/jwks/public.pem'

Rotate keys via CLI:

php bin/console ajgarlag:openid-connect:generate-keys

Integration Tips

Symfony Security Integration Use Ajgarlag\OpenIDConnectProviderBundle\Security\OpenIDConnectAuthenticator for seamless auth:

# config/packages/security.yaml
firewalls:
    main:
        custom_authenticators:
            - Ajgarlag\OpenIDConnectProviderBundle\Security\OpenIDConnectAuthenticator

Custom Grant Types Extend steverhoades/oauth2-openid-connect-server grants:

// src/OpenIDConnect/Grant/RefreshTokenGrant.php
use Steverhoades\OAuth2\OpenIDConnect\Grant\RefreshTokenGrant as BaseGrant;

class CustomRefreshTokenGrant extends BaseGrant {
    public function validate(): bool {
        // Custom logic
        return true;
    }
}

Testing Use Ajgarlag\OpenIDConnectProviderBundle\Tests\Functional\WebTestCase for endpoint tests:

use Ajgarlag\OpenIDConnectProviderBundle\Tests\Functional\WebTestCase;

class OpenIDConnectTest extends WebTestCase {
    public function testAuthorizationEndpoint(): void {
        $client = static::createClient();
        $crawler = $client->request('GET', '/oauth2/authorize');
        $this->assertResponseIsSuccessful();
    }
}

Gotchas and Tips

Common Pitfalls

Missing nonce Handling
- If nonce is missing in the auth request, the ID token will fail validation.
- Fix: Ensure nonce is passed via state parameter or configured in the client.
Client Credentials Grant + ID Tokens
- The bundle avoids issuing ID tokens for client credentials grants (fixed in v0.2.2).
- Workaround: Use authorization code flow for OIDC flows.
Session ID (sid) Mismatches
- RP-Initiated Logout requires exact sid matching.
- Debug: Check SessionSidTrait::getSid() for consistency.
JWKS Endpoint Caching
- Clients cache JWKS for hours. Rotate keys carefully:
```
php bin/console ajgarlag:openid-connect:generate-keys --force
```

Debugging Tips

Enable Verbose Logging

# config/packages/monolog.yaml
handlers:
    openid_connect:
        type: stream
        path: '%kernel.logs_dir%/openid_connect.log'
        level: debug
        channels: ['openid_connect']

Inspect Tokens Use Ajgarlag\OpenIDConnectProviderBundle\Token\IdToken to decode:
```
$token = new IdToken($idTokenString);
$claims = $token->getClaims();
```

Extension Points

Custom Claims Resolution Subscribe to UserClaimsResolveEvent (as shown in Implementation Patterns).
Custom Grant Validation Override steverhoades/oauth2-openid-connect-server grants (see Integration Tips).

Endpoint Customization Extend controllers (e.g., EndSessionController) to add logic:

// src/OpenIDConnect/Controller/CustomEndSessionController.php
use Ajgarlag\OpenIDConnectProviderBundle\Controller\EndSessionController as BaseController;

class CustomEndSessionController extends BaseController {
    protected function getPostLogoutRedirectUri(): string {
        // Custom logic
        return parent::getPostLogoutRedirectUri();
    }
}

Key Management Implement Ajgarlag\OpenIDConnectProviderBundle\Key\KeyManagerInterface for custom storage:

class CustomKeyManager implements KeyManagerInterface {
    public function getKey(): Key {
        // Load from custom storage
    }
}

Configuration Quirks

Route Overrides Ensure authorization_endpoint_route and token_endpoint_route match your league/oauth2-server-bundle routes.
PHP Version Compatibility
- Dropped: PHP 8.1 (v0.2.3+).
- Supported: PHP 8.2–8.5 (check composer.json).
Symfony Version Lock
- Dropped: Symfony 7.2/7.3 (v0.2.4+).
- Supported: Symfony 6.4, 7.4, 8.0.

Performance Notes

JWKS Endpoint: Add caching headers:

// src/OpenIDConnect/Controller/JwksController.php
$response->headers->set('Cache-Control', 'public, max-age=3600');

Token Generation: Avoid heavy claim resolution in UserClaimsResolveEvent for high-traffic flows.

---

Openid Connect Provider Bundle Laravel Package