Oauth2 Bundle Laravel Package

Getting Started

The first thing to internalize: this is a Symfony bundle, not a Laravel package. Do not try to composer require it into a Laravel app expecting a service provider and config file — it registers through Symfony's Bundle lifecycle and depends on Symfony's DI container and Doctrine. In a Laravel context you generally consume the underlying library, league/oauth2-server (which this bundle wraps), or you reach for Laravel Passport (which historically wrapped the same library).

Minimal path that actually fits a Laravel developer:

1. Skim the repo's docs/ and src/DependencyInjection/TrikoderOAuth2Extension.php to see the config schema (grants, keys, token TTLs, storage).
2. Trace ClientCredentialsGrant end-to-end — it's the simplest flow and shows how the bundle wires a grant, a repository, and the AuthorizationServer service.
3. If you need the behavior in Laravel, either (a) port the pattern into a service provider + middleware layer, or (b) run it as its own Symfony microservice and point Laravel apps at it as resource consumers.

First real use case: a dedicated OAuth2 server for machine-to-machine or third-party access, where Laravel apps are resource consumers validating bearer tokens via league/oauth2-server's ResourceServer and BearerTokenValidator (using only the public key and a thin middleware).

Implementation Patterns

• Two responsibilities, two objects. The bundle separates OAuth2AuthorizationServer (issues tokens) from OAuth2ResourceServer (validates them). Mirror that split in Laravel: an issuing service provider and a validating middleware. Don't merge them.
• Key management. The bundle uses CryptKey with public/private key paths (or raw PEM). In Laravel, load paths from config, never commit keys, and keep them outside the webroot with restrictive permissions.
• Storage adapters. The bundle's Doctrine entity providers map cleanly to Eloquent models if you port it. You'll implement ClientRepositoryInterface, AccessTokenRepositoryInterface, RefreshTokenRepositoryInterface, AuthCodeRepositoryInterface, and ScopeRepositoryInterface, plus the resource-side equivalents.
• Grant selection. Enable only what you need: client_credentials for M2M, authorization_code + refresh_token for user-facing apps, password only for legacy migrations. Each grant type class is independently configurable in the bundle, which is a good pattern to copy.
• Firewall vs middleware. Symfony wires this into the security firewall. The Laravel equivalent is a middleware that resolves the bearer token, validates it, and attaches the client/user to the request — then scope checks happen at route level via Gate/policies.
• Scope enforcement belongs at the edge. Treat scopes as the authorization boundary in middleware. Push business logic to trust "the request is authenticated and scoped." This keeps 401 vs 403 semantics consistent and makes failures observable.
• Server/consumer split. If you follow Symfony-as-issuer, Laravel-as-consumer, keep the Laravel side deliberately dumb: public key + ResourceServer + one middleware. Resist re-implementing token issuance there.

Gotchas and Tips

• No Laravel ergonomics. No artisan vendor:publish, no facade, no auto-discovery. Composer will install it and nothing will happen — that's expected, not a bug.
• Maintenance risk. Last release was mid-2023. It wraps league/oauth2-server, which is maintained more actively. Prefer the underlying library for new work and pin carefully if you do use the bundle; watch upstream advisories.
• Passport is not a drop-in. Passport v11+ forked league's server internals. The mental model is similar but the API surface is not interchangeable. Don't copy Symfony bundle config into Passport expecting it to work.
• Key format is a footgun. CryptKey accepts a path or raw PEM, with different passphrase semantics for each. A trailing newline, missing permissions, or wrong format surfaces as an opaque "unable to read key" error. Verify with openssl rsa -in key.pem -check before blaming the code.
• JWT size and validation. JWTs are larger and require the resource server to know the signing key and kid resolution. If tokens are opaque, you need a shared or remote store — pick deliberately and document it.
• Refresh token rotation. Turn it on. A reused revoked refresh token should invalidate the entire chain. Miss this and you have a silent security hole that won't show up in happy-path tests.
• Clock skew. BearerTokenValidator enforces exp/nbf. On multi-host setups without tight NTP you get intermittent, hard-to-reproduce 401s. Log exp, nbf, and server time together when debugging this.
• Debug at the boundary. League throws OAuthServerException with specific error codes. Catch it explicitly at the AuthorizationServer/ResourceServer seam and log grant type, client, scope, and error — don't let it bubble up as a generic 500.
• Extension point worth preserving. If you port the pattern, keep the bundle's contract shape (grant objects, repository interfaces, server wrapper). Future maintainers — and cross-team Symfony developers — will recognize it immediately. Re-inventing that vocabulary costs you more than it saves.