Onelogin Saml Bundle Laravel Package

Technical Evaluation

Architecture fit

• The package is a Symfony bundle, not a Laravel package. Its value is split between (a) a thin Symfony integration layer — Bundle class, DI extension, config tree, security firewall factory, authenticator, metadata controller — and (b) the actual SAML protocol work, which lives in the upstream onelogin/php-saml toolkit.
• Only (b) is transferable to Laravel. Part (a) is entirely inert inside a Laravel application: Laravel has no bundle registration, no FrameworkBundle, no Symfony security firewall, and no kernel/config-tree lifecycle. composer require will succeed; nothing will wire up. v3.0.0 does not change this — the release is a Symfony-version-support change inside part (a), the exact layer that is inert for us.
• Laravel's actual SP requirements — /saml/metadata, an ACS route, login redirect, SLO, attribute mapping to an Eloquent user, and guard/middleware integration — all have Laravel-native equivalents the bundle does not provide.

Integration feasibility

• As a direct dependency: not feasible. Do not schedule work assuming otherwise.
• As a reference implementation: high value. The bundle's config schema (SP entity ID, ACS/SLO URLs, IdP metadata, certs, signing algorithm, attribute mapping) is a well-formed spec we can port into a Laravel config file and service provider in roughly one to two sprints.
• Three viable paths, in order of preference:
  1. Laravel-native SP built on onelogin/php-saml (or a maintained equivalent), patterned on this bundle's configuration and validation flow.
  2. Evaluate an existing Laravel SAML package first; the ecosystem is thin and unevenly maintained, so this is a build-vs-buy spike, not a default.
  3. Sidecar/gateway (reverse proxy auth or an IdP broker) if the org already operates one — keeps SAML out of the app entirely.

Technical risk

• Code risk: low, and slightly improved. BSD-3-Clause, a mature upstream dependency, and a v3.0.0 major release with Symfony 8.0 support confirm the project is actively tracking the Symfony release train rather than coasting. A maintainer willing to cut a major for a framework bump is a positive vitality signal.
• Fit risk: high and unchanged. The framework mismatch is the dominant risk and is not mitigable by configuration or by this release.
• v3.0.0 is a breaking change for Symfony consumers, not for us. A major bump whose sole changelog line is "Symfony 8.0 support" almost certainly means Symfony 7.x and earlier are dropped from the supported range. That matters only to a hypothetical Symfony deployment; for the Laravel port it is a no-op. Do not let the "major version" label trigger a re-plan.
• Maintainer concentration. 57 stars and 0 recorded dependents implies a single-maintainer project with a thin user base — viable but with a real bus factor. v3.0.0 does not broaden the contributor or dependent base; the concentration risk is unchanged.
• Upstream chain risk. Security posture depends on onelogin/php-saml and its XML-signature library. Note the release notes say nothing about bumping the SAML library or the signature dependency — treat that as unverified and check the composer.json constraint diff before assuming any security-relevant upgrade occurred.
• Security surface is non-trivial. SAML signature-wrapping (XSW), assertion replay, audience/recipient validation, clock skew, and encrypted assertions are all places a hand-rolled port goes wrong. This needs an explicit security review, not just a passing test suite.
• Auth-model mismatch. Symfony's firewall/session semantics differ from Laravel's guard/session semantics; a naive port produces subtle re-authentication and session-fixation bugs.

Key questions

• Which IdP, and does it require SP-initiated only, IdP-initiated only, or both? Is Single Logout in scope?
• Are encrypted assertions or signed authn requests required?
• Single IdP or multi-tenant (per-customer metadata)? This changes config and routing design materially.
• Is JIT user provisioning expected, and how do IdP attributes map to roles/permissions?
• What is the account-linking policy when a SAML identity matches an existing local account?
• Who owns the security review and pen-test sign-off, and is a sidecar/gateway architecturally acceptable?
• (New) Does v3.0.0 bump onelogin/php-saml or the XML-signature dependency, or is it purely a Symfony constraint change? This determines whether there is any security-relevant delta worth reading the diff for — the answer decides whether the port references v2.1.0 or v3.0.0 patterns.

Integration Approach

Stack fit

• Laravel 10/11/12 on PHP 8.2+ with Symfony components present but not FrameworkBundle. Nothing in the bundle's integration layer will bind — and v3.0.0, being a Symfony 8 constraint change, touches precisely the layer we already cannot use.
• Practical fit is as a specification and pattern source: its config structure maps cleanly to config/saml.php; its firewall authenticator maps to a Laravel guard plus middleware; its metadata action maps to a single controller route. That mapping is stable across v2.1.0 → v3.0.0.

Migration path

• Symfony → this bundle: straightforward. Register the bundle in bundles.php, configure the firewall, point at IdP metadata. Low effort, well-trodden — but note v3.0.0 likely requires Symfony 8, so existing Symfony 6/7 estates must upgrade the framework first. Pin the bundle major to the framework major.
• Laravel → this bundle: no migration path exists. Treat it as design input, not a dependency. If the team later moves to Symfony, the ported config transfers back almost verbatim — target v3.0.0 there.

Compatibility

• Confirm X.509 cert handling, SHA-256 signing, and HTTP-Redirect/POST binding support against the target IdP's metadata.
• Watch for non-standard IdP metadata XML; some enterprise IdPs emit formats that trip strict parsers.
• If referenced in a Symfony context, the support matrix is now effectively split: v3.x for Symfony 8, v2.1.x for the prior major. Verify PHP 8.3/8.4 deprecation noise against whichever line you read from.

Sequencing

1. IdP requirements workshop and a pilot IdP tenant provisioned.
2. Skim the v3.0.0 diff to confirm whether any SAML-library or signing changes landed; if none, read patterns from either major, if some, read from v3.0.0.
3. Two-to-three day spike: metadata endpoint + ACS route in Laravel using onelogin/php-saml, validating real signed assertions end-to-end.
4. Implement guard, middleware, and JIT user provisioning with attribute mapping.
5. Negative-path test suite: tampered signature, wrong audience, wrong recipient, expired assertion, replayed assertion ID.
6. SLO and IdP metadata/cert rotation handling.
7. Security review and pen-test, then rollout behind a feature flag with password login retained as fallback.

Operational Impact

Maintenance

• In Laravel, this package imposes zero runtime dependency — but the ported SAML code becomes ours, so the maintenance burden transfers to the team rather than disappearing. v3.0.0 requires no action on our side at all.
• In Symfony, maintenance is light: track the bundle's releases and the Symfony major. v3.0.0 is the cadence working as intended — a coordinated bump behind a framework release — and it raises confidence that a Symfony 9 bump will also be handled.
• Budget for certificate rotation (SP and IdP) as a recurring runbook item, not an ad-hoc incident.

Support

• Community-only via GitHub issues. With 57 stars and 0 dependents, expect thin community coverage and no vendor SLA — plan for self-support.
• A single-maintainer project shipping a major version on Symfony's schedule means the maintainer is engaged today; it does not reduce the key-person risk. Keep the bus-factor mitigation (an internal owner who can read the source) in place.
• SAML failures frequently require IdP-vendor escalation; identify that support contract path before go-live.

Scaling

• SAML is login-volume traffic, not request-volume traffic. XML canonicalization and signature verification are CPU-cheap at realistic auth rates.
• Cache IdP metadata with a TTL; never fetch it per request.
• Fully horizontally scalable with a shared session store; no affinity requirements.

Failure modes

• IdP cert/metadata expiry → total login outage. Mitigate with expiry alerting and overlapping dual certs during rotation.
• Clock skew → spurious "not yet valid"/"expired" rejections. Require NTP and a defined tolerance window.
• ACS URL or audience misconfiguration → login loops or opaque 400s. Log SAML response IDs and status codes at the ACS.
• Missing RelayState on IdP-initiated flow → broken post-login redirects.
• Identity collision with an existing local account → account takeover vector if linking is implicit. Requires an explicit, reviewed linking policy.
• Upstream abandonment → security patch gap. Subscribe to advisories for the SAML library and its XML-signature dependency. v3.0.0 is reassuring on the bundle's own liveness but says nothing about the underlying SAML library's maintenance.
• Version-drift misread (new) → an engineer sees "v3.0.0 major release" and assumes a security or protocol change requiring rework. Pre-empt this in the runbook: the major is a framework-support bump, and our Laravel port is unaffected.

Ramp-up

• A senior PHP engineer needs roughly 3–5 days to get productive on SAML concepts (bindings, assertions, signature scope). The bundle itself is small enough to read in an afternoon and is a genuinely good onboarding artifact.
• Pair the implementer with a security engineer for the assertion-validation review; that pairing is the single highest-leverage investment in this workstream.
• Produce an IdP onboarding runbook from the first integration — it will be reused for every subsequent customer or environment.