Openid Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require fp/openid-bundle
   

   Add to config/bundles.php:

   FormaPro\OpenIdBundle\FormaProOpenIdBundle::class => ['all' => true],
   

2. Configuration: Add to config/packages/formapro_openid.yaml:

   forma_pro_openid:
       providers:
           google: ~
           yahoo: ~
       # Optional: Customize allowed providers
       allowed_providers: ['google', 'yahoo']
   

3. First Use Case:

   • Extend your User entity to include OpenID fields (e.g., openidIdentifier).
   • Add a route to trigger OpenID login (e.g., /login/openid/{provider}).
   • Use the OpenIdAuthenticator service to handle authentication:

     $authenticator = $this->container->get('formapro_openid.authenticator');
     $authenticator->authenticate($request, $provider);
     

Implementation Patterns

Workflow: User Authentication

1. Provider Selection: Render a list of OpenID providers (e.g., Google, Yahoo) via a template.

   {% for provider in openid_providers %}
       <a href="{{ path('openid_login', {'provider': provider}) }}">{{ provider }}</a>
   {% endfor %}
   

2. Authentication Flow:

   • Redirect to provider’s OpenID endpoint.
   • Handle the callback via OpenIdAuthenticator:

     public function authenticate(Request $request, string $provider): Response
     {
         $authenticator = $this->container->get('formapro_openid.authenticator');
         $authenticator->authenticate($request, $provider);
     
         return $this->redirectToRoute('home');
     }
     

3. User Creation/Update: Use Doctrine listeners or services to sync OpenID data with your User entity:

   // Example: Post-authentication hook
   $event = new OpenIdAuthEvent($user, $providerData);
   $this->dispatcher->dispatch($event, 'openid.post_auth');
   

Integration Tips

• Symfony Security: Integrate with Symfony’s security system by extending AbstractGuardAuthenticator:

  use FormaPro\OpenIdBundle\Security\OpenIdAuthenticator as BaseAuthenticator;
  
  class CustomOpenIdAuthenticator extends BaseAuthenticator
  {
      public function supports(Request $request): bool
      {
          return $request->isMethod('GET') && $request->getPathInfo() === '/login/openid';
      }
  }
  

• Custom Providers: Extend OpenIdProvider to support non-standard providers:

  class CustomProvider extends OpenIdProvider
  {
      protected function getDiscoveryUrl(): string
      {
          return 'https://custom-provider.com/openid';
      }
  }
  

• CSRF Protection: Disable CSRF for OpenID endpoints in security.yaml:

  firewalls:
      main:
          pattern: ^/login/openid
          csrf_protection: false
  

Gotchas and Tips

Pitfalls

1. Deprecated Bundle:

   • Last release in 2014—expect compatibility issues with modern Symfony (5.4+/6.x).
   • Mitigation: Fork the repo or use a maintained alternative like hwi/oauth-bundle.

2. Provider-Specific Quirks:

   • Some providers (e.g., Google) require scopes or redirect URIs to be pre-registered.
   • Tip: Use OpenIdProvider::setOption() to pass provider-specific configs:

     $provider->setOption('google', ['scope' => 'email profile']);
     

3. Session Handling:

   • OpenID relies on server-side sessions. Ensure your session config in framework.yaml is properly set:

     framework:
         session:
             handler_id: null # Use default (e.g., Redis, Memcached)
     

4. Error Handling:

   • Silent failures may occur if the provider’s discovery document is unreachable.
   • Debug Tip: Enable debug mode and check var/log/dev.log for OpenIdException.

Debugging

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

  handlers:
      openid:
          type: stream
          path: "%kernel.logs_dir%/openid.log"
          level: debug
          channels: ["openid"]
  

• Test with Mock Providers: Use OpenID test servers (e.g., https://openid.example.org/server) for local testing.

Extension Points

1. Custom Claims Mapping: Override OpenIdUserProvider to map provider claims to your User entity:

   class CustomUserProvider extends OpenIdUserProvider
   {
       protected function loadUserByOpenIdIdentifier($identifier)
       {
           // Custom logic to fetch/update user
       }
   
       protected function getUsernameFromClaim(array $claims): string
       {
           return $claims['preferred_username'] ?? $claims['email'];
       }
   }
   

2. Post-Authentication Actions: Dispatch events in OpenIdAuthenticator:

   $event = new PostOpenIdAuthEvent($user, $providerData);
   $this->eventDispatcher->dispatch($event, 'openid.post_auth');
   

3. UI Customization: Extend the default login template (@FormaProOpenId/login.html.twig) or override it in your theme:

   {% extends '@FormaProOpenId/login.html.twig' %}
   {% block openid_providers %}
       {{ parent() }} <!-- Extend default providers -->
       <a href="{{ path('openid_login', {'provider': 'custom'}) }}">Custom Provider</a>
   {% endblock %}