Lightsaml Bridge Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require claroline/lightsaml-bridge
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Claroline\LightSamlBridge\LightSamlBridgeBundle::class => ['all' => true],
   ];
   

2. Configuration Define SAML settings in config/packages/claroline_lightsaml_bridge.yaml:

   claroline_lightsaml_bridge:
       sp:
           entity_id: "https://your-app.com/saml/metadata"
           assertion_consumer_service:
               url: "https://your-app.com/saml/acs"
               binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
           single_logout_service:
               url: "https://your-app.com/saml/sls"
               binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
       idp:
           entity_id: "https://idp.example.com/metadata"
           single_sign_on_service:
               url: "https://idp.example.com/sso"
               binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
   

3. First Use Case Trigger SAML authentication in a controller:

   use Claroline\LightSamlBridge\Service\SamlService;
   
   class AuthController extends AbstractController
   {
       public function login(SamlService $samlService)
       {
           return $samlService->login();
       }
   }
   

Implementation Patterns

Core Workflows

1. Service Integration Inject SamlService into controllers/services to handle SAML flows:

   $samlService->login(); // Redirect to IdP
   $samlService->logout(); // Initiate SLO
   $samlService->processAuthnResponse(); // Handle ACS callback
   

2. Metadata Management Generate/validate metadata dynamically:

   $metadata = $samlService->getSpMetadata(); // SP metadata
   $samlService->validateIdpMetadata($idpMetadata); // Validate IdP metadata
   

3. User Context Retrieve authenticated user attributes:

   $attributes = $samlService->getAttributes();
   $userId = $attributes['urn:oid:1.3.6.1.4.1.5923.1.1.1.6']; // CommonName
   

Advanced Patterns

• Custom Attribute Mapping Override default attribute handling in a service:

  $samlService->setAttributeMapper(function ($attributes) {
      return [
          'email' => $attributes['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'] ?? null,
          'roles' => $attributes['urn:oid:1.3.6.1.4.1.5923.1.1.1.7'] ?? [],
      ];
  });
  

• Event Listeners Subscribe to SAML events (e.g., SamlAuthenticateEvent):

  $eventDispatcher->addListener(SamlEvents::AUTHENTICATE, function (SamlAuthenticateEvent $event) {
      if ($event->isAuthenticated()) {
          $this->authenticator->authenticate($event->getUser());
      }
  });
  

• Route-Based ACS/SLS Define custom routes for ACS/SLS in config/routes.yaml:

  saml_acs:
      path: /saml/acs
      controller: Claroline\LightSamlBridge\Controller\SamlController::acs
  saml_sls:
      path: /saml/sls
      controller: Claroline\LightSamlBridge\Controller\SamlController::sls
  

Gotchas and Tips

Common Pitfalls

1. Metadata Mismatch

   • Issue: SAML errors due to mismatched entity_id or AssertionConsumerService URLs.
   • Fix: Validate metadata before deployment:

     $samlService->validateSpMetadata($spMetadata);
     

2. Signed Requests

   • Issue: IdP rejects unsigned requests or vice versa.
   • Fix: Configure signing in config/packages/claroline_lightsaml_bridge.yaml:

     claroline_lightsaml_bridge:
         sp:
             want_assertions_signed: true
             signing_certificate: "%kernel.project_dir%/config/certs/sp-cert.pem"
             private_key: "%kernel.project_dir%/config/certs/sp-key.pem"
     

3. Attribute Errors

   • Issue: Missing or malformed attributes in responses.
   • Fix: Debug with:

     $samlService->getLastResponse(); // Raw SAML response
     

4. Session Handling

   • Issue: SAML session conflicts with Symfony’s session.
   • Fix: Use SamlSessionHandler to sync sessions:

     $samlService->setSessionHandler(new SymfonySessionHandler($request->getSession()));
     

Debugging Tips

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

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

  Then configure the bridge to use the saml channel.

• Test with Local IdP Use SimpleSAMLphp for local testing:

  claroline_lightsaml_bridge:
      idp:
          entity_id: "https://simplesaml.example.com/saml2/idp/metadata.php"
  

Extension Points

1. Custom Authenticators Implement SamlAuthenticatorInterface for custom logic:

   class CustomSamlAuthenticator implements SamlAuthenticatorInterface
   {
       public function authenticate(array $attributes): ?UserInterface
       {
           // Custom user lookup/creation
       }
   }
   

   Register via:

   claroline_lightsaml_bridge:
       authenticator: App\Security\CustomSamlAuthenticator
   

2. Override Templates Extend Twig templates in templates/ClarolineLightSamlBridge/:

   • login.html.twig (custom login page)
   • error.html.twig (custom error handling)

3. Hook into LightSAML Access the underlying LightSaml\Auth\Auth instance:

   $auth = $samlService->getAuth();
   $auth->setOption('debug', true); // Enable LightSAML debug mode