---
title: "The saml driver (SAML 2.0 sign-in) | SESAME docs"
description: "Browser sign-in as a SAML 2.0 service provider against a Shibboleth-style IdP, opt-in, with signed assertions required."
url: https://sesame.apps.wayne.edu/docs/guides/driver-saml.html
llms: https://sesame.apps.wayne.edu/llms.txt
generator: Squire agent-ready
---

# The saml driver (SAML 2.0 sign-in) [#](https://sesame.apps.wayne.edu/docs/guides/driver-saml.html#the-saml-driver-saml-2-0-sign-in)

The goal: sign a person into your app through the browser with SAML 2.0, with your app as the service provider (SP) and a Shibboleth-style identity provider (IdP) vouching for them. This page walks through how a sign-in runs, every config key, and what to hand the IdP's administrators; then set the driver up on the [Raw PHP](https://sesame.apps.wayne.edu/docs/guides/raw-php.html) or [Laravel](https://sesame.apps.wayne.edu/docs/guides/laravel.html) page.

Note

The saml driver is opt-in. Nothing in it runs unless `SESAME_DRIVER=saml`, and SESAME assumes no IdP: there is no default WSU IdP entity, so you name the IdP's metadata yourself. On Citadel prefer the `gateway` driver behind Drawbridge, and for Entra prefer `oidc`. Reach for SAML when the IdP you must use speaks only SAML.

## What you need [#](https://sesame.apps.wayne.edu/docs/guides/driver-saml.html#what-you-need)

Open sesame, in a language with a schema. The saml driver stands on `onelogin/php-saml`, which SESAME suggests but does not require:

```
composer require onelogin/php-saml
```

Without it, building the driver fails with `The saml driver needs onelogin/php-saml. Install it with: composer require onelogin/php-saml`. With a release older than the floor (php-saml 4.3.2, xmlseclibs 3.1.5, both for published signature and encryption advisories), building the driver fails too, and SESAME's `composer.json` refuses to install those releases beside it. Why that library, and what else was weighed: [docs/saml-library-choice.md](https://sesame.apps.wayne.edu/docs/saml-library-choice.html).

You also need:

- The IdP's metadata: an https URL, or the XML saved as a file in the deploy. Exactly one.
- A shared PSR-16 cache (in Laravel, a cache store every web server sees). The driver parks the IdP's answer there for two minutes, keeps the fetched metadata, and remembers the assertion IDs it has accepted.
- The app's session (SESAME's `SessionPort`), as for `cas` and `oidc`.
- Optionally an SP key pair, as file paths, for signed AuthnRequests and the certificate in the SP metadata.

## How a sign-in runs [#](https://sesame.apps.wayne.edu/docs/guides/driver-saml.html#how-a-sign-in-runs)

A SAML sign-in takes three requests, one more than you might expect.

1. **The start.** A request to the login URL without `saml_handle` builds an AuthnRequest (the HTTP-Redirect binding, signed when `saml.sign_authn_requests` is on), keeps its ID in the app's session (bound to this browser, single use, gone after ten minutes), and redirects to the IdP. A checked `return_to` rides along as the RelayState.
2. **The ACS.** The IdP posts its Response to the ACS URL. That POST is cross-site, so the browser sends no `SameSite=Lax` session cookie with it (S35, S41), and a session started there would replace the user's real one. So the ACS never touches the session: it parks the raw, unchecked Response in the PSR-16 cache under a random 256-bit handle (single use, two minutes) and answers `303 See Other` to the login URL with `saml_handle=<handle>`.
3. **The finish.** That GET is a top-level navigation, so the session cookie is back. The driver takes the parked Response and the pending request it answers (both single use), and php-saml validates it in strict mode: the XML schema (no DOCTYPE), the signature and exactly what it covers, Destination and Recipient against the configured ACS URL, Audience against the SP entity ID, Issuer against the IdP, InResponseTo against the pending request, the time conditions, and the bearer subject confirmation. SESAME then adds its own checks: a signed assertion (always), SHA-2 signatures and digests only, an IssueInstant no further ahead than `saml.leeway_seconds` and no older than `saml.max_assertion_age_seconds`, and an assertion ID the replay guard has never seen. The identity goes to the app's `findOrImportUser(Identity)`, and the core regenerates the session ID, as for every driver.

`sesame_login()` and the Laravel route then send the user to the checked return-to, so the handle never stays in the address bar.

IdP-initiated (unsolicited) responses are refused: a sign-in must start at the app. A Response that answers another browser's request (login CSRF) is refused too, because the pending request lives in this browser's session.

## Identity, attributes and MFA [#](https://sesame.apps.wayne.edu/docs/guides/driver-saml.html#identity-attributes-and-mfa)

`saml.attributes` maps SESAME's names to the SAML attribute names the IdP releases; the first name present wins. The defaults are the eduPerson and inetOrgPerson OIDs a Shibboleth IdP releases, then their friendly names:

| SESAME name | SAML attribute names (default) |
| --- | --- |
| `accessid` | `urn:oid:0.9.2342.19200300.100.1.1`, `uid` |
| `email` | `urn:oid:0.9.2342.19200300.100.1.3`, `mail` |
| `name` | `urn:oid:2.16.840.1.113730.3.1.241`, `displayName` |
| `affiliations` | `urn:oid:1.3.6.1.4.1.5923.1.1.1.1`, `eduPersonAffiliation` |
| `eppn` | `urn:oid:1.3.6.1.4.1.5923.1.1.1.6`, `eduPersonPrincipalName` |

The username comes from `saml.username_attribute` (default `accessid`). When the assertion has no such attribute, the sign-in fails with `saml.missing_attribute` and the error names the settings to change. The mapped attributes reach the resolver under SESAME's names (`$identity->attributes['affiliations']`), along with `issuer`, `name_id` (when the IdP sends one) and `authn_context`.

The AuthnStatement gives the MFA facts. `AuthnInstant` becomes the identity's sign-in time (never invented: without one, the MFA check fails closed). An `AuthnContextClassRef` listed in `saml.mfa_contexts` (the REFEDS MFA profile, `https://refeds.org/profile/mfa`, by default) adds `mfa` to the methods, and the class reference is also the identity's authentication context, so `sesame.context:https://refeds.org/profile/mfa` works. `saml.assume_mfa` counts every sign-in as MFA, for an IdP that enforces MFA for this SP but does not say so.

## Step-up and return-to [#](https://sesame.apps.wayne.edu/docs/guides/driver-saml.html#step-up-and-return-to)

A login request with `step_up=1` sends `ForceAuthn="true"`, so the IdP asks for credentials again. The finish then requires a fresh `AuthnInstant`: not in the future beyond the leeway, not before the sign-in started, and within 300 seconds. In Laravel, `sesame.mfa` with `mfa.on_failure=reauth` sends the user to `/login?step_up=1` for you.

A login request may carry `return_to`. It goes out as the RelayState only when it passes the ReturnTo rule (an absolute https URL with the login URL's scheme, host and port, and no user name or password), and the RelayState that comes back is checked again with the same rule, so it can never be an open redirect.

## Logout [#](https://sesame.apps.wayne.edu/docs/guides/driver-saml.html#logout)

Local only. There is no single logout: SESAME refuses `slo` at boot, so the app session is cleared and the IdP's session lives on (the next sign-in is usually silent).

## Raw PHP [#](https://sesame.apps.wayne.edu/docs/guides/driver-saml.html#raw-php)

The ACS is its own page, and it must NOT call `session_start()`.

```php
<?php
// boot-saml.php: shared by the three pages below. No session_start() here.

declare(strict_types=1);

require __DIR__.'/vendor/autoload.php';

use Nyholm\Psr7\Factory\Psr17Factory;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\Cache\Psr16Cache;
use Waynestate\Sesame\Config;
use Waynestate\Sesame\DriverFactory;
use Waynestate\Sesame\Session\NativeSession;

$config = Config::fromArray([
    'driver' => 'saml',
    'environment' => 'production',
    'saml' => [
        'sp' => [
            'entity_id' => 'https://app.example.test/metadata.php',
            'acs_url' => 'https://app.example.test/acs.php',
            'cert_file' => getenv('SESAME_SAML_SP_CERT_FILE') ?: null,
            'key_file' => getenv('SESAME_SAML_SP_KEY_FILE') ?: null,
        ],
        'idp' => [
            'metadata_file' => __DIR__.'/config/idp-metadata.xml',
        ],
        'service_url' => 'https://app.example.test/login.php',
    ],
]);

$session = new NativeSession(); // does not start the session
$driver = DriverFactory::make(
    $config,
    new \GuzzleHttp\Client(['allow_redirects' => false, 'timeout' => 10]), // only for a metadata URL
    new Psr17Factory(),
    null,
    null,
    new Psr16Cache(new FilesystemAdapter('sesame')), // shared by every web server
    $session,
);
```

```php
<?php
// acs.php: the IdP posts here. No session_start(): the 303 goes to login.php.
require __DIR__.'/boot-saml.php';
sesame_saml_acs($driver);
```

```php
<?php
// metadata.php: the SP metadata for the IdP's administrators.
require __DIR__.'/boot-saml.php';
sesame_saml_metadata($driver);
```

```php
<?php
// login.php: starts the sign-in, finishes it with the saml_handle, then
// sends the user to the checked return_to or back here.
require __DIR__.'/boot-saml.php';

use Waynestate\Sesame\Sesame;

ini_set('session.gc_maxlifetime', '7200'); // at least SESAME's idle timeout; see Raw PHP
// Or call helmet_boot(), which sets all of this. NativeSession warns without it.
ini_set('session.use_strict_mode', '1');
session_set_cookie_params(['httponly' => true, 'secure' => true, 'samesite' => 'Lax']);
session_start();

sesame(new Sesame($driver, new MyUserResolver(), $session, $config));

$user = sesame_login();
```

A protected page sends a guest to `login.php?return_to=<its own https URL>`, and a page that needs fresh credentials to `login.php?step_up=1`.

## Laravel [#](https://sesame.apps.wayne.edu/docs/guides/driver-saml.html#laravel)

```
SESAME_DRIVER=saml
SESAME_SAML_IDP_METADATA_URL=<the IdP's metadata URL>
# or SESAME_SAML_IDP_METADATA_FILE=/path/to/idp-metadata.xml
# The SP entity ID, the ACS URL and the login URL default to the app's
# /login/saml/metadata, /login/saml/acs and /login routes.
SESAME_SAML_SP_CERT_FILE=/path/to/sp.crt
SESAME_SAML_SP_KEY_FILE=/path/to/sp.key
SESAME_SAML_CACHE_STORE=redis
```

The adapter registers two more routes beside `GET /login`, both outside the `web` middleware group, because neither may start a session:

| Route | Name | What it does |
| --- | --- | --- |
| `POST /login/saml/acs` | `sesame.saml.acs` | Parks the IdP's Response and answers 303 to `/login?saml_handle=...`; an unusable POST gets a plain 400. No session, no CSRF token (the IdP cannot send one). |
| `GET /login/saml/metadata` | `sesame.saml.metadata` | The SP metadata as `application/samlmetadata+xml`. |

It passes the Laravel session and the `sesame.saml.cache_store` cache to the driver. Laravel's default `SameSite=Lax` session cookie is right: the browser drops it on the IdP's POST, which is why the ACS parks the response, and sends it on the 303's GET. `Strict` would drop it on that GET too.

## What to hand the IdP's administrators [#](https://sesame.apps.wayne.edu/docs/guides/driver-saml.html#what-to-hand-the-idp-s-administrators)

Send them the SP metadata URL (`/login/saml/metadata` in Laravel). It carries the entity ID, the ACS URL with the HTTP-POST binding, `WantAssertionsSigned="true"` and, when set, the SP certificate. Ask them:

- to **sign assertions** (Shibboleth's `signAssertions` for this SP). SESAME refuses an unsigned assertion even inside a signed Response;
- to release the attributes in `saml.attributes` (by default the AccessID as `uid`, plus `mail`, `displayName` and `eduPersonAffiliation`);
- to sign with SHA-256 or better; SHA-1 is refused;
- not to encrypt assertions unless the app has an SP key pair to decrypt them with.

## Config keys [#](https://sesame.apps.wayne.edu/docs/guides/driver-saml.html#config-keys)

| Key | Env | Default | Meaning |
| --- | --- | --- | --- |
| `saml.sp.entity_id` | `SESAME_SAML_SP_ENTITY_ID` | Laravel: `/login/saml/metadata` | The SP's entity ID, as the IdP knows the app. Required in raw PHP. |
| `saml.sp.acs_url` | `SESAME_SAML_SP_ACS_URL` | Laravel: `/login/saml/acs` | Where the IdP posts its Response. https, or `http://localhost` for development. Required in raw PHP. |
| `saml.service_url` | `SESAME_SAML_SERVICE_URL` | Laravel: `/login` | The login URL, where a sign-in starts and finishes; every return-to must stay on its host. Required in raw PHP. |
| `saml.sp.cert_file`, `saml.sp.key_file` | `SESAME_SAML_SP_CERT_FILE`, `SESAME_SAML_SP_KEY_FILE` | none | The SP's PEM certificate and private key, as file paths; set both or neither. The key must match the certificate. Never inline, never logged: the key is held in a `SensitiveParameterValue`. |
| `saml.sign_authn_requests` | `SESAME_SAML_SIGN_AUTHN_REQUESTS` | `false` | Sign the AuthnRequest (RSA-SHA256). Needs the SP key pair. |
| `saml.want_messages_signed` | `SESAME_SAML_WANT_MESSAGES_SIGNED` | `false` | Also require a signed Response. The assertion signature is required either way. |
| `saml.idp.metadata_url` | `SESAME_SAML_IDP_METADATA_URL` | none | The IdP's metadata, https only, fetched without following redirects and cached. Set this or the file. |
| `saml.idp.metadata_file` | `SESAME_SAML_IDP_METADATA_FILE` | none | The IdP's metadata XML as a file, read at boot (a bad file stops the app). Set this or the URL. |
| `saml.idp.entity_id` | `SESAME_SAML_IDP_ENTITY_ID` | none | Which IdP in the metadata to trust; required when the document holds more than one. No default WSU IdP. |
| `saml.idp.cert_file` | `SESAME_SAML_IDP_CERT_FILE` | the metadata's signing certificates | Pin the IdP's signing certificate. |
| `saml.attributes` | `SESAME_SAML_ATTRIBUTE_ACCESSID`, `_EMAIL`, `_NAME`, `_AFFILIATIONS`, `_EPPN` | the table above | SESAME's name to SAML attribute names, comma-separated; an empty value keeps the default for that name. |
| `saml.username_attribute` | `SESAME_SAML_USERNAME_ATTRIBUTE` | `accessid` | Which mapped attribute becomes the username. |
| `saml.mfa_contexts` | `SESAME_SAML_MFA_CONTEXTS` | `https://refeds.org/profile/mfa` | AuthnContextClassRef values that count as MFA. |
| `saml.assume_mfa` | `SESAME_SAML_ASSUME_MFA` | `false` | Count every sign-in as MFA, when the IdP enforces it for this SP. |
| `saml.authn_context` | `SESAME_SAML_AUTHN_CONTEXT` | none | AuthnContextClassRef values to request (a RequestedAuthnContext); none is sent by default. |
| `saml.leeway_seconds` | `SESAME_SAML_LEEWAY_SECONDS` | `60` | Clock skew on the IssueInstant and the step-up checks, 0 to 180 seconds. php-saml's own conditions allow a fixed 180. |
| `saml.max_assertion_age_seconds` | `SESAME_SAML_MAX_ASSERTION_AGE_SECONDS` | `300` | The oldest an assertion may be, by its IssueInstant, 30 to 3600 seconds. |
| `saml.metadata_cache_ttl_seconds` | `SESAME_SAML_METADATA_CACHE_TTL_SECONDS` | `3600` | How long fetched metadata is kept, 60 to 86400 seconds. |
| `saml.request_ttl_seconds` | none | `600` | How long a started sign-in may take, 60 to 3600 seconds. |
| `saml.cache_store` | `SESAME_SAML_CACHE_STORE` | the default store | Laravel only. Must be shared by every web server of the app. |

## Errors [#](https://sesame.apps.wayne.edu/docs/guides/driver-saml.html#errors)

Every refusal is an `AuthenticationFailed` with a short reason in parentheses, never a value from the XML:

| Reason | What happened |
| --- | --- |
| `saml.acs` | The ACS got no usable `SAMLResponse` (not a POST, empty, too large, not base64). |
| `saml.handle` | The `saml_handle` is unknown, used, or older than two minutes. |
| `saml.response` | The Response is not well-formed XML, or carries a DOCTYPE. |
| `saml.unsolicited` | The Response answers no request (IdP-initiated). |
| `saml.in_response_to` | It answers a request this browser did not send, or one already used or expired. |
| `saml.invalid: <code>` | php-saml refused it; the code is its `ValidationError` name, for example `no_signed_assertion`, `invalid_signature`, `wrong_audience`, `wrong_issuer`, `wrong_destination`, `assertion_expired` or `wrong_number_of_assertions`. |
| `saml.algorithm` | A signature or digest outside SHA-2. |
| `saml.issue_instant`, `saml.too_old` | The IssueInstant is in the future beyond the leeway, or older than the maximum age. |
| `saml.replay` | The assertion ID was accepted before. |
| `saml.step_up` | A step-up sign-in was not fresh. |
| `saml.missing_attribute` | The username attribute is missing. |
| `saml.metadata` | The IdP metadata could not be fetched or used. |

## Related [#](https://sesame.apps.wayne.edu/docs/guides/driver-saml.html#related)

- [Which driver for my app?](https://sesame.apps.wayne.edu/docs/guides/which-driver.html)
- [The saml driver's library choice](https://sesame.apps.wayne.edu/docs/saml-library-choice.html)
- [The oidc driver](https://sesame.apps.wayne.edu/docs/guides/driver-oidc.html)
- [The gateway driver](https://sesame.apps.wayne.edu/docs/guides/driver-gateway.html)
- [The cas driver](https://sesame.apps.wayne.edu/docs/guides/driver-cas.html)
- [Raw PHP](https://sesame.apps.wayne.edu/docs/guides/raw-php.html)
- [Laravel](https://sesame.apps.wayne.edu/docs/guides/laravel.html)
- [Requiring MFA](https://sesame.apps.wayne.edu/docs/guides/requiring-mfa.html)
- [Step-up (authentication context)](https://sesame.apps.wayne.edu/docs/guides/step-up.html)
