Saml2 Bridge Bundle Laravel Package

Getting Started

First Steps

1. Installation Run composer require adactive-sas/saml2-bridge-bundle and enable the bundle in config/bundles.php:

   return [
       // ...
       AdactiveSas\Saml2BridgeBundle\AdactiveSasSaml2BridgeBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console config:dump-reference AdactiveSasSaml2BridgeBundle
   

   Then configure config/packages/adactive_sas_saml2_bridge.yaml with your SAML IdP settings (e.g., entity_id, certificate, private_key).

3. First Use Case: Basic SSO Redirect users to the SAML IdP login endpoint:

   use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
   
   $url = $this->generateUrl('saml2_bridge_idp_initiate', [
       'sp_entity_id' => 'https://example.com/sp-metadata.xml',
   ]);
   return $this->redirect($url);
   

Implementation Patterns

Core Workflows

1. Metadata Management

   • Generate SP metadata dynamically:

     $metadata = $this->get('adactive_sas_saml2_bridge.metadata');
     $xml = $metadata->generateMetadata();
     

   • Validate SP metadata before processing:

     $validator = $this->get('adactive_sas_saml2_bridge.metadata_validator');
     $validator->validate($spMetadataXml);
     

2. Authentication Flow

   • SP-Initiated SSO: Redirect to saml2_bridge_idp_initiate route with sp_entity_id.
   • IdP-Initiated SSO: Use saml2_bridge_idp_sso route with target_entity_id (SP).
   • Logout: Trigger via saml2_bridge_idp_logout (supports both IdP/SP-initiated).

3. User Mapping

   • Override default user resolution in config/packages/adactive_sas_saml2_bridge.yaml:

     user_provider:
         class: App\Security\SamlUserProvider
         method: loadUserBySAMLAttributes
     

   • Implement loadUserBySAMLAttributes to map SAML attributes (e.g., email, uid) to your user model.

4. Event Listeners Leverage Symfony events for custom logic:

   // src/EventListener/SamlAuthListener.php
   class SamlAuthListener implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               'saml2_bridge.idp.authenticate' => 'onAuthenticate',
           ];
       }
       public function onAuthenticate(AuthenticateEvent $event) {
           $attributes = $event->getAttributes();
           // Custom logic (e.g., role assignment)
       }
   }
   

5. CSRF Protection Enable CSRF protection in config:

   security:
       csrf_protection: true
   

Gotchas and Tips

Common Pitfalls

1. Metadata Validation

   • Always validate SP metadata before processing requests to avoid malicious SP attacks.
   • Use AdactiveSas\Saml2BridgeBundle\Validator\MetadataValidator for strict checks.

2. Certificate Management

   • Ensure private_key and certificate in config are PEM-encoded and properly formatted.
   • Test locally with self-signed certs (generate via openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes).

3. Time Synchronization

   • SAML requires clock synchronization between IdP and SP (max 5-minute skew). Configure NTP on servers.

4. Debugging

   • Enable debug mode in config:

     debug: true
     

   • Log SAML messages to var/log/saml2_bridge.log:

     logging: true
     

5. Deprecated Features

   • The bundle is last updated in 2018—test thoroughly with modern SP libraries (e.g., onelogin/php-saml).
   • Some SAML 2.1 features (e.g., encrypted assertions) may not be supported.

Pro Tips

1. Dynamic SP Configuration Store SP metadata in a database and fetch dynamically:

   $spMetadata = $this->getSpMetadataFromDb($spEntityId);
   $validator->validate($spMetadata);
   

2. Attribute Mapping Use a YAML-based mapping for flexibility:

   attribute_mapping:
       email: 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'
       groups: 'http://schemas.xmlsoap.org/claims/Group'
   

3. Testing

   • Use Dockerized SimpleSAMLphp for local SP testing:

     FROM simplesamlphp/simplesamlphp:1.18
     

   • Mock SAML responses in PHPUnit:

     $this->get('adactive_sas_saml2_bridge.test.saml_response')->setMockResponse($xml);
     

4. Performance

   • Cache metadata and certificates to avoid repeated file I/O:

     $cache = $this->get('cache.app');
     $metadata = $cache->get('saml_metadata', function() use ($metadataService) {
         return $metadataService->generateMetadata();
     });
     

5. Security Hardening

   • Restrict SAML endpoints to trusted IPs:

     firewall:
         saml:
             pattern: ^/saml
             ip: 192.168.1.0/24
     

   • Disable unused bindings (e.g., Http-Artifact) in config.

6. Upgrade Path

   • If migrating from OpenConext/Stepup-saml-bundle, note breaking changes in:
     • Route names (e.g., saml2_bridge_idp_initiate vs. stepup_saml_initiate).
     • Event namespaces (saml2_bridge.* vs. stepup_saml.*).