Oauth2 Server Laravel Package

Getting Started

1. Install the package via Composer: composer require league/oauth2-server. Ensure PHP ≥8.2, openssl, and json extensions are enabled.
2. Read the official docs first at https://oauth2.thephpleague.com. The documentation is thorough, well-maintained, and includes step-by-step setup for building a fully functional OAuth2 server.
3. Start with Authorization Code Grant (most common for web apps): implement ClientEntityInterface, UserEntityInterface, and store clients/users in your DB. Use the provided AuthorizationServer class to handle token issuance and validation.
4. First production-ready use case: Protect an API endpoint by validating access tokens via ResourceServer. Accept only requests with valid Authorization: Bearer <token> headers.

Implementation Patterns

• Laravel? Use Laravel Passport, which is built on top of this package. You’ll rarely need to interact with league/oauth2-server directly—configure via migration templates and the passport:install command.
• Custom server? Extend core interfaces (ClientRepositoryInterface, UserRepositoryInterface, ScopeRepositoryInterface) and inject them into AuthorizationServer and ResourceServer via factories or DI container.
• PKCE enforcement: Always enableProofKeyForCodeExchange (PKCE) support—configure AuthorizationCodeGrant with $enableProofKey = true. This is critical for public clients (mobile/spa) and required for modern security.
• Scopes as first-class citizens: Implement ScopeEntityInterface and use finalizeScopes() in your auth code grant logic to dynamically trim scopes based on client permissions or user consent.
• Device/Long-running flows: Leverage the DeviceAuthorizationGrant (added in v9) for IoT and TV-like clients. Requires implementing DeviceCodeRepositoryInterface and a UI flow for user confirmation.

Gotchas and Tips

• Strict typing: All interfaces use scalar types (string, int, bool) and return types strictly. Implementations must match exact signatures—PHPSpec/IDE linting is highly recommended.
• Refresh token behavior changed in v9: Expired/revoked refresh tokens now return invalid_grant + HTTP 400 instead of invalid_request + HTTP 401—update your client-side error handling to treat both token types uniformly.
• Key security: Avoid storing private keys on disk. Use in-memory keys (e.g., via environment variables) with CryptKey—never write raw keys to /tmp.
• Bearer header case sensitivity: Fixed in v9.3.0 (Authorization: bearer ... now works). Ensure your middleware/proxy doesn’t uppercase headers before PHP receives them.
• Event system nuance: The library emits events (RequestAccessTokenEvent, DeviceAuthorizationEvent) only for specific grants. Use listeners to log, audit, or mutate token issuance—but remember: events are not queued by default.
• Scope finalization timing: You receive an auth code ID in finalizeScopes() only after the auth code is persisted. Don’t rely on DB writes inside finalizeScopes()—hook into persistence events (e.g., Doctrine lifecycle callbacks) instead.
• Disable implicit grant in production: Though supported, implicit grant is deprecated by OAuth 2.1 and insecure for SPAs—use Authorization Code + PKCE instead.