Oauth2 Server Configuration Bundle Laravel Package

Getting Started

This bundle is the configuration/endpoints layer for the Spomky-Labs Symfony2 OAuth2 stack. It doesn't issue tokens itself — it exposes the metadata endpoints (OpenID Connect discovery document and the JWKS/key set) that let clients and resource servers auto-configure against your authorization server. Treat it as glue between spomky-labs/oauth2-server-bundle, the jose key-management component, and your firewall.

Minimal setup:

1. Install with Composer, pinning to a Symfony 2.8-compatible release:

   composer require spomky-labs/oauth2-server-configuration-bundle
   

2. Register in app/AppKernel.php:

   new SpomkyLabs\OAuth2ServerConfigurationBundle\SpomkyLabsOAuth2ServerConfigurationBundle(),
   

   Make sure it is loaded after the OAuth2 server bundle and the JWT/Jose bundle it depends on.
3. Import the bundle's routing in app/config/routing.yml — it ships the /.well-known/openid-configuration and JWKS routes:

   spomky_labs_oauth2_server_configuration:
       resource: "@SpomkyLabsOAuth2ServerConfigurationBundle/Resources/config/routing.xml"
       prefix: /
   

4. Configure the issuer and key set in config.yml under the bundle's config key. The one thing you cannot skip is a correct absolute issuer URL and a jose key set service — the discovery document is generated from those.

Where to look first: the bundle's DependencyInjection/Configuration.php (tells you the exact config tree for this version), Resources/config/routing.xml (the exposed routes), and the controller/service that assembles the discovery document. Those three files answer 90% of "what can I configure" questions.

First use case: expose https://your-app/.well-known/openid-configuration so a mobile/web client library can discover authorization_endpoint, token_endpoint, jwks_uri, and supported scopes — instead of hardcoding them in every client.

Implementation Patterns

Pair it with oauth2-server-bundle, not standalone. The configuration bundle only describes your server. Your token issuance, grant types, and client storage live in the OAuth2 server bundle; the metadata you publish must match what that bundle actually exposes. Keep them in one config file so the issuer, endpoint paths, and scopes stay in sync.

Discovery-first client wiring. Once the discovery document is live, point clients at the issuer URL rather than individual endpoints. This is the main day-to-day payoff: rotate or rename an endpoint, update the bundle config, and clients re-discover it.

Publish JWKS for resource servers. Configure the bundle with your jose key set and let it serve the public keys. Resource servers and ID-token consumers then validate signatures by fetching jwks_uri — you avoid distributing PEMs out of band. Keep the key set service shared with the token-signing service so the published keys are exactly the signing keys.

Custom metadata via config. Most deployments need to override issuer, add scopes_supported, response_types_supported, grant_types_supported, and claims_supported to match the real server behavior. Do this in YAML rather than overriding controllers; that keeps upgrades tractable.

Environment-specific config. The issuer must differ per environment (https://auth.staging... vs https://auth.example.com). Parameterize the issuer and key material per environment and never let staging keys leak into production JWKS.

Firewall integration. Leave the .well-known routes public (they must be unauthenticated); only the token/authorize endpoints behind your OAuth2 server bundle's firewall logic. A common pattern is to whitelist ^/.well-known/ and ^/jwks in security.yml access_control.

Gotchas and Tips

• This is legacy. It targets Symfony 2.x and the spomky-labs/oauth2-server-bundle of that era (pre-web-token/jose split). With zero stars and no dependents, expect no maintenance and sparse docs — budget time to read the source, and consider depending on the OAuth2 server bundle directly for new work.
• PHP version ceilings. The dependency chain (old jose, old OAuth2 server) often caps at PHP 7.0/7.1 and conflicts with modern Symfony. If Composer drags in an ancient jose version, that's the constraint, not a bug in your config.
• Issuer mismatch is the #1 failure. If the issuer in config doesn't exactly match the URL clients use (scheme, host, trailing-slash), discovery and ID-token iss validation break silently. Use a single parameter everywhere.
• Caching the discovery document. It's static per deploy — let it be cached, but make sure your proxy/CDN cache is invalidated when you change keys or scopes. A stale JWKS after key rotation causes signature-validation failures that look like "invalid token" downstream.
• Key rotation needs the JWKS live before you sign with a new key. Publish the new public key in the key set first, then start signing; otherwise consumers fetching jwks_uri can't verify new tokens.
• Routing collisions. The /.well-known/ prefix and the bundle's route names can clash with app routes or other well-known handlers; import with a narrow prefix or explicit route names if you get duplicate-route errors.
• Debugging metadata. Hit the discovery endpoint directly with curl and diff it against your OAuth2 server bundle config — most "client can't connect" reports are a missing scopes_supported or a wrong token_endpoint.
• Extension point. If you need dynamic metadata (e.g., tenant-specific issuers), extend the metadata service rather than the controller; overriding the controller ties you to the bundle's internals and breaks on any minor bump.