Laravel Passport Modern Scopes – Attribute-Based OAuth Scope Enforcement

Source: Dev.to

Laravel Passport traditionally enforces OAuth scopes at the routing level, usually via middleware definitions in route files. While this works, it often leads to:

• Authorization rules scattered across routes
• Controllers coupled to infrastructure concerns
• Duplicated or hard‑to‑review scope requirements
• Reduced clarity as APIs grow

Laravel Passport Modern Scopes introduces a different approach.

The idea: declare scopes where they matter

Instead of wiring scopes into routes, this package allows you to declare OAuth scope requirements directly on controllers or controller actions using PHP 8 attributes. Authorization intent lives next to the code it protects, while Passport remains fully responsible for authentication and token validation.

Example

use N3XT0R\PassportModernScopes\Support\Attributes\RequiresScope;
use N3XT0R\PassportModernScopes\Support\Attributes\RequiresAnyScope;

#[RequiresScope('users:read')]
final class UserController
{
    public function index()
    {
        // Requires users:read
    }

    #[RequiresAnyScope('users:update', 'users:write')]
    public function update()
    {
        // Requires at least one of the given scopes
    }
}

A single middleware inspects controller attributes at runtime and enforces them using Laravel Passport’s native tokenCan checks. Authentication itself remains the responsibility of your configured guard (e.g. auth:api).

What this package does

• Enables attribute‑based OAuth scope enforcement
• Keeps routes clean and infrastructure‑agnostic
• Makes authorization requirements explicit and discoverable
• Works with Passport’s existing scope validation
• Requires no changes to Passport internals

Scopes are declared, not wired.

Why attributes?

• Declarative and explicit
• No duplication between routes and controllers
• Easier to reason about during code review
• Friendly to static analysis and documentation tools
• No magic strings scattered across route definitions

This keeps authorization intent separate from HTTP wiring.

What this package does not do

• ❌ It does not replace Laravel Passport
• ❌ It does not implement authentication
• ❌ It does not introduce custom guards
• ❌ It does not enforce business rules

It only resolves and enforces declared OAuth scope requirements.

Where this fits architecturally

Laravel Passport Modern Scopes is intentionally small and focused. It pairs well with:

• Structured scope models (e.g. resource:action)
• Domain‑level authorization logic
• Admin tooling that manages scopes centrally

It can be used standalone or alongside higher‑level authorization libraries.

Installation

composer require n3xt0r/laravel-passport-modern-scopes:^2.0

The middleware is automatically registered via the package’s service provider.

Final thoughts

This package is about clarity, not abstraction. If you prefer:

• Explicit authorization requirements
• Clean routes
• Controllers that express intent clearly

then attribute‑based scope enforcement can be a very natural fit.

Feedback and discussion are welcome.