Raw PHP#
This page shows how a framework-free PHP app boots SESAME, signs the user in, reads the user back, and signs the user out. Start with the boot example, then wire up your protected pages.
Boot the app#
<?php
declare(strict_types=1);
require __DIR__.'/vendor/autoload.php';
use Waynestate\Sesame\Config;
use Waynestate\Sesame\DriverFactory;
use Waynestate\Sesame\Identity;
use Waynestate\Sesame\Sesame;
use Waynestate\Sesame\Session\NativeSession;
use Waynestate\Sesame\UserResolver;
// 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();
$config = Config::fromArray([
'driver' => 'fake',
'environment' => 'local',
'fake' => [
'username' => 'jdoe',
'attributes' => ['cn' => ['John Doe']],
],
]);
$sesame = new Sesame(
DriverFactory::make($config),
new class implements UserResolver {
public function findOrImportUser(Identity $identity): mixed
{
return $identity->username;
}
},
new NativeSession(),
$config,
);
sesame($sesame);
// When the login has not completed, sends the redirect to the identity
// provider and stops the script. When a ticket completes it, sends the
// redirect to the driver's service URL and stops the script, so the ticket
// never stays in the address bar. When the user is already signed in and
// the request has no ticket, returns the user.
$user = sesame_login();
Which key to store#
Your findOrImportUser looks the person up in the app's own store, so key that store on the driver plus the identity provider's own stable identifier, never on an email or a display name, which can change or be shared between providers. For the cas driver that identifier is the username (the Access ID), so the key is $identity->driver plus $identity->username. Other drivers name their stable identifier differently: the oidc section keys on iss plus sub, or tid plus oid, never the username alone.
Session ownership#
The app owns the session: start it with session_start(), and let HELMET set the cookie flags. SESAME regenerates the session ID on login and stores the user and identity in it, but it never opens the session and never sets a cookie flag: the only session cookies it causes are the new ID at login and the expired one at logout, both with the app's own cookie params. sesame_login() and sesame_logout() stop the script after they send their redirect, so nothing after them runs in that request. A protected page reads the user with sesame_user():
$user = sesame_user();
Strict mode, on by default. Two PHP settings stop a client choosing its own session ID: session.use_strict_mode (without it PHP accepts any ID a client sends, so an attacker can plant one) and session.use_only_cookies (without it PHP takes the ID from the URL, where links and logs leak it). NativeSession turns both on with ini_set() whenever no session is active: when it is built before session_start(), and before every session start of its own. When your app already started the session with either one off, the first use in the request raises one E_USER_WARNING naming the setting and the fix, and the session keeps working. The fix is the ini_set() line in the example above, ini_set('session.use_strict_mode', '1') before session_start(), or HELMET's helmet_boot(); Squire's php.ini already sets both.
The cookie flags, checked the same way. SESAME never sets a cookie flag, but from 0.7.0 NativeSession looks at the ones your session started with. When the session cookie lacks HttpOnly, lacks Secure on an https request (HTTPS set, or X-Forwarded-Proto: https), or has a SameSite other than Lax, the first use in the request raises one E_USER_WARNING naming the missing flags and the fix, and the session keeps working. A Strict cookie gets its own sentence, because it looks safer and breaks every sign-in (see below). PHP's own defaults trip it (HttpOnly off and no SameSite), and so did Squire's kit php.ini before Squire 0.10.2 (it now sets session.cookie_samesite = Lax; run squire update). Where the host's php.ini decides, the fix is the session_set_cookie_params() line in the example above, before session_start(), or HELMET's helmet_boot(), which sets all three. The upgrading guide has the fix per case.
Pass checkSessionSettings: true to new NativeSession() for a hard stop (a LogicException on every call) instead of either warning, or false to leave the settings alone and stay quiet about both.
The session cookie (name and SameSite)#
SESAME never sets a cookie, so two choices belong to the session setup. In raw PHP HELMET makes both for you (SessionHardening::apply(), called by helmet_boot()); in Laravel they are settings in config/session.php:
- Name it with the
__Host-prefix (S4). The browser then accepts the cookie only if it isSecure, hasPath=/and has noDomain, so a sibling subdomain under*.apps.wayne.educannot overwrite it. HELMET names the cookie__Host-WSUSESSIDon HTTPS (it keeps a name your app chose). In Laravel, setSESSION_COOKIE=__Host-wsu-session,SESSION_SECURE_COOKIE=true,SESSION_PATH=/and leaveSESSION_DOMAINempty inconfig/session.php. - Keep it
SameSite=Lax, neverStrict(S41). The identity provider sends the browser back to your app with a cross-site top-levelGET, and aStrictcookie is not sent on that request: it would be missing, so the app would see no session on the return request and any login binding (S18) would fail for every user.Laxis what HELMET sets and what Laravel does by default.NativeSessionwarns about a missing,NoneorStrictvalue, and theStrictwarning says why sign-in fails. A cross-sitePOSTcarries noLaxcookie at all, which is the defense you want; that is why thesamldriver's ACS page parks the IdP's POST without a session and sends the browser back to the login URL with a 303, where theLaxcookie is sent again (S35; see The saml driver). - Leave the session ID length alone (S45). Do not set
session.sid_lengthorsession.sid_bits_per_character: PHP's default ID is 32 hexadecimal characters (128 bits), and on PHP 8.4 and later both settings are deprecated and raise notices. A low value weakens the ID. Neither SESAME nor HELMET sets or checks them.
On logout, both paths send Cache-Control: no-store and Clear-Site-Data: "cache", "storage" so a back button or a shared browser cannot show a signed-in page; "cookies" is left out on purpose, because it would clear every cookie on the host and sign the user out of every other app on wayne.edu, not just this one. Single logout is not supported, the identity provider cannot sign the user out of the app's other sessions, so SESAME rejects a truthy slo (or single_logout) config key at boot.
Logout#
Logout is POST-only, with a CSRF token. sesame_logout() runs only for a POST whose body carries the session's sesame_logout_token; a GET answers 405 (Allow: POST) and a POST without the right token answers 403, and both leave the session alone. So another site cannot sign the user out with an image, a link or a forged form. Put the token in the sign-out form:
<form method="post" action="/logout.php">
<input type="hidden" name="sesame_logout_token" value="<?= sesame_logout_token() ?>">
<button>Sign out</button>
</form>
// logout.php
sesame_logout('https://app.example.test/');
The token lives in the session, is made on first use and dies with the session at logout. Laravel apps use Laravel's own CSRF token instead: the POST /logout route is in the web middleware group, so a form needs @csrf.
Helper functions#
The raw-PHP path is a set of plain functions in the global namespace behind a sesame_ prefix, each guarded with function_exists so two copies of the file can never collide. The app owns the session: start it with session_start() before calling anything here, and let HELMET set the cookie flags.
| Function | What it does |
|---|---|
sesame(?Sesame $instance = null) |
Hold the one Sesame instance for this process: pass the instance to set it, pass nothing to read it. Throws LogicException when read before it is set. |
sesame_request() |
Build the PSR-7 request for the current request from the globals, using the nyholm/psr7 factories the library already requires. |
sesame_login(): mixed |
Run a login against the current request. Sends the 302 and stops the script when the driver answers with a redirect; returns the app's user, or null when the resolver refused the identity. A script's request (JSON Accept, or X-Requested-With: XMLHttpRequest) with no one signed in gets a 401 with {"signedIn":false} instead of the redirect. Throws ProviderUnavailable when the provider cannot be reached, and AuthenticationFailed when it refuses the sign-in. |
sesame_user(): mixed |
The app's user for the current session, or null when there is none. |
sesame_require_mfa(int $maxAgeSeconds = 28800): mixed |
Require that the signed-in user's MFA is still good. Returns the user when satisfied, throws MfaNotSatisfied otherwise. |
sesame_require_context(string $id): mixed |
Require that the signed-in identity has the given authentication context. Returns the user when it does, throws AuthContextNotSatisfied otherwise. |
sesame_logout_token(): string |
The logout CSRF token for this session, for the logout form. The token is hex, so it needs no escaping in HTML. |
sesame_logout(string $returnTo): void |
Log the user out, then send them on. Invalidates the app session, redirects to the identity provider's logout URL when the driver has one, otherwise to the safe return-to, and stops the script. |
Logging#
The facade takes an optional sixth constructor argument: a PSR-3 logger (Psr\Log\LoggerInterface). When you pass one, SESAME writes one record per authentication event through it:
| Event | Level | When |
|---|---|---|
sesame.login |
info |
A verified identity resolved to a user and the session was stored. |
sesame.login_failed |
warning |
The driver's login threw AuthenticationFailed. |
sesame.login_refused |
warning |
The resolver refused the identity and returned null. |
sesame.logout |
info |
The session was signed out (a logout, a timeout, or a deleted user). |
sesame.session_anomaly |
warning |
The session state looks wrong or tampered with: reason is missing_timestamps or bad_session_ref. |
Each record carries event, driver, username and at (the time in UTC) in its context, and sesame.logout adds reason (logout, idle_timeout, absolute_timeout, no_timestamps or user_gone). sesame.session_anomaly adds reason (missing_timestamps, a user stored without the session's timestamps, or bad_session_ref, a stored reference that is not the 16-character lowercase hex value login created) and carries session_ref when the stored value is still a valid 16-character lowercase hex string; when you see one, look at the session_ref and the user around it in the log to see what happened to the session. sesame.login and sesame.logout also carry session_ref: an opaque 16-character hex reference SESAME creates on every login (stored in the session under sesame.session_ref) that ties the login, timeouts and logout of one sign-in together in the log. It is not the session ID and never derived from it, and a value read back from the session that is not a 16-character lowercase hex string is ignored, so a tampered session cannot inject log text. The logger stays optional: without one, nothing is logged and nothing else changes.
SESAME never logs tickets, session IDs, tokens or failure messages: a failed login records only the event, the driver and the time. Usernames have every control character replaced with ? and are cut at 128 characters, so a username cannot forge an extra log line or flood the log. A logger that throws never changes what the facade returns or throws.
With the sign-in counter on, one more event can appear: sesame.metrics_failed (warning), when a count could not be written. It carries event, driver and at, plus reason when the cause is SESAME's own setup; the store's own error is never logged.
Metrics#
The facade takes an optional seventh constructor argument, a LoginMetrics. PrometheusLoginMetrics counts every finished sign-in as sesame_logins_total{driver, outcome} in a promphp store; on the store HELMET's request metrics use, it shows on HELMET's /metrics. Off by default. The setup, the labels and the queries are in Counting sign-ins.