Skip to content
SESAME
Menu

Troubleshooting#

Open sesame opens the door; this page is for when it does not. Each symptom below names the cause the sources give, the fix, and a check you can run. If your sign-in still fails after these, start at Quick start with the fake driver to prove the wiring, then come back with the real driver.

Sign-in fails#

The oidc driver fails to build: The oidc driver needs league/oauth2-client#

Cause. The oidc driver stands on league/oauth2-client, which SESAME suggests but does not require. Without it, building the driver fails with The oidc driver needs league/oauth2-client. Install it with: composer require league/oauth2-client.

Fix. Install the library:

composer require league/oauth2-client

Check. Build the driver again; the error is gone and the sign-in starts. The driver's behavior is covered by tests/OidcDriverTest.php.

The saml driver fails to build: The saml driver needs onelogin/php-saml#

Cause. The saml driver stands on onelogin/php-saml, which SESAME suggests but does not require, and it refuses php-saml older than 4.3.2 or xmlseclibs older than 3.1.5 (both had signature or encryption advisories).

Fix. Install or update the library:

composer require onelogin/php-saml
composer update onelogin/php-saml robrichards/xmlseclibs

Check. Build the driver again; the error is gone. The floor is covered by tests/SamlConfigTest.php.

A SAML sign-in fails with saml.handle or saml.in_response_to#

Cause. The finish could not find what the start and the ACS left behind. saml.handle: the parked response is gone (more than two minutes, used twice, or a cache the web servers do not share). saml.in_response_to: the session that started the sign-in is not the one finishing it (a different browser, a session cookie set to SameSite=Strict, a session started on the ACS page, or a sign-in older than ten minutes).

Fix. Use a cache store every web server shares (SESAME_SAML_CACHE_STORE), keep the session cookie SameSite=Lax, and never start the session on the ACS page (raw PHP) or put the ACS route in the web group (Laravel).

Check. A fresh sign-in from the app's login URL completes. The flow is covered by tests/SamlDriverTest.php and tests/Laravel/SamlRouteTest.php.

A cas login loops back to the CAS login page#

Cause. cas.renew is set to true against Academica. Academica does not issue a ticket for renew=true and sends the user back to the login page, so a renew login loops instead of signing in.

Fix. Leave cas.renew off (the default is false). Set it to true only when the app needs a fresh, direct login rather than an existing SSO session, and the CAS server issues tickets for it.

Check. Sign in with the default cas.renew; the ticket completes and the user lands on the service URL. tests/CasDriverTest.php covers the cas sign-in steps.

CAS validation redirects to the login page, or attributes are missing#

Cause. cas.protocol is 3.0 against Academica, which answers a CAS 3.0 /p3/serviceValidate call with an HTTP 302 to the login page. Protocol 2.0 is the default for that reason.

Fix. Keep cas.protocol at 2.0. Set it to 3.0 only when a CAS server releases attributes on /p3/serviceValidate.

Check. Validate a ticket with cas.protocol at 2.0; the identity comes back with its attributes. tests/CasDriverTest.php covers it.

A sign-in fails on a hung or slow CAS server, or a client that is set up wrong#

Cause. SESAME treats any non-200 answer (including a redirect) as a failed login, and a client exception (no route, a TLS failure, the timeout ran out) or a 5xx answer as ProviderUnavailable, a subclass of AuthenticationFailed, so a PSR-18 client that is set up wrong fails the sign-in and never signs anyone in. Guzzle has no total timeout by default, so a hung CAS server would hold the request open forever, and it follows up to five redirects by default, to any host or to plain http. An app that does not catch the exception shows a blank 500 while CAS is down; catch ProviderUnavailable and answer 503 (see The cas driver).

Fix. Hand SESAME a client with a timeout, redirects off for the validation call, and TLS verification on:

$http = new \GuzzleHttp\Client([
    'timeout' => 10,
    'connect_timeout' => 5,
    'allow_redirects' => false,
    'verify' => true,
]);

Check. Run the suite; the fail-closed behavior on a redirect and on a client exception is proven by tests (S42):

docker

docker run --rm -v "${PWD}:/app" -w /app php:8.3-cli vendor/bin/phpunit

local

vendor/bin/phpunit

A failed login shows the CAS failure code to the user#

Cause. An AuthenticationFailed message can carry the CAS failure code (for example INVALID_TICKET), which tells an attacker how the server refused the ticket.

Fix. Log the message for operators and show the user one generic line instead.

Check. Trigger a failed login with a bad ticket; the log carries the message and the page shows the generic line. tests/CasDriverTest.php covers the failure path.

The gateway driver refuses every assertion from an untrusted peer#

Cause. The request must come from a trusted proxy: the direct peer (REMOTE_ADDR) must match one of the configured CIDR ranges in gateway.trusted_proxies. A valid assertion from an untrusted peer is still rejected, and a plain identity header (Remote-User, X-Remote-User, or any spelling of them) is never read.

Fix. List the CIDR ranges (or single IPs) the gateway proxy sits behind in gateway.trusted_proxies, a non-empty array.

Check. Send a request through the gateway proxy; the assertion verifies and the user signs in. tests/GatewayDriverTest.php covers the trust checks.

The gateway driver throws InvalidConfig naming a key at boot#

Cause. With the gateway driver, DriverFactory::make() throws InvalidConfig naming the key when gateway.public_key, gateway.issuer or gateway.audience is null or empty, instead of passing an empty string into the driver.

Fix. Set the named key. All three are required for the gateway driver, along with a non-empty gateway.trusted_proxies.

Check. Boot the driver; it builds without InvalidConfig.

A truthy slo (or single_logout) config key is rejected at boot#

Cause. 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 with InvalidConfig at boot, a mistake to fail on early rather than at the first logout.

Fix. Remove the slo (or single_logout) key from the config.

Check. Boot the app; it starts, and a logout clears the app session and sends Cache-Control: no-store and Clear-Site-Data: "cache", "storage".

The fake driver refuses to boot in production#

Cause. The fake driver is for local development and tests only; it refuses to boot in production.

Fix. Use a real driver in production: cas for a Citadel app today, gateway once Drawbridge is live, or oidc or oauth2 for apps off Citadel. See Which driver for my app?.

Check. In the local environment the fake driver signs in; in production the configured driver does. tests/FakeDriverTest.php covers the refusal.

The log has SESAME: the session was started with session.use_strict_mode off#

Cause. The app started its session with session.use_strict_mode off (PHP then accepts any session ID a client sends, so an attacker can plant a known one) or session.use_only_cookies off (PHP takes the ID from the URL). PHP's own default leaves strict mode off, and so does a shared php.ini that nobody hardened. NativeSession turns both on itself whenever no session is active yet, but a session the app already started keeps the settings it started with, so SESAME raises one E_USER_WARNING per request and carries on. With checkSessionSettings: true it throws LogicException instead.

Fix. Add ini_set('session.use_strict_mode', '1'); before session_start(), or call helmet_boot() there (HELMET sets both, with the cookie flags), or set session.use_strict_mode = 1 in php.ini or the FPM pool. Squire's php.ini already does. Building new NativeSession() before session_start() also works, since it turns the settings on while no session is active.

Check. The warning stops. php -r "echo ini_get('session.use_strict_mode');" prints 1 for the CLI; for the web, the same ini_get() on a page. NativeSessionTest covers the settings, the warning and the hard stop.

Cause. From 0.7.0 NativeSession checks the flags the app's session cookie started with. Without HttpOnly a script on the page can read the cookie, without Secure it can travel over plain http, and without a Lax SameSite other sites can make the browser send it (a Strict one has its own entry below). PHP's own defaults leave HttpOnly off and SameSite empty, and Squire's kit php.ini left SameSite empty before Squire 0.10.2, so an app that never set them sees this warning once per request. Secure is named only on an https request (HTTPS set, or X-Forwarded-Proto: https). SESAME never sets the flags itself; with checkSessionSettings: true it throws LogicException instead of warning. The full text, with all three missing, is:

SESAME: the session cookie is sent without HttpOnly, Secure and SameSite, so it is easier to steal or misuse. Set them before session_start(): session_set_cookie_params(['httponly' => true, 'secure' => true, 'samesite' => 'Lax']); (or call helmet_boot()).

Fix. Pick the case that matches the app:

  • Squire kit 0.10.2 or later: run vendor/bin/squire update and commit the new .squire/php.ini, which sets session.cookie_samesite = Lax. Nothing else to do where the kit's php.ini is used (local parity and the portable image).
  • Laravel: you should not see this. The Laravel adapter uses Laravel's session, not NativeSession, and Laravel sets its own cookie from config/session.php. If you do see it, something in the app builds a NativeSession by hand.
  • Raw PHP on a host whose php.ini you do not control: call helmet_boot() before session_start() (HELMET sets all three), or add ini_set('session.cookie_httponly', '1');, ini_set('session.cookie_secure', '1'); and ini_set('session.cookie_samesite', 'Lax'); before session_start(). The session_set_cookie_params() line in the warning does the same.

Keep Lax, not Strict: a Strict cookie is not sent when the identity provider sends the browser back, so the sign-in fails. Lax keeps CAS, OIDC and SAML working, because the CAS ticket and the OIDC code come back on a top-level GET and the SAML driver finishes on a GET after parking its POST.

Check. The warning stops. php -r "var_export(session_get_cookie_params());" shows httponly true and samesite Lax for the CLI; for the web, the same call on a page. NativeSessionTest covers the flags, the warning and the hard stop.

The session ends too soon, or looks wrong#

A raw-PHP app signs people out after 24 quiet minutes#

Cause. PHP's default session.gc_maxlifetime is 1440 seconds (24 minutes), and PHP's garbage collector deletes session data older than that, so on the defaults a raw-PHP app signs people out after 24 quiet minutes, long before SESAME's 120-minute idle timeout. SESAME never starts the session, so it cannot change this for you.

Fix. Set session.gc_maxlifetime = 7200 (your session.idle_minutes times 60) in php.ini or the FPM pool, or call ini_set('session.gc_maxlifetime', '7200') before session_start(). Laravel apps set SESSION_LIFETIME (minutes) instead.

Check. The exact call the sources use, in the oidc raw-PHP example:

ini_set('session.gc_maxlifetime', '7200'); // at least SESAME's idle timeout; see Raw PHP

Then sit a signed-in session for more than 24 quiet minutes; it stays signed in until the idle timeout (120 minutes by default) drops it.

The log carries a sesame.session_anomaly warning#

Cause. The session state looks wrong or tampered with: reason is missing_timestamps (a user stored without the session's timestamps; the session is signed out right after, so the anomaly precedes the sesame.logout) or bad_session_ref (a stored sesame.session_ref that is not a 16-character lowercase hex string; the user stays signed in and the bad value is never echoed into the log). A session without a reference at all is not an anomaly.

Fix. 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, the opaque 16-character hex reference that ties the login, timeouts and logout of one sign-in together in the log.

Check. Grep the log for sesame.session_anomaly and follow the session_ref value across the events of that sign-in. tests/SesameEventsTest.php covers the events.

The log carries sesame.metrics_failed, or /metrics shows no sesame_logins_total#

Cause. The sign-in counter is on but could not write its count. With a reason in the context, SESAME's own setup is the cause: there is no store (HELMET's request metrics are off, or HELMET_METRICS_STORAGE is unset, and the app binds no Prometheus\Storage\Adapter), or promphp is not installed. Without a reason, the store itself failed (APCu missing, Redis down, the SQLite file not writable); its message is left out on purpose, because it can carry a Redis URL with its password. The sign-in itself went through either way.

Fix. Turn on HELMET's request metrics with a store (HELMET_METRICS_ENABLED=true, HELMET_METRICS_STORAGE=apcu, redis or sqlite), or bind your own Prometheus\Storage\Adapter. When HELMET's own request metrics are failing too, HELMET logs metrics_storage_unusable with the store's error and its /metrics shows helmet_metrics_storage_up 0.

Check. Sign in once and scrape /metrics with HELMET's token: sesame_logins_total{driver="...",outcome="success"} is there. tests/Laravel/LoginMetricsTest.php covers the wiring, HELMET's SQLite store included. See Counting sign-ins.

The session is missing on the return from the identity provider#

Cause. The session cookie is SameSite=Strict. The identity provider sends the browser back to the app with a cross-site top-level GET, and a Strict cookie 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 would fail for every user.

Fix. Keep the cookie SameSite=Lax, never Strict. In raw PHP HELMET makes both choices for you (SessionHardening::apply(), called by helmet_boot()); in Laravel the default is Lax, and the settings are SESSION_COOKIE=__Host-wsu-session, SESSION_SECURE_COOKIE=true, SESSION_PATH=/ with SESSION_DOMAIN empty in config/session.php.

Check. Sign in end to end; the return request carries the cookie and the login completes. A cross-site POST carries no Lax cookie at all, which is the defense you want. In raw PHP, NativeSession warns once per request with SESAME: the session cookie is SameSite=Strict, so the browser leaves it off the identity provider's return and every sign-in fails. In Laravel, php artisan sesame:check fails on SameSite=Strict and on the array session driver (which loses the session the same way), so a deploy job can catch both before users do.

A stale session is signed out on the spot#

Cause. Every signed-in session has two clocks: the idle timeout (default session.idle_minutes 120) and the absolute lifetime (default session.absolute_minutes 720). Both are checked on every user() call, so a stale session is signed out the first time anything asks who is signed in. A session made before the timeouts existed (a user, no timestamps) counts as expired.

Fix. This is the expected behavior, not a fault. If the limits are wrong for the app, set session.idle_minutes and session.absolute_minutes (env SESAME_SESSION_IDLE_MINUTES and SESAME_SESSION_ABSOLUTE_MINUTES in Laravel). See Session timeouts.

Check. Read the user with sesame_user() after the quiet time; the session is gone and the next sesame_login() starts fresh.

A visitor back from a break gets a blank 500: No session is active#

Cause. SESAME 0.7.0 on the native PHP session (raw PHP, or the Wayne Auth bridge). A session past the 2 hour idle timeout or the 12 hour absolute limit was signed out and the PHP session closed; the same request then sent the visitor to CAS, and storing the pending sign-in threw LogicException: No session is active. Start one before using NativeSession. An XHR save at that moment failed the same way.

Fix. Upgrade to 0.7.1 or later: the sign-out starts a fresh session under a new ID, so the visitor goes through CAS again, and a script's request gets a 401 with {"signedIn":false}. Until you can upgrade, catch \LogicException around the sign-in call and, when session_status() !== PHP_SESSION_ACTIVE, redirect to the app's own root: the next request starts clean and goes to CAS. It cannot loop, because the old cookie was expired and a reused ID is retired.

Check. tests/WayneAuthLegacyAppTest.php ages a real session file past each limit and expects the CAS redirect, then the sign-in, then a 401 for an XHR.

Config and playbook#

Boot fails: Missing required setting SESAME_....#

Cause. The setting is not in the environment and the private waynestate/playbook package, which supplies the university's values when the environment is empty, is not installed. A missing routed setting fails with Missing required setting SESAME_.... Set it in the environment, or install waynestate/playbook (see the README).

Fix. Set the variable in the environment, as with every other setting, or install the playbook:

{
    "repositories": [
        { "type": "vcs", "url": "https://git.wayne.edu/enterprise-apps/playbook.git" }
    ]
}
composer require waynestate/playbook

The environment always wins: a set variable beats the playbook, and an empty one counts as unset.

Check. Boot the app with the environment empty; it reads the four shared values from the playbook and starts. tests/SettingTest.php covers the resolution order.

Fetching the playbook answers 404#

Cause. Playbook is private on git.wayne.edu.

Fix. Ask the Enterprise Applications team for read access. The token is your own: read_api for curl, read_repository for clone and Composer.

Check. Refetch; the file arrives as plain KEY=value lines. Copy the ones you need into your app's .env (or your Citadel environment); SESAME does not read .env.playbook itself.

linux

curl --fail -H "PRIVATE-TOKEN: $GITLAB_TOKEN" "https://git.wayne.edu/api/v4/projects/enterprise-apps%2Fplaybook/repository/files/playbook.env/raw?ref=main" -o .env.playbook

windows

Invoke-WebRequest -Headers @{ 'PRIVATE-TOKEN' = $env:GITLAB_TOKEN } -Uri "https://git.wayne.edu/api/v4/projects/enterprise-apps%2Fplaybook/repository/files/playbook.env/raw?ref=main" -OutFile .env.playbook

After updating to 0.8, a class in Waynestate\Sesame\WayneCas is not found, or the wayne.cas middleware is unknown#

Cause. SESAME 0.8.0 removed the wayne-cas shim: the Waynestate\Sesame\WayneCas namespace and the wayne.cas middleware alias are gone.

Fix. Take the steps in Leaving the shim while the app is still on 0.7.x, or let Booster's cas-to-sesame hop do it.

Check. Sign in through the pre-production host and check the session timeout, the Access ID attribute and Duo there.

A wayne-cas app signs in, then every page fails with InvalidConfig naming a static find method#

Cause. SESAME 0.6.1 and earlier: the wayne-cas shim's refreshUser() looked for a declared static find method on auth.providers.users.model. An Eloquent model reaches find() through its query builder instead of declaring it, so the check failed on every signed-in request.

Fix. composer update waynestate/sesame to 0.6.2 or later: from 0.6.2 the shim looked an Eloquent model up through query()->find(). On 0.8, point user_resolver at \Waynestate\Sesame\Laravel\ModelUserResolver::class.

Check. Sign in, open a second page, and the log has no InvalidConfig. tests/Laravel/ModelUserResolverTest.php covers an Eloquent model and a plain class with a static find.

Build, CI and docs#

composer ci fails#

Cause. composer ci runs the whole gate: validate through tests, Pint and PHPStan, plus the agent-ready and docs checks and the locked-dependency audit. CI on git.wayne.edu runs the same command: seven checks (manifest, tests, Pint, PHPStan, the agent-ready pages, the docs build, audit).

Fix. Read the failing step; static analysis is PHPStan at level 8 from Pinstripe's strict preset, where a call to a deprecated method fails the build.

Check. Rerun the gate locally:

docker

docker run --rm -v "${PWD}:/app" -v stack-composer-cache:/tmp/cache -w /app composer:2 composer ci

local

composer ci

composer docs:check fails in CI#

Cause. The built docs site is stale, or the generated environment reference has drifted from the source.

Fix. Rebuild the docs site:

composer docs

Check. composer docs:check passes again, and the rebuilt pages under site/docs/ match what you committed.

No PHP on the machine, and the suite will not run#

Cause. The developer machine has no PHP, so vendor/bin/phpunit cannot start.

Fix. Docker runs the suite:

docker run --rm -v "${PWD}:/app" -v stack-composer-cache:/tmp/cache -w /app composer:2 composer install --no-interaction
docker run --rm -v "${PWD}:/app" -w /app php:8.3-cli vendor/bin/phpunit
docker run --rm -v "${PWD}:/app" -w /app php:8.4-cli vendor/bin/phpunit
docker run --rm -v "${PWD}:/app" -w /app php:8.5-cli vendor/bin/phpunit

Check. All three PHP versions pass. How to build, test and release this project is in MAINTAINING.md.