Passport Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel/passport
   php artisan passport:install
   

   This runs migrations, creates keys, and registers the Passport service provider.

2. Configure Auth Guard: In AuthServiceProvider, ensure Passport is configured for your auth guard (e.g., users):

   Passport::routes();
   Passport::hashClientSecrets();
   Passport::tokensExpireIn(now()->addDays(15));
   Passport::refreshTokensExpireIn(now()->addDays(30));
   Passport::enableImplicitGrant();
   

3. First Use Case:

   • Issue a Token: Use the Passport::actingAs() helper in tests or manually:

     $user = User::find(1);
     $token = $user->createToken('API Token')->accessToken;
     

   • Protect Routes: Add middleware to API routes:

     Route::middleware('auth:api')->get('/user', function (Request $request) {
         return $request->user();
     });
     

Where to Look First

• Documentation: Laravel Passport Docs (official, up-to-date).
• Migrations: database/migrations/ for oauth_* tables.
• Middleware: app/Http/Middleware/ for AuthenticateWithPassport.
• Helpers: Passport::actingAs(), Passport::actingAsClient() for testing.

Implementation Patterns

Core Workflows

1. Token Issuance:

   • User Tokens: Use createToken() on a User model.

     $token = $user->createToken('App Access')->accessToken;
     

   • Client Credentials: Use Passport::actingAsClient() for machine-to-machine auth.

     $client = Client::find(1);
     $token = Passport::actingAsClient($client)->createToken()->accessToken;
     

2. Route Protection:

   • Apply auth:api middleware to routes or groups:

     Route::middleware(['auth:api', 'throttle:60,1'])->group(function () {
         // Protected routes
     });
     

3. Scopes and Permissions:

   • Assign scopes when creating tokens:

     $token = $user->createToken('Admin Access', ['admin', 'write'])->accessToken;
     

   • Validate scopes in middleware:

     public function handle($request, Closure $next, $scope) {
         if (!$request->user()->tokenCan($scope)) {
             abort(403);
         }
         return $next($request);
     }
     

4. Token Revocation:

   • Revoke tokens via the Token model:

     $user->tokens()->delete(); // Revoke all user tokens
     $token->revoke(); // Revoke a specific token
     

5. Customizing Responses:

   • Override default token response format:

     Passport::tokensCanUseManyScopes();
     Passport::tokensExpireIn(CarbonInterval::hours(1));
     

Integration Tips

• Testing: Use Passport::actingAs() for authenticated tests:

  $response = $this->actingAs($user)->get('/api/user');
  

  For client credentials:

  $response = $this->actingAsClient($client)->post('/oauth/token', [
      'grant_type' => 'client_credentials',
  ]);
  

• Third-Party Clients: Register clients via the Client model or use the Passport::client() helper:

  $client = Passport::client(
      'client-id',
      'client-secret',
      ['password', 'refresh_token']
  );
  

• Custom Guards: Extend TokenGuard for non-standard auth logic:

  class CustomTokenGuard extends TokenGuard {
      public function getUser() {
          // Custom user resolution logic
      }
  }
  

• Event Listeners: Listen to token events (e.g., Passport::events()):

  Passport::tokensUsingManyScopes(function ($user, $token) {
      // Custom logic when token uses multiple scopes
  });
  

Gotchas and Tips

Pitfalls

1. UUID vs. Integers:

   • Passport v13+ defaults to UUIDs for clients/tokens. If using integers, ensure migrations and models are updated:

     Schema::table('oauth_clients', function (Blueprint $table) {
         $table->string('id')->change();
     });
     

2. Client Secret Hashing:

   • Secrets are always hashed in v13+. Avoid storing plaintext secrets in logs or configs.

3. Token Guard Configuration:

   • Ensure AuthServiceProvider configures the correct guard:

     Passport::useTokenGuard('api'); // Explicitly set guard name
     

4. Scope Validation:

   • Scopes are case-sensitive. Validate with tokenCan():

     if (!$request->user()->tokenCan('WRITE')) { // Fails if scope is 'write'
         abort(403);
     }
     

5. Refresh Tokens:

   • Refresh tokens are revoked by default when used. Disable with:

     Passport::refreshTokensExpireIn(null); // Disable expiration
     

6. Middleware Order:

   • Place auth:api after throttle middleware to avoid throttling unauthenticated requests.

7. Headless Mode:

   • Passport v13 is "headless" by default. If using Jetstream/Breeze, ensure:

     Passport::ignoreRoutes(); // Disable built-in routes
     

Debugging

1. Token Issues:

   • Check token validity with:

     $token = \Laravel\Passport\Client::find(1)->findToken($request->bearerToken());
     

   • Validate scopes:

     dd($request->user()->token()->scopes);
     

2. Client Misconfiguration:

   • Verify client secrets and redirect URIs in the oauth_clients table.

3. CORS Errors:

   • Ensure Access-Control-Allow-Origin headers are set for OAuth endpoints:

     Passport::enableImplicitGrant();
     Passport::tokensCanUseManyScopes();
     

4. Database Locks:

   • Use transactions for bulk token operations to avoid deadlocks:

     DB::transaction(function () {
         $user->tokens()->delete();
     });
     

Extension Points

1. Custom Token Models:

   • Extend Laravel\Passport\Token or Laravel\Passport\Client:

     class CustomToken extends Token {
         public function customMethod() { ... }
     }
     

   • Register in AuthServiceProvider:

     Passport::tokensUsingManyScopes(function ($user, $token) {
         return new CustomToken($token->getKey());
     });
     

2. Custom Grant Types:

   • Implement Laravel\Passport\Bridge\Grant:

     class CustomGrant implements Grant {
         public function respondToAccessRequest() { ... }
     }
     

   • Register in Passport::grantsUsing():

     Passport::grantsUsing([CustomGrant::class]);
     

3. Custom User Resolution:

   • Override findForPassport() in your User model:

     public static function findForPassport($identifier) {
         return static::where('email', $identifier)->first();
     }
     

4. Token Lifecycle Hooks:

   • Listen to passport.token.created or passport.token.revoked events:

     event(new Passport\Events\TokenCreated($token));
     

5. Custom Error Responses:

   • Override OAuthServerException rendering:

     Passport::registerExceptionRenderer(function ($request, \League\OAuth2\Server\Exception\OAuthServerException $exception) {
         return response()->json(['error' => $exception->getMessage()], 400);
     });
     

Configuration Quirks

1. Trusted Proxies:

   • Configure trusted proxies for token issuance:

     Passport::trustedProxies(['192.168.1.0/24']);
     

2. Key File Permissions:

   • Ensure bootstrap/cache/passport-*.pem files are readable by the web server:

     chmod 644 bootstrap/cache/passport-*.pem
     

3. Personal Access Tokens (PAT):

   • PATs are disabled by default in v13+. Re-enable with:

     Passport::