Oauth2 Server Authorization Endpoint Laravel Package

Getting Started

This is a component, not an application. It implements the OAuth2 authorization endpoint, but depends on the spomky-labs/oauth2-server core for the server object, repositories, and response types. Budget for the whole stack, not just this package.

• composer require spomky-labs/oauth2-server-authorization-endpoint spomky-labs/oauth2-server
• Add a PSR-7 implementation (nyholm/psr7 is the smallest modern option; the package's README will likely suggest zendframework/zend-diactoros from its era).
• Read composer.json first — check the PHP constraint and last release date before you design anything around it.
• Then read src/ and enumerate every interface the endpoint type-hints. That list is your integration contract: client repository, scope repository, resource-owner/account provider, authorization-code repository. You will implement all of them.
• First use case: a single GET|POST /oauth/authorize route. GET validates the authorization request and renders a login/consent screen; POST issues an authorization code and 302s back to the client's registered redirect_uri.

Laravel wiring has no service provider. Bind the endpoint in a provider, convert Illuminate\Http\Request to a PSR-7 request, invoke the endpoint, and synthesize an Illuminate\Http\Response from the PSR-7 response (copy status and Location/Content-Type headers; the body is usually empty for redirects).

Implementation Patterns

• Two-phase consent. On GET, validate the request and stash it (session or signed payload) so the POST completes it without re-trusting client-supplied client_id/redirect_uri. On POST, look up the stashed request, apply the user's decision, and only then issue a code.
• Grant dispatch. Enable response_type=code and nothing else. The implicit (token) and hybrid responses are legacy; if the endpoint registers them, prune them from the grant/response-type list.
• Repository semantics. Authorization codes: single-use, TTL ≤ 10 minutes, stored hashed, with columns for client_id, redirect_uri, scope, code_challenge, code_challenge_method, expires_at, used_at. The token endpoint must re-check all of these.
• Error routing. Split failures into "safe to redirect" (invalid_scope, access_denied, unsupported_response_type) versus "render locally" (unknown client_id, unregistered redirect_uri). Never redirect to an unvalidated URI, even to report an error.
• PKCE. If the endpoint does not validate code_challenge, wrap it: a decorator validates and persists the challenge before delegating, and the token endpoint verifies code_verifier. This is the most common thing you'll need to add yourself.
• Testing. Feature-test the redirect: hit /oauth/authorize with a full query string, assert 302 and parse code/state from Location. Assert the DB row exists, then assert a denial POST returns error=access_denied with the same state.
• Multi-client. Resolve the client by client_id from your DB inside the client repository; cache the registered redirect URI list.

Gotchas and Tips

• Maintenance risk is the headline. Low stars, zero dependents, pre-PHP-8 codebase. Inspect the last commit; expect to fork or patch type-hints and deprecated constructs to run on modern PHP.
• Redirect URI matching is exact string comparison per RFC 6749. No trailing-slash normalization, no host case-folding beyond what the endpoint already does. Cosmetic client mismatches become invalid_request support tickets.
• state must be echoed verbatim on both success and error redirects. Dropping it silently breaks every client relying on it for CSRF protection.
• Denial is a first-class path. User rejects consent → error=access_denied redirect. Don't let that fall through to a 500.
• Never log the authorization code or the full redirect URL — the code lives in the query string. Redact at the logger boundary.
• Open-redirect footgun. If the endpoint falls back to a configured default URI when redirect_uri is absent, disable that fallback. Registered-URI-only.
• Session re-binding. If you stash the request between GET and POST, re-assert the authenticated user ID on POST; otherwise a session swap can approve a different user's request.
• Debugging is header-only. The whole flow is a 302. Log the validation outcome and the final Location (code redacted) at debug level, and capture the PSR-7 response in tests rather than trusting the browser.
• Extend by substitution, not patching. The package is interface-driven by design — swap repositories, the user provider, or implement the response-type interface for new flows. Editing vendor code will bite on the next (however unlikely) update.
• Migration fallback. If the maintenance risk outweighs the work, league/oauth2-server (with a PSR-7 bridge) or Laravel Passport implement the same authorization-code flow and are actively maintained. Stay on this package only if you're already committed to the Spomky-Labs core elsewhere.