Laravel#
The Laravel adapter is a service provider that binds the core into the container, registers the auth.sesame, sesame.mfa and sesame.context middleware aliases, and, unless the app has taken the routes over, registers the login and logout routes. It holds no rules of its own: every rule lives in the core. This page is how to wire it into an app and read the signed-in user back; next, see Requiring MFA and Step-up (authentication context) for the checks the middleware runs.
Install and publish#
The provider is discovered automatically. Publish the config with:
php artisan vendor:publish --tag=sesame-config
The app's environment becomes the core's environment, the cas.service_url falls back to the app's /login route when the app has not set one, and the oidc driver's redirect_uri falls back to the app's /login/callback route. For the saml driver, saml.service_url, saml.sp.acs_url and saml.sp.entity_id fall back to the app's /login, /login/saml/acs and /login/saml/metadata routes.
Config#
Config keys (in config/sesame.php):
| Key | Env | Default | Meaning |
|---|---|---|---|
driver |
SESAME_DRIVER |
cas |
cas, gateway, oauth2, oidc, saml or fake. The oidc keys are in The oidc driver, the saml keys in The saml driver. |
cas.base_url |
SESAME_CAS_BASE_URL |
none | The CAS server, an absolute https:// URL (http://localhost or http://127.0.0.1 only in a local environment). |
cas.service_url |
SESAME_CAS_SERVICE_URL |
the app's /login route |
Where the server sends the user back to: an absolute https:// URL, or http://localhost or http://127.0.0.1 in a local environment. |
cas.protocol |
SESAME_CAS_PROTOCOL |
2.0 |
3.0 or 2.0. |
cas.assume_mfa |
SESAME_CAS_ASSUME_MFA |
false |
A successful validation counts as an MFA sign-in. On only when the CAS server enforces MFA for every sign-in. |
fake.username |
SESAME_FAKE_USERNAME |
none | The fake driver's username. |
gateway.header |
SESAME_GATEWAY_HEADER |
X-Sesame-Assertion |
The one header that holds the signed assertion. |
gateway.algorithm |
SESAME_GATEWAY_ALGORITHM |
ES256 |
ES256, RS256 or EdDSA. |
gateway.public_key |
SESAME_GATEWAY_PUBLIC_KEY |
none | The gateway's public key. Required for the gateway driver. |
gateway.issuer |
SESAME_GATEWAY_ISSUER |
none | The iss claim the assertion must carry. Required for the gateway driver. |
gateway.audience |
SESAME_GATEWAY_AUDIENCE |
none | The aud claim the assertion must carry. Required for the gateway driver. |
gateway.leeway_seconds |
SESAME_GATEWAY_LEEWAY_SECONDS |
30 |
Clock skew allowed on the time-claim checks, in seconds. |
gateway.trusted_proxies |
SESAME_GATEWAY_TRUSTED_PROXIES |
none | Comma-separated CIDR ranges (or single IPs) the gateway proxy sits behind. Required for the gateway driver. |
gateway.max_lifetime |
SESAME_GATEWAY_MAX_LIFETIME |
300 |
The longest an assertion may live, in seconds. |
gateway.replay_store |
SESAME_GATEWAY_REPLAY_STORE |
the app's default cache store | The cache store the used jtis are kept in (Laravel only). |
gateway.allow_without_replay_guard |
SESAME_GATEWAY_ALLOW_WITHOUT_REPLAY_GUARD |
false |
Skip the replay guard. Local development only. |
oauth2.issuer |
SESAME_OAUTH2_ISSUER |
none | The iss claim the token must carry. Required for the oauth2 driver. |
oauth2.jwks_url |
SESAME_OAUTH2_JWKS_URL |
none | The URL of the issuer's key set. Required for the oauth2 driver. |
oauth2.audience |
SESAME_OAUTH2_AUDIENCE |
none | The aud claim the token must carry. Required for the oauth2 driver. |
oauth2.leeway_seconds |
SESAME_OAUTH2_LEEWAY_SECONDS |
60 |
Clock skew allowed on the time-claim checks, in seconds. |
oauth2.identity_claim |
SESAME_OAUTH2_IDENTITY_CLAIM |
preferred_username |
The claim the username comes from: preferred_username or accessid. |
oauth2.jwks_cache_ttl_seconds |
SESAME_OAUTH2_JWKS_CACHE_TTL_SECONDS |
3600 |
How long the fetched key set is kept, in seconds. |
oauth2.jwks_store |
SESAME_OAUTH2_JWKS_STORE |
the app's default cache store | The cache store the key set is kept in (Laravel only). |
oauth2.require_at_jwt |
SESAME_OAUTH2_REQUIRE_AT_JWT |
false |
Refuse a token whose typ header is not at+jwt (RFC 9068). Leave it off for Entra. |
oauth2.introspection_url |
SESAME_OAUTH2_INTROSPECTION_URL |
none | The RFC 7662 endpoint for opaque bearer tokens. Leave it unset to keep the driver JWT-only. |
oauth2.introspection_client_id |
SESAME_OAUTH2_INTROSPECTION_CLIENT_ID |
none | The client id sent as HTTP Basic auth to the introspection endpoint. Required when the URL is set. |
oauth2.introspection_client_secret |
SESAME_OAUTH2_INTROSPECTION_CLIENT_SECRET |
none | The client secret sent as HTTP Basic auth to the introspection endpoint. Required when the URL is set. |
oauth2.introspection_cache_ttl_seconds |
SESAME_OAUTH2_INTROSPECTION_CACHE_TTL_SECONDS |
60 |
How long an accepted introspection answer is kept, in seconds, capped by the token's exp. Zero disables the cache. |
session.idle_minutes |
SESAME_SESSION_IDLE_MINUTES |
120 |
Drop the session after this much quiet time, in minutes. |
session.absolute_minutes |
SESAME_SESSION_ABSOLUTE_MINUTES |
720 |
End the session this long after sign-in, in minutes. |
mfa.max_age |
SESAME_MFA_MAX_AGE |
28800 |
The longest a user's last MFA sign-in may be, in seconds. |
mfa.on_failure |
SESAME_MFA_ON_FAILURE |
deny |
deny answers a 403; reauth redirects to the login route. |
routes |
SESAME_ROUTES |
true |
Register the login and logout routes. |
log |
SESAME_LOG |
true |
Log the sign-in and sign-out events through the app's PSR-3 logger. Set to false to turn them off. |
user_resolver |
SESAME_USER_RESOLVER |
none | The class that resolves a verified identity to the app's user. Required. For a model with a static findOrImportUser, use the ready-made \Waynestate\Sesame\Laravel\ModelUserResolver. |
A missing user_resolver fails with an error that names ModelUserResolver, the ready-made resolver for a model with a static findOrImportUser. The driver is built lazily: resolving SESAME does not build it, so guests on http, artisan commands, queue workers and tests can ask who is signed in; the driver (and its https check) is built when someone signs in or out, and an app with a broken config still boots and answers signed-out requests.
Routes#
The routes, when routes is true:
| Method | Path | Name |
|---|---|---|
GET |
/login |
sesame.login |
POST |
/logout |
sesame.logout (in the web group, so Laravel's CSRF check applies; a form needs @csrf) |
GET |
/login/callback |
sesame.callback (oidc driver only) |
POST |
/login/saml/acs |
sesame.saml.acs (saml driver only; outside the web group, so no session and no CSRF token: the IdP's POST cannot carry either) |
GET |
/login/saml/metadata |
sesame.saml.metadata (saml driver only; the SP metadata) |
Set SESAME_ROUTES=false when the app defines its own login and logout routes. The auth.sesame middleware still points at the sesame.login route name, so the app's login route must keep that name.
Middleware#
Protect a route with the auth.sesame middleware:
Route::get('/dashboard', fn () => view('dashboard'))->middleware('auth.sesame');
A guest is sent to the login route; a JSON guest gets a 401.
Require MFA on a route with the sesame.mfa middleware:
Route::get('/vault', fn () => view('vault'))->middleware(['auth.sesame', 'sesame.mfa']);
It lets the request through when the signed-in user's MFA is still good, and otherwise stops it: a 403 by default, a JSON 403 for JSON requests, and a redirect to the login route when mfa.on_failure is reauth. The allowed age comes from the route parameter when there is one, and from mfa.max_age when there is not:
Route::get('/vault', fn () => view('vault'))->middleware(['auth.sesame', 'sesame.mfa:3600']);
The sesame.context middleware does the step-up context check on a route:
Route::get('/vault', [VaultController::class, 'index'])
->middleware(['web', 'auth.sesame', 'sesame.context:c1']);
A request without the context gets a 403, or a JSON 403 with a message for JSON requests. A route that names no context fails closed. See Step-up (authentication context).
An app moving off wayne-cas follows Moving from wayne-cas.
Reading the user#
The app's user is available through the facade:
$user = app(\Waynestate\Sesame\Sesame::class)->user();
SESAME stores the user your resolver returned at sign-in and hands back that same copy until the session ends. When the app wants the signed-in user read back from its own store on every request, so a change made after the sign-in (a removed role, a deleted account) shows up from the next request on, the resolver also implements Waynestate\Sesame\RefreshesUser: its refreshUser($user) runs on every request, and a null answer signs the session out. \Waynestate\Sesame\Laravel\ModelUserResolver is the ready-made resolver for a model with a static findOrImportUser: it implements both interfaces, looks the user up through auth.providers.users.model, and an Eloquent model works as it is, with or without JSON session serialization, so an app needs no resolver of its own. An app moving off wayne-cas points user_resolver at it as well; see Moving from wayne-cas. A resolver that does not implement RefreshesUser keeps handing back the stored copy, as it always has.
On Laravel 13, a resolver of your own must implement it. Laravel 13 stores sessions as JSON, so the user SESAME saved at sign-in comes back on the next request as a plain array instead of the app's User model, and a resolver that hands the array back leaves the guard seeing nobody. ModelUserResolver looks the array up through the model itself, so an app on it needs no change. refreshUser() receives that array (or the model itself when the session is still PHP-serialized) and must return the app's User: look it up by a stable key such as the username or the primary key, and return null when the user is gone, which signs the session out. Sourdough's Laravel templates already ship this:
public function refreshUser(mixed $user): mixed
{
$username = match (true) {
$user instanceof User => $user->username,
is_array($user) => $user['username'] ?? null,
default => null,
};
if (! is_string($username) || $username === '') {
return null;
}
return User::where('username', $username)->first();
}
The same user is available through Laravel's own auth, because the provider registers a sesame guard driver. Point a guard in config/auth.php at it:
'guards' => [
'web' => [
'driver' => 'sesame',
'provider' => 'users',
],
],
and the usual calls work against the SESAME session: auth()->user(), $request->user(), Auth::check(), and the auth middleware. The note above applies here too: the guard hands back the stored copy, or the refreshed one when the resolver refreshes. A user that is not an Illuminate\Contracts\Auth\Authenticatable reads as null through the guard; the auth.sesame middleware still sees it, because it checks the SESAME session directly.
auth()->logout() signs the user out of both sides, the Laravel session and the SESAME session. The identity provider's single sign-on session is left alone.
HTTP client and caches#
The cas and oauth2 drivers need a PSR-18 client. The adapter uses the app's Psr\Http\Client\ClientInterface binding when there is one, Guzzle when it is installed (with redirects off), and nothing when there is neither. Bind a client when the app has neither:
app()->singleton(
Psr\Http\Client\ClientInterface::class,
fn () => new \Symfony\Component\HttpClient\Psr18Client(),
);
The oauth2 driver also keeps its fetched key set in a PSR-16 cache. The adapter wires one up from the app's cache, using the store named by oauth2.jwks_store, or the default store when none is named. The gateway driver's replay guard is wired the same way, from the store named by gateway.replay_store, so a captured assertion cannot be played back a second time.
Logging#
The adapter passes the app's PSR-3 logger to the core, so a Laravel app gets the authentication events in its normal log channels with no extra wiring: the container's Psr\Log\LoggerInterface binding is used when there is one. Set sesame.log (env SESAME_LOG) to false to turn the events off; the default is true. The events, their context and what is never logged are described in Raw PHP, "Logging".
Metrics#
Set sesame.metrics.enabled (env SESAME_METRICS_ENABLED) to true and the adapter counts every finished sign-in as sesame_logins_total, by driver and outcome. It writes to the app's Prometheus\Storage\Adapter binding when there is one, else to the store HELMET's request metrics use, so turn those on too (HELMET_METRICS_ENABLED=true and HELMET_METRICS_STORAGE) and the counter shows on HELMET's /metrics. The store is opened on the first sign-in of a request, never before. Off by default. See Counting sign-ins.
Check before a deploy#
In Laravel, SESAME rides on the app's own session, so config/session.php decides whether sign-in works at all. php artisan sesame:check reads those settings and SESAME's own, prints one line for each, and exits 1 when anything fails, so a deploy job can run it first:
$ php artisan sesame:check
[OK] Driver: cas is configured.
[OK] User resolver: set.
[OK] Session driver: file.
[OK] Session cookie: HttpOnly.
[FAIL] Session cookie: SameSite=Strict drops the cookie on the identity provider's return, so every sign-in fails; use lax.
[OK] Session cookie: Secure.
[OK] Session lifetime: 120 minutes, SESAME's idle timeout is 120.
6 ok, 0 warnings, 1 failure.
| Line | OK | WARN | FAIL |
|---|---|---|---|
| Driver | the driver builds from config/sesame.php |
it does not (the line gives the reason; the fake driver outside local, development and testing is one) | |
| User resolver | sesame.user_resolver names a class that implements Waynestate\Sesame\UserResolver |
it is empty, or names something else | |
| Session driver | file, database, redis or any other store |
cookie (the whole session lives in the browser) |
array (the session ends with the request, so a sign-in never sticks) |
| HttpOnly | session.http_only is true |
anything else | |
| SameSite | lax |
none, or no value |
strict (the identity provider's return is a cross-site GET, which drops a Strict cookie) |
| Secure | true |
unset (it follows each request's scheme), or false outside production |
false in production |
| Session lifetime | session.lifetime is at least sesame.session.idle_minutes, or the session ends when the browser closes |
Laravel drops a quiet session before SESAME's idle timeout would |
Warnings exit 0; --strict makes them fail too. The command only reads config and builds the driver: it never signs anyone in, calls the identity provider or prints a URL, key or secret (a URL an error quotes back reads (a URL)), so it is safe in CI logs. Run it with the deploy's real environment: on the command line there is no request, so the cas driver's return URL comes from APP_URL, and an http:// (or missing) APP_URL fails the Driver line just as it would fail the first sign-in. A raw PHP app has no command; NativeSession checks HttpOnly, Secure and SameSite at run time and warns once per request, but it lets Strict through (see Raw PHP).