Digidbundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require conduction/digidbundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Conduction\DigiDBundle\DigiDBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console digid:install
   

   Update config/packages/conduction_digid.yaml with your DigiD credentials (client ID, secret, etc.).

3. First Use Case Authenticate a user via DigiD in a controller:

   use Conduction\DigiDBundle\Service\DigiDService;
   
   public function login(DigiDService $digidService)
   {
       $authUrl = $digidService->getAuthUrl('https://yourapp.com/callback');
       return new RedirectResponse($authUrl);
   }
   

Implementation Patterns

Workflow: OAuth2 Flow

1. Redirect to DigiD Use DigiDService::getAuthUrl() to generate a login URL with a callback route.

   $authUrl = $digidService->getAuthUrl('/auth/digid/callback');
   

2. Handle Callback Configure a route (e.g., /auth/digid/callback) to process the DigiD response:

   public function callback(DigiDService $digidService, Request $request)
   {
       $token = $digidService->handleCallback($request);
       $userInfo = $digidService->getUserInfo($token);
       // Store user data (e.g., in session or database).
   }
   

3. Token Management Store the access token securely (e.g., in the user session or a database) for subsequent API calls:

   $digidService->callApi($token, 'https://api.digid.nl/endpoint');
   

Integration Tips

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

  # config/packages/security.yaml
  firewalls:
      main:
          digid_authenticator: true
  

  Override onAuthenticationSuccess() to map DigiD claims to Symfony users.

• Event Listeners Listen for digid.login.success events to trigger post-auth actions (e.g., logging, analytics):

  public function onDigiDLoginSuccess(DigiDLoginEvent $event)
  {
      $userInfo = $event->getUserInfo();
      // Custom logic here.
  }
  

• API Calls Use DigiDService::callApi() for protected endpoints:

  $response = $digidService->callApi($token, '/api/protected-route');
  

Gotchas and Tips

Pitfalls

1. Callback Route Mismatch Ensure the redirect_uri in getAuthUrl() matches the configured callback route exactly (including trailing slashes). Mismatches result in redirect_uri_mismatch errors.

2. Token Expiry DigiD tokens expire (typically 1 hour). Implement token refresh logic or prompt re-authentication:

   try {
       $response = $digidService->callApi($token, '/endpoint');
   } catch (TokenExpiredException $e) {
       // Redirect to login or refresh token.
   }
   

3. CORS Issues If using DigiD’s API from a frontend, ensure CORS headers are configured on your backend:

   # config/packages/nelmio_cors.yaml
   paths:
       '^/api/':
           allow_origin: ['https://yourapp.com']
   

Debugging

• Enable Logging Set debug: true in config/packages/conduction_digid.yaml to log OAuth2 requests/responses.

• Test Locally Use DigiD’s test environment with mock credentials to avoid hitting rate limits.

Extension Points

1. Custom Claims Mapping Override DigiDUserProvider to map DigiD claims (e.g., bsn) to your user model:

   public function loadUserByDigiDInfo(array $userInfo)
   {
       return User::where('bsn', $userInfo['bsn'])->first();
   }
   

2. State Parameter Add a custom state parameter to getAuthUrl() to prevent CSRF:

   $authUrl = $digidService->getAuthUrl('/callback', ['state' => bin2hex(random_bytes(16))]);
   

3. Multi-Tenant Support Pass a tenant ID via the state parameter and validate it in the callback to support multi-tenancy:

   $state = ['tenant_id' => $tenantId, 'csrf_token' => $token];
   $authUrl = $digidService->getAuthUrl('/callback', ['state' => json_encode($state)]);