Oauth2 Client Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require awuniversity/oauth2-client-bundle
   

   Enable in config/bundles.php:

   return [
       // ...
       Awuniversity\OAuth2ClientBundle\AwuniversityOAuth2ClientBundle::class => ['all' => true],
   ];
   

2. Configure OAuth2 Client Edit config/packages/awuniversity_oauth2_client.yaml:

   awuniversity_oauth2_client:
       clients:
           google:
               client_id: 'YOUR_CLIENT_ID'
               client_secret: 'YOUR_CLIENT_SECRET'
               redirect_uri: '%env(OAUTH_REDIRECT_URI)%'
               scopes: ['email', 'profile']
   

3. First Use Case: Login with OAuth2 Generate a login route in config/routes.yaml:

   awuniversity_oauth2_login:
       path: /login/{provider}
       controller: Awuniversity\OAuth2ClientBundle\Controller\AuthController::login
   

   Redirect users to /login/google to initiate OAuth2 flow.

Implementation Patterns

Workflow: OAuth2 Authentication

1. Initiate Login Redirect users to /login/{provider} (e.g., /login/google). The bundle handles the OAuth2 authorization request.

2. Callback Handling After user approval, the bundle redirects to the configured redirect_uri. Use the AuthController to process the callback:

   // src/Controller/AuthController.php
   use Awuniversity\OAuth2ClientBundle\Controller\AuthController;
   
   class CustomAuthController extends AuthController {
       protected function handleAuthSuccess($provider, $userData) {
           // Custom logic: e.g., create/update user in your DB
           $user = $this->userManager->findOrCreateUser($userData);
           $this->authenticateUser($user);
       }
   }
   

3. User Data Integration Fetch user data after authentication:

   $client = $this->get('awuniversity_oauth2_client.client.google');
   $userData = $client->getUserData(); // After successful callback
   

Integration Tips

• Symfony Security Component Extend the bundle’s Authenticator to integrate with Symfony’s security system:

  use Awuniversity\OAuth2ClientBundle\Security\OAuth2Authenticator;
  
  class CustomOAuth2Authenticator extends OAuth2Authenticator {
      public function getCredentials() {
          // Custom credential logic
      }
  }
  

• State Management Use Symfony’s Session or ParameterBag to manage OAuth2 state for CSRF protection:

  # config/packages/awuniversity_oauth2_client.yaml
  awuniversity_oauth2_client:
      state: true # Enable state parameter
  

• Multi-Provider Support Configure multiple providers in awuniversity_oauth2_client.yaml and reuse the same workflow for each.

Gotchas and Tips

Pitfalls

1. Deprecated Dependencies The bundle relies on awuniversity/oauth2-client (v1.0), which may lack updates. Monitor for compatibility issues with newer Symfony versions (e.g., 5.x+).

2. State Parameter Mismatch If state is enabled but not validated, OAuth2 requests may fail. Ensure your redirect_uri matches the configured state:

   redirect_uri: 'https://yourapp.com/login/callback?state=%state%' # Example
   

3. No Built-in User Provider The bundle does not auto-create users. Implement handleAuthSuccess() in a custom AuthController to integrate with your user system.

4. Token Storage Access tokens are not persisted by default. Use Symfony’s security.token_storage or a custom service to store tokens:

   $token = $client->getAccessToken(); // Store this for API calls
   

Debugging

• Enable Verbose Logging Add to config/packages/monolog.yaml:

  handlers:
      oauth2:
          type: stream
          path: "%kernel.logs_dir%/oauth2.log"
          level: debug
  

  Log OAuth2 client interactions for troubleshooting.

• Check Redirect URIs Ensure redirect_uri in your OAuth2 provider (e.g., Google Console) matches the route in the bundle config exactly (including http/https).

Extension Points

1. Custom Providers Extend the Client class to support non-standard OAuth2 providers:

   use Awuniversity\OAuth2Client\Client;
   
   class CustomClient extends Client {
       public function getAuthUrl() {
           // Override for custom auth endpoints
       }
   }
   

2. Post-Authentication Logic Override AuthController::handleAuthSuccess() to trigger actions like:

   • Sending welcome emails.
   • Assigning roles based on provider data.
   • Logging user activity.

3. API Client Integration Use the stored access token to make authenticated API calls:

   $client = $this->get('awuniversity_oauth2_client.client.google');
   $response = $client->get('https://www.googleapis.com/userinfo/v2/me');
   

Configuration Quirks

• Scopes as Array Always define scopes as an array in the config, even for single scopes:

  scopes: ['email'] # Not "email"
  

• Environment Variables Use Symfony’s %env() for sensitive data (e.g., client_secret):

  client_secret: '%env(OAUTH_GOOGLE_SECRET)%'