Laravel Passport Modern Scopes Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: The package extends Laravel Passport’s OAuth2 scopes with attribute-based access control (ABAC), enabling fine-grained permission enforcement (e.g., user:read:own, user:read:all). This fits well in B2B, SaaS, or multi-tenant systems where role-based scopes (e.g., admin, user) are insufficient.
• Passport Synergy: Leverages Passport’s existing token/grant system, reducing architectural overhead. Scopes are dynamically resolved via callbacks or policies, aligning with Laravel’s authorization patterns (e.g., Gates/Policies).
• Extensibility: Supports custom scope resolvers, allowing integration with existing RBAC/ABAC systems (e.g., Casbin, Entrust) or database-backed policies.
• Statelessness: Scopes are enforced at the token level, avoiding session/state management complexities.

Integration Feasibility

• Low Coupling: Modifies Passport’s scope validation middleware (Passport::scope) without requiring core Passport changes. Backward-compatible with existing scope-based auth.
• Dependency Risks: Relies on:
  • Laravel Passport (≥v10, likely due to 2026 release date).
  • PHP 8.1+ (assumed by modern Laravel versions).
  • No heavy dependencies (e.g., no queue/worker requirements).
• Database Schema: Minimal impact—only requires scope definitions (stored in oauth_scopes or custom tables). No migrations provided; assumes manual setup or Passport’s default schema.

Technical Risk

Key Questions

1. Scope Definition Strategy:
   • Will scopes be hardcoded, database-driven, or hybrid? How will they map to user attributes (e.g., department, role)?
2. Policy Resolution:
   • How will custom resolvers (e.g., App\Policies\ScopeResolver) be structured? Will they integrate with existing Gates/Policies?
3. Fallback Behavior:
   • What happens if a scope cannot be resolved? Deny access? Log and allow? Custom error?
4. Testing:
   • Are there pre-built tests for scope validation? How will negative cases (e.g., missing attributes) be handled?
5. Auditability:
   • How will scope enforcement be logged/audited (e.g., for compliance)?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Passport: Required (OAuth2 provider).
  • Laravel Framework: ≥9.x (PHP 8.1+).
  • Authorization: Complements Gates, Policies, or Entrust.
• Non-Laravel Systems:
  • Not directly applicable—requires Passport integration. Could wrap in a microservice for polyglot stacks.
• Alternatives Considered:
  • Spatie Laravel-Permission: RBAC-focused; lacks ABAC dynamism.
  • Custom Middleware: More verbose; this package abstracts complexity.

Migration Path

1. Prerequisites:
   • Install Passport (composer require laravel/passport).
   • Publish Passport migrations (php artisan passport:install).
2. Package Installation:

   composer require n3xt0r/laravel-passport-modern-scopes
   php artisan vendor:publish --provider="N3xt0r\ModernScopes\ModernScopesServiceProvider"
   

3. Configuration:
   • Define scope resolvers in config/auth.php or service provider.
   • Example resolver:

     public function resolve($user, $scope)
     {
         return $user->role === 'admin' && $scope === 'user:read:all';
     }
     

4. Middleware:
   • Replace Passport::scope() with Passport::modernScope() in app/Http/Kernel.php.
5. Testing:
   • Validate scopes via Passport::tokensCan() or custom assertions.

Compatibility

• Passport Versions: Likely v10+ (2026 release date suggests alignment with Laravel 10+).
• PHP Versions: 8.1+ (Laravel 9+).
• Database: Works with MySQL, PostgreSQL, SQLite (Passport’s default).
• Caching: Scopes may benefit from Redis caching if resolvers are expensive.

Sequencing

1. Phase 1: Replace static scopes with modern scopes in a non-critical API.
2. Phase 2: Implement custom resolvers for business logic (e.g., department-based access).
3. Phase 3: Integrate with monitoring (e.g., log denied scope requests).
4. Phase 4: Deprecate old scope middleware if fully migrated.

Operational Impact

Maintenance

• Proactive Tasks:
  • Scope Definition Updates: Modify resolvers when business rules change (e.g., new user attributes).
  • Passport Updates: Test against new Passport/Laravel versions.
• Reactive Tasks:
  • Resolver Bugs: Debug false positives/negatives in scope resolution.
  • Performance: Optimize slow resolvers (e.g., database queries).

Support

• Debugging:
  • Logs: Enable Passport::enableScopeLogging() to trace denied requests.
  • Tools: Use telescope or laravel-debugbar to inspect scope resolution.
• Documentation:
  • Internal Wiki: Document scope-resolver contracts and edge cases.
  • Examples: Provide real-world resolver snippets (e.g., tenant-aware scopes).
• Community:
  • Limited: No stars/issues; rely on GitHub discussions or Laravel forums.

Scaling

• Horizontal Scaling:
  • Stateless: Scopes resolved per-request; no shared state.
  • Caching: Cache resolver results (e.g., Cache::remember) for high-throughput APIs.
• Vertical Scaling:
  • Resolver Complexity: Heavy resolvers (e.g., graph traversals) may need queue workers.
• Load Testing:
  • Simulate high TPS to validate scope resolution latency.

Failure Modes

Ramp-Up

• Onboarding Time: 1–3 days for basic integration; 1 week for custom resolvers.
• Training Needs:
  • Developers: Understand ABAC vs. RBAC and resolver logic.
  • Security Team: Review scope definitions for least privilege.
• Knowledge Transfer:
  • Code Reviews: Enforce resolver testing (e.g., unit tests for each resolver).
  • Runbooks: Document scope-related incidents (e.g., "How to debug a denied scope").