External Login Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require acts/external-login-bundle
   

   Add to config/bundles.php (Symfony):

   Camdram\ExternalLoginBundle\CamdramExternalLoginBundle::class => ['all' => true],
   

2. Configuration Update config/packages/camdram_external_login.yaml with your OAuth credentials (Facebook, Twitter, Google, Raven).

3. First Use Case Add the login route to your firewall in config/packages/security.yaml:

   firewalls:
       main:
           pattern: ^/
           external_login:
               provider: your_user_provider
               facebook: true
               twitter: true
               google: true
               raven: true
   

4. Template Integration Include the login button in your Twig template:

   {{ path('external_login_start', {'provider': 'facebook'}) }}
   

Implementation Patterns

Workflow: OAuth Login Flow

1. Redirect to Provider Call external_login_start route with provider name (e.g., facebook).

   return $this->redirectToRoute('external_login_start', ['provider' => 'google']);
   

2. Callback Handling The bundle auto-handles the OAuth callback at /login/check-{provider}. Customize user creation/updating via Camdram\ExternalLoginBundle\Event\ExternalLoginEvent.

3. User Provider Integration Implement UserProviderInterface to map external IDs to your user model:

   class CustomUserProvider implements UserProviderInterface {
       public function loadUserByExternalId($provider, $id) {
           return User::where('external_id', $id)->first();
       }
   }
   

Integration Tips

• Symfony Security Events Listen for external_login.success to post-process user data:

  # config/services.yaml
  services:
      App\EventListener\ExternalLoginListener:
          tags:
              - { name: kernel.event_listener, event: external_login.success, method: onExternalLogin }
  

• Custom Providers Extend Camdram\ExternalLoginBundle\Provider\ProviderInterface for unsupported platforms.

• CSRF Protection Ensure csrf_protection is enabled in your firewall for callback routes.

Gotchas and Tips

Pitfalls

1. Deprecated Dependencies The bundle relies on acts/social-api-bundle (unmaintained). Fork or replace with league/oauth2-client for modern setups.

2. State Parameter Issues Callback routes may fail if state parameter is missing. Add middleware to validate it:

   $this->container->get('security.token_storage')->setToken(
       new UsernamePasswordToken($request->getSession()->get('user'), null, 'main', $roles)
   );
   

3. User Provider Conflicts Ensure loadUserByExternalId() returns a UserInterface or throws UsernameNotFoundException.

Debugging

• OAuth Errors Check acts/social-api-bundle logs for token validation failures. Enable debug mode:

  # config/packages/dev/camdram_external_login.yaml
  debug: true
  

• Session Issues Clear sessions if users aren’t redirected post-login:

  php bin/console cache:clear
  

Extension Points

1. Custom User Mapping Override Camdram\ExternalLoginBundle\Service\UserMapper to handle non-standard user fields.

2. Post-Login Redirects Modify Camdram\ExternalLoginBundle\Security\ExternalLoginAuthenticationListener to change redirect logic.

3. Provider-Specific Logic Extend Camdram\ExternalLoginBundle\Provider\AbstractProvider for custom OAuth flows (e.g., LinkedIn).

Configuration Quirks

• Raven (Cambridge) Specifics Raven’s OAuth requires client_id and client_secret in config/packages/camdram_external_login.yaml:

  raven:
      client_id: your_raven_client_id
      client_secret: your_raven_secret
      scope: ["user"]
  

• Google Scopes Add email and profile scopes to avoid missing user data:

  google:
      scope: ["email", "profile"]