Oauth2 Server Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package—there is no service provider, no auto-discovery, no publishable config. It wraps league/oauth2-server (the v4/v5-era API) and adds Doctrine-backed storage, grant configuration, and Symfony DI wiring. In a Laravel codebase the direct equivalent is Laravel Passport; the only reason to read this bundle is if you've inherited a Symfony app using it, or you want to borrow its storage/grant separation.

Minimal path in a Symfony app:

composer require michalkvasnicak/oauth2-server-bundle

1. Register the bundle in AppKernel (or config/bundles.php on Symfony 3.4+).
2. Import the oauth2_server config block and create the Doctrine schema for the bundle's Client, AccessToken, RefreshToken, and AuthCode entities.
3. Look first at vendor/michalkvasnicak/oauth2-server-bundle/README.md, then DependencyInjection/Configuration.php (every config key), Resources/config/services.xml (service IDs), and the Entity/ directory.
4. Check composer.json for the pinned league/oauth2-server version—the API changed significantly between v4/v5 and modern v7/v8.

First use case: client-credentials token for service-to-service auth. Insert a client row, POST to your token endpoint with grant_type=client_credentials and HTTP Basic client credentials, receive JSON access_token, then validate the Bearer token on protected routes via the bundle's resource-server service.

Implementation Patterns

• Token endpoint controller. Inject the authorization server service, build a PSR-7 ServerRequestInterface (use symfony/psr-http-message-bridge), call handleTokenRequest(), and convert the result to a Symfony response. Catch OAuthServerException and render its payload/status—do not let it bubble up as a 500.
• Authorization-code flow. Validate the authorize request, redirect to your own login/consent UI, stash the pending request in session, and on approval call completeAuthorizationRequest(). Keep consent decisions explicit and auditable; don't auto-approve.
• Resource server / middleware. On each API request, extract Authorization: Bearer …, call the resource server's validation, and attach client, user, and scopes to the Symfony request attributes. Enforce scopes per route in a listener or voter—authorization-server scope config alone doesn't protect endpoints.
• Client provisioning. Build a console command or admin CRUD over the Client entity. Generate random secrets, hash them at rest if storage supports it, and constrain allowed grant types and redirect URIs per client.
• Custom Doctrine storage. Implement the league storage interfaces (client, access token, refresh token, auth code, scope) as services and point config at them. This is the primary extension point when you already have user/client tables.
• Custom grants. Implement GrantTypeInterface, register it as a service, add it to the configured grant list. Useful for social-login or device-style grants the bundle doesn't ship.
• Events for auditing. Hook the bundle's authorization/token request events to log issuances, revoke tokens on password change, and emit metrics. Keep business logic out of the endpoint controllers.
• Laravel translation. These patterns map cleanly onto a Passport AuthServiceProvider plus custom grant and middleware. The storage-interface separation is the reusable idea.

Gotchas and Tips

• Abandonment risk is the headline. Four stars, zero dependents, no recent activity. It targets Symfony 2.8/3.x and PHP 5.6/7.0-era league/oauth2-server. Expect Composer conflicts on PHP 8 / Symfony 5+. Do not introduce it into a new project, and do not attempt to install it in Laravel—there's nothing to wire it up.
• Verify config keys against source. Token TTLs, grant list, storage driver, and key paths are easy to misname, and validation is thin. Use bin/console debug:config oauth2_server and debug:container oauth2_server before debugging behavior.
• Crypt keys. JWT access tokens need a CryptKey (public/private). Generate with openssl, keep the private key out of VCS, and set restrictive permissions. A missing or malformed key usually surfaces as an opaque 500 rather than a config error.
• Exception handling. league/oauth2-server signals all client errors via OAuthServerException. Uncaught, you get HTML error pages instead of OAuth JSON (error, error_description). Wrap the token and authorize endpoints and return $e->getPayload() with $e->getHttpStatusCode().
• Redirect URIs are exact-match. No wildcards in league. Register each environment's callback URL; a trailing slash mismatch silently rejects the authorize request.
• Security defaults. Leave password and implicit grants disabled; require HTTPS; rotate refresh tokens; keep access tokens short-lived; hash client secrets; check scopes on the resource server.
• Doctrine schema. The schema tool may not pick up bundle entities unless mapped—write explicit migrations. Changing the configured table prefix later orphans every issued token.
• Debugging. Log grant type and client ID (never secrets or token values), replay with curl -u client:secret -d grant_type=client_credentials …, and check clock skew for exp/iat validation failures.
• Prefer extension over forking. Use storage interfaces, grant services, and events. If you need modern OAuth features (PKCE, newer grant interfaces), migrate to league/oauth2-server-bundle on the server side, Passport in Laravel, or the current league/oauth2-server wired manually. The storage/grant/event separation here is worth copying even when the code isn't.