Lightsaml Symfony Bridge Laravel Package

Getting Started

This bundle wraps the LightSAML PHP toolkit for Symfony, giving you a Service Provider (SP) integration point rather than an IdP. Before wiring it up, be aware the package was last released in May 2017 (0 stars, 0 dependents) — treat it as a reference implementation to study and vendor/adapt rather than a drop-in dependency.

Minimal steps:

1. Install and confirm target Symfony version match. This is a Symfony 2.8/3.x-era bundle (bundle registration in AppKernel.php, Resources/config YAML services, no autowiring/autoconfigure). Do not assume it works on Symfony 5/6 without refactoring.
2. Register the bundle in your kernel and run bin/console config:dump-reference <bundle_alias> first — this tells you the exact config tree the fork exposes, which is the single most reliable source of truth here since forks drift from the upstream LightSAML SP bundle.
3. Read DependencyInjection/Configuration.php and the service definitions before editing anything. You need to know which services are public and which are aliases you can decorate.
4. Pick your first use case: SP-initiated SSO against a test IdP (SimpleSAMLphp or samltest.id). Point the bundle's IdP metadata at the test IdP and your SP entityId/assertionConsumerService URL at your local routes, then hit the login endpoint and confirm you receive a SAMLResponse POST back.

If you need production SSO today, budget for evaluating the maintained alternatives (e.g. hslavich/oneloginsaml-bundle, or direct LightSAML usage) alongside this one.

Implementation Patterns

SP metadata endpoint. Expose the generated metadata XML at a dedicated route so the IdP can consume it. This is the cleanest way to verify entity IDs, ACS URLs, and signing certificates match what the IdP expects — mismatches here are the #1 cause of "Invalid request" errors.

SP-initiated vs IdP-initiated flows. Wire a "login" action that builds an AuthnRequest and redirects, and an "ACS" action that consumes the POSTed SAMLResponse, validates it, and then feeds an authenticated identity into Symfony's security layer. IdP-initiated flows skip the request step and go straight to the ACS — ensure your ACS handler does not assume a stored request ID exists.

Security integration. The typical pattern is a custom authentication provider/listener that takes the validated LightSAML assertion, resolves a local user via your user provider, and creates a token. Keep assertion parsing (bundle/LightSAML) separate from user resolution (your app) so you can test each independently.

Attribute mapping. Map SAML attributes (NameID, email, groups/roles) to local roles in a small adapter service rather than inside controllers. This is the piece you'll change most often per IdP.

Single Logout (SLO). Configure the logout route and be explicit about whether you support SP-initiated logout and/or IdP-initiated SLO. Partial SLO support is extremely common and is a frequent source of "user still logged in" bugs.

Multi-IdP setups. The bundle is designed around one IdP config block in older forks. If you need per-tenant IdPs, expect to build a dynamic metadata resolver on top of LightSAML rather than relying on config alone.

Gotchas and Tips

• Abandoned dependency risk. With a 2017 release and zero dependents, transitive dependencies will be your biggest problem. Pin lightsaml/lightsaml and PHP versions explicitly, and check whether your PHP version still satisfies the old constraint.
• XML signing and libxml/openssl. SAML validation depends on openssl verifying signatures and libxml for canonicalization. Disable entity loading concerns, ensure xmlseclibs is compatible, and log the raw XML on failure — signature errors are opaque without it.
• Clock skew. Set tolerated timestamp skew explicitly. A few seconds of drift between IdP and SP causes "assertion not yet valid" failures that look like signature bugs.
• Certificate rotation. IdP signing certs rotate; support reloading IdP metadata without a redeploy, or you'll get silent validation failures on rotation day. Cache metadata with a short TTL and a refresh route.
• Binding confusion. Redirect binding puts the request in the URL; POST binding puts it in a form. Some IdPs only accept one. Mismatched bindings produce errors before signature validation even runs.
• Debugging. Wrap LightSAML's logger into your Monolog channel and switch it to debug only in non-prod. Never log full assertions in production — they may contain PII.
• Extension points. Prefer decorating the bundle's public services (assertion validator, metadata provider) over editing vendor code, so you can patch upstream freely. If services are private (likely in this era), add public aliases in your own services.yaml.
• Testing. Build a fake IdP response fixture and unit-test your validator and attribute mapper against it; you won't get meaningful coverage by hitting a real IdP in CI.
• Migration plan. Given the package's age, isolate it behind your own interface so swapping the SAML toolkit later is contained.