Oauth Laravel Package

Getting Started

Read the composer.json before anything else. This package is explicitly a frontend layer — it contains routes, controllers, and views that sit on top of a separate OAuth2 server package. You cannot evaluate or use it in isolation; the underlying server dependency (lucadegasperi/oauth2-server-laravel, rinvex/laravel-oauth-server, or similar — confirm from require) determines the actual token/grant behaviour. Most of your debugging time will be spent there, not here.

Minimal setup:

composer require cortex/oauth
php artisan vendor:publish --provider="Cortex\Oauth\Providers\OauthServiceProvider"
php artisan migrate

• Register the provider if not auto-discovered, and make sure cortex/auth (and its ACL layer) is installed first — this package almost certainly assumes Cortex's authentication and ability/role model is already in place.
• Publish config to config/cortex/oauth.php (verify the exact path from mergeConfigFrom in the provider) and check the route prefix, middleware stack, and view namespace.
• Look first at: src/Providers/, src/Http/Controllers/, routes/, and the migrations. The controllers are thin CRUD wrappers around the OAuth server's client/scope/token repositories — that's the whole package.

First use case: stand up an admin-facing screen where a user with the right ability registers an OAuth client (name, redirect URI, granted scopes), receives a client ID/secret, and then exchanges it for a token via the underlying server's oauth/token endpoint. Confirm the round trip end-to-end before wiring anything else.

Implementation Patterns

Treat it as admin self-service, not as your API auth layer. The pattern is: this package gives you the management UI/endpoints; your actual API authentication is the oauth middleware from the server package, applied to your own route groups.

Route::middleware('oauth')->group(function () {
    Route::get('/api/me', fn () => auth()->user());
});

Permissions are Cortex ACL abilities. Expect checks like cortex.oauth.clients.create / .update / .delete enforced via middleware or $this->authorize(). Seed those abilities and attach them to roles, otherwise every controller action 403s and it looks like a routing bug.

Override, don't fork. Because the package is archived, assume you'll need to change behaviour. Favour:

• Published config for prefix/middleware/limits.
• view()->addNamespace('cortex/oauth', resource_path('views/vendor/cortex/oauth')) for UI overrides.
• Rebinding the controller or repository in a service provider if the CRUD logic doesn't fit.

Use it as a reference implementation. Its real day-to-day value is showing how to wire an OAuth client registry into a Laravel admin panel — client model, scope model, form requests, policy checks. If you need custom grant flows or non-standard token lifetimes, copy that structure into your app rather than extending this.

Pair with cortex/auth guards. Keep the browser session guard for the admin UI and the OAuth guard for API requests; don't try to share one guard across both.

Gotchas and Tips

• Archived and effectively unmaintained (2 stars, 0 dependents). Expect pinned, old dependency constraints. Check Laravel version compatibility first — if you're on Laravel 8+, a straight composer require will likely fail resolution or drag in a dead transitive dependency. Budget time for composer why-not archaeology.
• Seriously consider Laravel Passport or Sanctum instead. Passport covers the same ground (clients, scopes, grants, token management) with active maintenance. Only use this package if you're already committed to the Cortex stack.
• CSRF on the token endpoint. If you route token issuance through your web middleware group, VerifyCsrfToken will reject POSTs from external clients. Exclude oauth/token in $except.
• Migration order matters. The package's tables reference Cortex user/ability tables. Publish and run migrations in dependency order, or you'll get foreign key failures that read as unrelated errors.
• Scope enforcement is a common silent hole. The management UI lets you attach scopes to clients, but unless the resource server validates them on each request, tokens carry scopes that mean nothing. Test with a token lacking a required scope and confirm you get a 403, not a 200.
• Client secrets are stored in plaintext in the clients table, as with most packages of this era. Don't log the table, and rotate on exposure.
• Route collisions. The package claims a prefix (likely oauth or admin/oauth). Run php artisan route:list --path=oauth after install and check it doesn't shadow your own API routes.
• Debugging: the server package swallows grant exceptions into generic OAuth error responses. Temporarily log the exception in the server's exception handler — otherwise "invalid_grant" tells you nothing.
• Config caching can mask a route/middleware change; always php artisan config:clear and route:clear when toggling the package's settings.