Oneloginsaml Bundle Laravel Package

Getting Started

This package is primarily a Symfony bundle wrapping onelogin/php-saml, so a Laravel developer picking it up should first confirm whether they want (a) the bundle via a Symfony/Laravel bridge, or (b) the underlying onelogin/php-saml toolkit directly. For most Laravel apps, the bundle is not the first stop — but it is the reference implementation for correct SP behavior and useful to read.

1. Install: composer require karolornoch/onelogin-saml-bundle (v1.8.3 is a low-risk patch on top of 1.8.2).
2. Look first at: DependencyInjection/Configuration.php in the repo — it defines the full config schema (SP entity ID, ACS URL, IdP metadata, certificates, attribute mapping, security mode). The README's YAML examples map almost 1:1 to this schema.
3. Register a service provider in Laravel if bridging: bind OneLogin\Saml2\Auth as a singleton and inject your config array, rather than pulling the bundle's Symfony DI container.
4. First use case: SP-initiated SSO. Configure SP metadata → import IdP metadata (URL or local XML) → hit the login route → validate the assertion → map attributes (email, name, groups) to your User model.

Implementation Patterns

• SP-initiated SSO: Build an AuthRequest from the Auth instance, redirect to the IdP ssoUrl. On callback, call $auth->processResponse() and check getErrors() before trusting getAttributes().
• IdP-initiated SSO: Same endpoint, but skip the outbound request; just process the incoming SAMLResponse. Guard against replay by checking getLastRequestXML() and using the toolkit's LastRequestId tracking if you have a store (cache/db).
• Attribute mapping: Prefer mapping to a dedicated SsoIdentity value object rather than mutating your User model directly — it makes multi-tenant / multi-IdP setups (which newer versions support) tractable.
• Single Logout (SLO): Wire SP-initiated and IdP-initiated SLO into the same /saml/logout route; invalidate both the Laravel session and the toolkit's session store.
• Metadata endpoint: Expose /saml/metadata returning $auth->getSettings()->getSPMetadata() so IdP admins can import your SP configuration without hand-editing XML.
• Testing: Stub OneLogin\Saml2\Auth behind an interface so feature tests can return a canned getAttributes() payload without needing a signed response.

Gotchas and Tips

• It is not a native Laravel package. There is no auto-discovery, no published config, and no service provider. If you pull it in, expect to write the glue (or use onelogin/php-saml directly, which is what most Laravel SAML wrappers ultimately call).
• Certificate and key handling: SP private key and IdP X.509 cert must both be PEM. A common failure is pasting the cert with the trailing -----END CERTIFICATE----- newline stripped — signature validation fails silently with a generic error.
• Clock skew: Signature validation fails with Signature validation failed when server time drifts more than the allowedClockDrift (default 60s). Verify NTP before chasing SAML logic bugs.
• SHA-1 deprecation: Many IdPs now require SHA-256 signatures. Set security.requestsSigned = true and configure the IdP's signatureAlgorithm to sha256; leaving sha1 fails on newer Azure AD / Okta tenants.
• strict mode: Enable it in production (strict = true) so unsigned responses are rejected — but you will need the IdP cert loaded before it works, so don't flip the switch until cert config is verified.
• Debugging assertions: When processResponse() fails, log getLastErrorReason() and the raw POSTed SAMLResponse (base64-decoded) — the toolkit's errors are often terse and don't identify which assertion field was wrong.
• v1.8.3 specific: The only change in this release is the "neuca saml" PR (#1) from a new contributor — a project-specific addition. No breaking changes, no config schema changes, no new public API surfaced in the notes. Safe to ignore unless you are the NEUCA integration. The bundle remains on the v1.x line with onelogin/php-saml 3.x/4.x as the underlying dependency; watch upstream PHP-SAML releases for the real security surface rather than the bundle patch bumps.