Oauth2 Client Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require league/oauth2-client
   

   For Laravel, use a service provider (e.g., League\OAuth2\Client\Provider\GithubProvider) or wrap it in a custom facade.

2. First Use Case: Authenticating with GitHub

   use League\OAuth2\Client\Provider\GithubProvider;
   
   $provider = new GithubProvider([
       'clientId' => env('GITHUB_CLIENT_ID'),
       'clientSecret' => env('GITHUB_CLIENT_SECRET'),
       'redirectUri' => env('GITHUB_REDIRECT_URI'),
   ]);
   
   // Generate auth URL
   $authUrl = $provider->getAuthorizationUrl();
   // Redirect user to $authUrl
   
   // After redirect, handle callback
   $token = $provider->getAccessToken('authorization_code', [
       'code' => $request->query('code'),
   ]);
   

3. Where to Look First

   • Provider Documentation (list of supported providers).
   • League\OAuth2\Client\Provider\AbstractProvider (base class for custom providers).
   • League\OAuth2\Client\Token\AccessToken (token handling).

Implementation Patterns

Workflow: OAuth2 Integration

1. Provider Initialization Extend AbstractProvider for custom providers or use built-in ones (e.g., Google, Facebook).

   $provider = new CustomProvider([
       'clientId' => config('oauth.client_id'),
       'clientSecret' => config('oauth.client_secret'),
       'redirectUri' => route('oauth.callback'),
       'scopes' => ['user:read', 'repo'], // Optional
   ]);
   

2. Authorization Flow

   • Generate URL: $provider->getAuthorizationUrl().
   • Handle callback: $token = $provider->getAccessToken('authorization_code', ['code' => $request->code]).

3. Fetching User Data

   $user = $provider->getResourceOwner($token);
   // $user is a League\OAuth2\Client\Provider\ResourceOwnerInterface
   

4. Refreshing Tokens

   $newToken = $provider->getAccessToken('refresh_token', ['refresh_token' => $token->getRefreshToken()]);
   

Laravel-Specific Patterns

• Service Container Binding

  $this->app->bind('oauth.github', function () {
      return new GithubProvider(config('services.github'));
  });
  

• Middleware for Protected Routes

  public function handle($request, Closure $next) {
      if (!$request->user()->token) {
          return redirect()->route('oauth.login');
      }
      return $next($request);
  }
  

• Storing Tokens Use Laravel’s HasApiTokens trait or a custom table:

  $user->forceFill([
      'access_token' => $token->getToken(),
      'refresh_token' => $token->getRefreshToken(),
  ])->save();
  

Integration Tips

• Scopes: Always request minimal required scopes (e.g., ['email', 'profile']).
• State Parameter: Use Laravel’s Session to store/validate state for CSRF protection.
• Rate Limiting: Handle League\OAuth2\Client\Exception\RateLimitException gracefully.
• Logging: Log token responses for debugging:

  \Log::debug('OAuth Token', $token->jsonSerialize());
  

Gotchas and Tips

Common Pitfalls

1. Redirect URI Mismatch

   • Ensure redirectUri in config matches the callback URL registered with the provider.
   • Fix: Use url()->current() or route('oauth.callback') dynamically.

2. Token Expiry

   • Tokens expire! Use refresh_token if available or re-authenticate.
   • Tip: Store expires timestamp and auto-refresh before expiry.

3. Provider-Specific Quirks

   • Google: Requires access_type=offline for refresh tokens.
   • GitHub: Uses code in query params; other providers may use POST.
   • Custom Providers: Override getAuthorizationUrl(), getAccessToken(), and getResourceOwner().

4. CSRF/State Handling

   • Always include a state parameter and validate it on callback.
   • Laravel Example:

     $state = $request->session()->getState();
     if ($state !== $request->query('state')) {
         throw new \RuntimeException('State mismatch');
     }
     

5. Error Handling

   • Catch League\OAuth2\Client\Exception\IdentityProviderException for provider errors.
   • Example:

     try {
         $token = $provider->getAccessToken('authorization_code', ['code' => $code]);
     } catch (\League\OAuth2\Client\Exception\IdentityProviderException $e) {
         \Log::error('OAuth Error: ' . $e->getMessage());
         return redirect()->route('oauth.login')->with('error', 'Authentication failed');
     }
     

Debugging Tips

• Enable Verbose Logging

  $provider->setHttpClient(new \GuzzleHttp\Client([
      'debug' => true,
  ]));
  

• Inspect Raw Responses Use getLastResponse() on the provider to debug API calls:

  $response = $provider->getLastResponse();
  \Log::debug($response->getBody());
  

Extension Points

1. Custom Providers Extend AbstractProvider and implement:

   • getAuthorizationUrl()
   • getAccessToken()
   • getResourceOwner()
   • getBaseAuthorizationUrl() (e.g., https://api.example.com/oauth/authorize)

2. Token Storage

   • Use Laravel’s HasApiTokens or a custom TokenRepository.
   • Example:

     $token = $provider->getAccessToken(...);
     $user->tokens()->create([
         'token' => $token->getToken(),
         'refresh_token' => $token->getRefreshToken(),
         'expires_at' => $token->getExpires(),
     ]);
     

3. Middleware for Token Validation

   public function handle($request, Closure $next) {
       $token = $request->user()->token;
       if ($token && $token->expires_at < now()) {
           $provider = app('oauth.github');
           $newToken = $provider->getAccessToken('refresh_token', [
               'refresh_token' => $token->refresh_token,
           ]);
           $token->update([
               'token' => $newToken->getToken(),
               'expires_at' => $newToken->getExpires(),
           ]);
       }
       return $next($request);
   }
   

4. Scopes Management Dynamically add/remove scopes:

   $provider->setScopes(['user:read', 'repo']); // Before getAuthorizationUrl()