Laravel4 Saml2 Laravel Package

Getting Started

1. Install a pinned version, not a branch. In composer.json:

   "pitbulk/laravel4-saml2": "0.0.5"
   

   Laravel 4 has no package auto-discovery, so a dev-master constraint will silently drift.

2. Register the service provider in app/config/app.php under providers (confirm the exact class name in vendor/pitbulk/laravel4-saml2/composer.json and the README — it is a Pitbulk\Laravel4Saml2\…ServiceProvider). Laravel 4 does not do this for you.

3. Publish the config so you own a copy:

   php artisan config:publish pitbulk/laravel4-saml2
   

   This lands under app/config/packages/pitbulk/laravel4-saml2/. That config file is the single most important thing to read — it mirrors the OneLogin_Saml2_Settings array, so the structure should look like idp (entityId, singleSignOnService.url, x509cert) and sp (entityId, assertionConsumerService.url, singleLogoutService.url, optional signing cert/key).

4. Where to look first, in order:

   • vendor/pitbulk/laravel4-saml2/README.md — settings shape and route names.
   • The service provider in src/ — what routes and controllers it registers (login, ACS, logout, metadata).
   • The published config — every IdP/SP value you must fill in.

5. Configure the IdP. Pull the entityId, SSO URL, and signing certificate from your IdP's metadata XML. Paste the certificate body only (no -----BEGIN CERTIFICATE----- fences, no trailing whitespace).

6. First use case: SP-initiated SSO. Register your app with the IdP using the SP entity ID and the ACS URL the package exposes, hit the package's login route from a controller or view, get redirected to the IdP, and land back on the ACS route with a validated assertion. Verify the session before wiring any authorization logic.

Implementation Patterns

• SP-initiated login with intended URL. Don't link the package's login route raw. Capture the current URL in the session (the same shape as Laravel's Auth::guest redirect), redirect to SAML login, and after the ACS completes, redirect back to the stored intended URL. This is the pattern you'll copy into every protected entry point.

• Bridge the assertion to Laravel auth explicitly. The package establishes a SAML session; it does not necessarily create an Eloquent User. In the ACS completion path, map the IdP NameID (or a chosen attribute like email) to your User model, then call Auth::login($user) and Session::regenerate(). Treat the SAML session as a credential, not as your application session.

• Protect routes with a thin middleware. Write a SamlAuth middleware that checks the package's session key (often something like samlSessionData / samlUser) and redirects to the login route preserving intended. This keeps SAML concerns out of controllers, and gives you one place to swap the check if you replace the package.

• Serve SP metadata to the IdP admin. Most IdPs want your SP metadata XML rather than manual entry. Hit the package's metadata route, save the output, and upload it — then confirm the ACS/entity ID in the IdP match what the package generates exactly. This avoids the most common first-day mismatch.

• Use environment-specific config folders. Laravel 4 supports app/config/<environment>/packages/…. Keep real IdP certificates and entity IDs in environment config (or env vars injected into the config array), not in a committed default file. Keep a local/testing IdP (e.g. samltest.id or a self-hosted test IdP) so developers never authenticate against production.

• Handle SLO deliberately. Single Logout is where most integrations get sloppy. Decide whether logout is SP-initiated (call the package logout route) or IdP-initiated (the IdP POSTs to your SLS endpoint and you must invalidate the Laravel session too). Wire the logout controller so both Auth::logout() and the SAML session clear happen together.

• Wrap the package behind an internal interface. Define something like SamlAuthenticator with login(), consume(), logout(), metadata(). Implement it with the package now; because the package is 0.0.x and low-adoption, you may later reimplement the same interface directly on OneLogin_Saml2_Auth in a day. This is the single most valuable pattern given the package's maturity.

• Multi-tenant / multi-IdP. The published config is static per application. If you need per-tenant IdPs, bypass the package's controller: build a settings array at runtime from the tenant record, instantiate OneLogin_Saml2_Auth yourself, and only reuse the package's views/routes as a reference.

• Test without a real IdP. Unit-test your mapping logic by constructing the settings array and calling OneLogin_Saml2_Settings / OneLogin_Saml2_Auth directly. For end-to-end, point your local environment at a test IdP and assert the ACS behavior (success, invalid signature, expired assertion, unknown SP) rather than mocking SAML.

Gotchas and Tips

• Laravel 4 is EOL; PHP 7+ is a risk. The wrapped onelogin/php-saml version may be old enough to break under modern PHP. Check vendor/onelogin/php-saml and robrichards/xmlseclibs versions in composer.lock, and pin them. If your runtime is PHP 7.2+, test the full login flow before assuming it works.

• Pin the exact version and read diffs. The only release note between 0.0.4 and 0.0.5 is "fix several issues." That vague changelog means every 0.0.x bump is an unvetted change. Diff the vendor tree or the GitHub compare view before upgrading.

• Proxy / load balancer URL mismatch is the #1 failure. The ACS URL is derived from Laravel's URL generator. Behind TLS termination or a proxy, this can come out as http:// or the wrong host, and the IdP rejects with Destination mismatch, InvalidResponse, or signature errors. Force the root URL and scheme in your app bootstrap so the generated ACS URL matches what the IdP was registered with.

• Exact-match ACS URLs. The IdP compares the ACS URL precisely — trailing slash, scheme, port, and query string all matter. Copy it from the IdP admin and the package output and diff them character by character.

• Certificate formatting. Paste the base64 body only, no PEM headers, no line-ending differences. A common symptom of a malformed cert is a signature validation failure that looks like a wrong key.

• Keep strict mode on. php-saml with strict: false skips important validation and is a security hole. But turning it on is exactly what surfaces destination/audience/clock issues — so do it in staging early rather than flipping it late.

• Clock skew. Assertion NotBefore / NotOnOrAfter are compared against server time. NTP drift on either side causes intermittent "not yet valid" / "expired" errors that look nondeterministic. Check both servers' clocks before debugging signatures.

• Session semantics. The package's SAML session key is not Auth::check(). Decide early whether Auth is driven by the SAML session or by an Eloquent user, and make sure logout clears both. Regenerate the session ID after a successful ACS to prevent fixation.

• Debug mode is development-only. php-saml debug output goes to its own log/stderr and can leak assertion contents. Enable briefly in staging, then remove it — never ship with it on.

• Route collisions. The package registers routes. If you already own /login, /logout, or a /saml/* path, either override them in app/routes.php or skip the package routes and write your own controller calling the service layer.

• Metadata endpoint quirks. If the IdP consumed your metadata before you changed the SP certificate, re-upload it. Stale metadata is a silent cause of "everything looks right but signatures fail."

• Plan the exit. With 2 stars and a 2016 release, assume the maintainer may not respond. Keep the integration behind your own interface and vendor the config; replacing the package with direct php-saml calls is small, and doing it while the interface is fresh is far cheaper than doing it during an incident.