Samlbundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require conduction/samlbundle
   

   Enable the bundle in config/bundles.php:

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

2. Configuration Copy the default config to config/packages/conduction_saml.yaml:

   php bin/console make:config conduction_saml
   

   Update with your Identity Provider (IdP) metadata (XML or URL) and Service Provider (SP) settings (entity ID, private key, certificate).

3. First Use Case

   • Login Route: Add a route to initiate SAML authentication:

     # config/routes.yaml
     conduction_saml_login:
         path: /login/saml
         controller: conduction_saml.controller
     

   • Callback Route: Configure the ACS (Assertion Consumer Service) URL in conduction_saml.yaml:

     sp:
         acs_url: "https://your-app.com/login/saml/callback"
     

4. Verify Setup Run the SAML validator:

   php bin/console conduction:saml:validate
   

   Test with a browser or Postman by accessing /login/saml.

Implementation Patterns

Workflows

1. User Authentication Flow

   • Redirect users to IdP:

     use Conduction\SamlBundle\Security\SamlAuthenticator;
     
     // In a controller or event listener
     $authenticator = new SamlAuthenticator();
     return $authenticator->start($request, $options);
     

   • Handle the SAML response in the callback route (automatically handled by the bundle if routes are configured).

2. User Provisioning

   • Use the SamlUserProvider to fetch user attributes from the SAML response:

     $userProvider = $container->get('conduction_saml.user_provider');
     $user = $userProvider->loadUserBySAMLResponse($samlResponse);
     

   • Map IdP attributes to your user model (extend SamlUserProvider or use a custom mapper).

3. Session Management

   • Leverage Symfony’s security component to manage sessions post-authentication:

     # security.yaml
     firewalls:
         main:
             saml: true
     

Integration Tips

• Symfony Security Integration Configure the firewall to use SAML authentication:

  security:
      providers:
          saml_provider:
              id: conduction_saml.user_provider
      firewalls:
          main:
              saml: ~
  

• Custom Attribute Mapping Override the default attribute mapper in services.yaml:

  conduction_saml.user_provider:
      class: App\Security\CustomSamlUserProvider
      arguments:
          - '@conduction_saml.attribute_mapper'
          - '@conduction_saml.user_mapper'
  

• Metadata Handling Dynamically fetch IdP metadata from a URL:

  idp:
      metadata_url: "https://idp.example.com/metadata"
  

• Logging and Debugging Enable debug mode in conduction_saml.yaml:

  debug: true
  

  Log SAML messages to var/log/saml.log.

Gotchas and Tips

Pitfalls

1. Certificate and Key Configuration

   • Ensure the SP private key and certificate are correctly formatted (PEM). The bundle expects:

     sp:
         private_key: "%kernel.project_dir%/config/saml/sp-key.pem"
         certificate: "%kernel.project_dir%/config/saml/sp-cert.pem"
     

   • Gotcha: If the certificate is self-signed, add it to your trusted CA store or configure the IdP to trust it.

2. ACS URL Mismatch

   • The acs_url in conduction_saml.yaml must match the URL used in the IdP configuration. A mismatch will cause authentication to fail silently.
   • Debug Tip: Use conduction:saml:validate to check URL consistency.

3. Attribute Mapping Issues

   • If user attributes (e.g., email, firstName) are not mapping correctly, verify:
     • The attribute names in the IdP metadata.
     • The custom mapper implementation (if extended).
   • Debug Tip: Dump the raw SAML response in the callback:

     $samlResponse = $request->get('SAMLResponse');
     file_put_contents('saml_response.xml', base64_decode($samlResponse));
     

4. Time Synchronization

   • SAML requires clocks to be synchronized between SP and IdP (within 5 minutes). Enable NTP on your server if issues arise.

5. Caching Metadata

   • If using metadata_url, the bundle caches metadata by default. Clear the cache if IdP metadata changes:

     php bin/console cache:clear
     

Tips

1. Testing Locally

   • Use tools like SimpleSAMLphp to simulate an IdP for development.
   • Configure the IdP to trust your SP’s self-signed certificate temporarily.

2. Custom Error Handling

   • Extend the SamlExceptionListener to handle SAML errors gracefully:

     use Conduction\SamlBundle\Event\SamlExceptionEvent;
     
     $eventDispatcher->addListener(SamlExceptionEvent::class, function (SamlExceptionEvent $event) {
         $event->setResponse(new RedirectResponse('/login?error=saml'));
     });
     

3. Logout Functionality

   • Implement Single Logout (SLO) by configuring the IdP and SP logout URLs:

     sp:
         single_logout_url: "https://your-app.com/logout/saml"
     

4. Performance

   • For high-traffic applications, pre-load metadata and certificates into memory:

     $metadata = $container->get('conduction_saml.metadata');
     $metadata->load(); // Explicitly load metadata
     

5. Bundle Updates

   • Monitor for updates to conduction/samlbundle as it’s actively maintained. Check the changelog for breaking changes.