Download the PHP package jdlien/laravel-saml without Composer

Laravel SAML

A SAML 2.0 toolkit for Laravel, built around SAML-Toolkits/php-saml (on packagist as onelogin/php-saml).

Requirements

• PHP ^8.3
• Laravel ^12.0 or ^13.0
• ext-openssl

Installation

The service provider is auto-discovered. Publish the config:

This creates config/saml.php. The shape mirrors the OneLogin PHP toolkit settings; see that project's docs for advanced options.

Configuration

Single IdP

If your application authenticates against a single IdP, fill in the idp section of config/saml.php (or supply the corresponding SAML_IDP_* env vars). The package auto-registers the resolver on boot.

Multiple IdPs

For multi-IdP scenarios, leave idp unset in config/saml.php and register a resolver from a service provider:

Calling Saml::idp($name)->redirect() resolves through the closure and caches the resulting SamlAuth instance.

Cert and key values

x509cert and privateKey accept either inline PEM strings or filesystem paths. Paths can be:

• Absolute — /etc/ssl/certs/saml.crt
• Relative to project root — storage/certs/saml.crt (resolved against Laravel's base_path(), so it works under php-fpm, queue workers, and scheduled tasks regardless of the current working directory)
• Relative to PHP's CWD — works for php artisan but not recommended; prefer the project-root form

If a value looks like a path (string, no newlines, ≤4096 chars) but no file is found at either location, Saml::normalizeConfig() throws InvalidConfigException naming the offending config key.

Usage

For multi-IdP scenarios, swap any Saml::method() call below for Saml::idp($name)->method() to target a specific IdP.

Controller Scaffold

Routes

Middleware Requirements

• The SAML routes must run under session middleware (typically the web group). The package reads/writes saml.authnRequestId and saml.logoutRequestId on the session to correlate requests with responses.

• The POST /acs route must be excluded from CSRF validation, because the IdP's POST will not include a Laravel CSRF token. In Laravel 11+/12+:

  In older apps, add the same path to App\Http\Middleware\VerifyCsrfToken::$except.

• If you also expose a POST SLS endpoint for an IdP that uses HTTP-POST binding for SLO, exclude that route too.

Redirect to the IdP Login

Initiates SSO.

Assertion Consumer Service (ACS)

Handles the IdP's authentication response. Returns a SamlUser (which wraps the OneLogin Auth object plus convenience accessors).

Redirect to IdP Logout

The IdP returns a Logout Response through the user's browser to your /sls endpoint.

Single Logout Service (SLS)

Handles both Logout Responses (SP-initiated logout) and Logout Requests (IdP-initiated logout).

Metadata Endpoint

Publishes the SP metadata XML so the IdP can register your service.

Security

RelayState Validation

SamlUser::getIntendedUrl() is the safe accessor for the SAML RelayState — it validates the value against open-redirect attacks. It returns:

• relative paths (e.g. /dashboard) as-is
• absolute URLs only when the host matches the application host

It returns null for cross-origin URLs, protocol-relative URLs (//example.com/...), javascript: / data: / other non-HTTP schemes, and anything malformed. Always prefer getIntendedUrl() over the raw RelayState when redirecting users after login.

If you have a legitimate reason to inspect the unvalidated value (e.g. logging, custom validation), use getRawRelayState() — but treat its output as user-controlled input.

Underlying SAML Implementation

The actual SAML 2.0 protocol logic — signature validation, XML canonicalization, encrypted assertion handling, etc. — lives in onelogin/php-saml. This package's job is the Laravel binding; it intentionally doesn't reimplement protocol primitives.

Migrating from overtrue/laravel-saml

This package is a successor to overtrue/laravel-saml. Migration is intentionally cheap:

1. Update composer.json:

   Then composer update jdlien/laravel-saml.

2. Update the service provider reference if you registered it manually (auto-discovered installs need no change). In bootstrap/providers.php (Laravel 11+) or config/app.php:

3. Existing imports keep working — a compat shim aliases every Overtrue\LaravelSaml\… class name to its new home. You can update use statements at your leisure. The compat shim will be removed in v3.0.

4. Facade calls (Saml::redirect(), etc.) need no changes. The facade name is preserved.

See CHANGELOG.md for behavior changes that may affect existing consumers.

Testing

License

MIT. See LICENSE.

Originally based on overtrue/laravel-saml by @overtrue. Now maintained as an independent package by @jdlien — modernized for Laravel 12/13 and PHP 8.3+, with bug fixes, security hardening, and full Pest 4 test coverage.