Lightsaml Sp Bundle Laravel Package

Getting Started

This bundle is a thin Symfony wrapper around LightSAML core that wires up the Service Provider side of a SAML2 Web-Browser SSO flow. Expect zero stars/zero dependents to mean: no community support, treat the source as the documentation. Read DependencyInjection/Configuration.php and Resources/config/services.yml first — those two files tell you every config key and every service ID you can override.

1. Install (mind the Symfony version — the 2017 release targets Symfony 2.8/3.x, not 4+):

   composer require kidatsy/lightsaml-sp-bundle
   

   Also confirm which lightsaml/lightsaml version the bundle pins; the SP API changed across LightSAML 1.x/2.x.

2. Register the bundle in app/AppKernel.php (Symfony 3 era):

   new Kidatsy\SpBundle\SpBundle(),
   

3. Configure the SP and IdP. The keys mirror LightSAML's ServiceProvider / IdentityProvider builders — entity ID, assertion consumer endpoint, signing/encryption certificates, and IdP SSO URL + signing cert:

   sp_bundle:                      # verify exact root key in Configuration.php
       service_provider:
           entity_id: "https://app.example.com/saml/metadata"
           assertion_consumer_service_url: "https://app.example.com/saml/acs"
           single_logout_service_url: "https://app.example.com/saml/sls"
           certificate_file: "%kernel.root_dir%/config/saml/sp.crt"
           private_key_file: "%kernel.root_dir%/config/saml/sp.key"
       identity_provider:
           entity_id: "https://idp.example.com"
           single_sign_on_service_url: "https://idp.example.com/sso"
           certificate_file: "%kernel.root_dir%/config/saml/idp.crt"
   

4. Generate a keypair (openssl req -new -x509 -nodes ...), drop .crt/.key outside the web root, and hand the .crt over to the IdP team.

5. First use case — SP-initiated login. Hit the bundle's login route (check Resources/config/routing.yml for the exact path, typically something like /_saml/login), authenticate at the IdP, and land back on the ACS endpoint. That round trip is the smoke test: if the ACS accepts the SAMLResponse and returns a mapped principal, the bundle is working.

Implementation Patterns

• SP-initiated flow is the normal path: user requests a protected route → the bundle builds an AuthnRequest, signs it, redirects to the IdP → IdP POSTs a SAMLResponse to the ACS → the bundle validates signature/conditions and gives you a Response object.
• IdP-initiated flow (unsolicited responses) usually requires you to disable the request_id/InResponseTo check in the Response validation settings. Only do this if the IdP actually drives it, and accept the replay-risk tradeoff.
• Wiring auth into the firewall. The bundle gives you a controller + services; it typically does not ship a Symfony 3 Guard authenticator. Standard pattern is a small custom Guard/auth listener that calls the bundle's ACS handling (or an SamlAuthProvider-style service) and, on success, returns a UsernamePasswordToken/PostAuthenticationToken. Keep that glue in your own bundle so upgrades don't break login.
• ACS handling is usually best done inside a controller that reads $request->request->get('SAMLResponse'), base64-decodes via LightSAML's HTTPPost, validates against the configured IdP, then extracts attributes. Don't re-implement XML-DSig — always let LightSAML validate.
• Attribute mapping. The bundle hands back a Response, not a user. Write a mapper that converts NameID + attribute statements into your User entity, and normalise/whitelist attributes rather than blindly trusting them:

  $nameId = $response->getAssertions()[0]->getSubject()->getNameId()->getValue();
  $attrs  = $response->getAssertions()[0]->getAttributes();
  

• Metadata endpoint. The bundle exposes a metadata route/controller. Your IdP admin consumes that XML; regenerating certs means re-registering metadata, so version it.
• Single Logout (SLO) is where these bundles usually break in practice. If SLO isn't wired, don't half-implement it — do local logout and let the IdP session timeout handle the rest.
• Testing. Stand up a local IdP (SimpleSAMLphp or kristophjunge/test-saml-idp in Docker) and drive the flow with a functional test against the ACS endpoint. Unit-test your attribute mapper in isolation.

Gotchas and Tips

• It is effectively abandoned. Last release 2017-05-17, no dependents, no stars. Assume no fixes. Fork it into your own namespace (or vendor it) before production — you will need to patch something.
• Symfony 4/5/6 will not work. The bundle uses AppKernel, %kernel.root_dir%, and Symfony 3 DI conventions. Budget for a port (services to autowiring, config tree migration, RequestStack) or don't adopt it at all.
• Certificate handling is the #1 failure mode. LightSAML wants PEM in the right format; a cert that opens in a browser may still be rejected. Verify with openssl x509 -in idp.crt -noout -text and check the IdP's KeyDescriptor actually matches.
• Clock skew breaks assertion validation (NotBefore/NotOnOrAfter). Keep hosts NTP-synced; most IdPs allow ±5 min, don't exceed that.
• Signature validation ordering in LightSAML is strict — if you swap SP/IdP certs you get opaque SignatureExceptions. Enable LightSAML's PSR-3 logger against a Monolog channel and read the actual reason before touching config.
• InResponseTo / Destination / audience checks each have validation settings. Loosening them to "make it work" is how you get a SAML bypass. Change one at a time, log the original error.
• Extension points are limited to service overrides — override the bundle's ACS/controller and metadata service IDs in services.yml rather than copying the whole bundle. That's the only realistic customisation surface.
• Migration path: if you're starting fresh, look at hslavich/saml-bundle or go straight to OIDC (knpuniversity/oauth2-client-bundle + an IdP that speaks OIDC). If SAML2 is mandated and you're on modern Symfony, this bundle is a research reference, not a dependency.