Skip to content
Menu

Sessions and lifetimes#

This page explains the three sessions a signed-in visitor holds at once, how long each lasts, and what ends each one.

Session lifetimes#

The gateway block sets how long a sign-in lasts and how long it may sit unused: session_seconds (default 28800 seconds, 300 to 604800) and session_idle_seconds (default 3600 seconds, 60 to 86400). Each app host renders them as mod_auth_openidc's OIDCSessionMaxDuration and OIDCSessionInactivityTimeout.

Three sessions, three clocks#

A signed-in visitor has up to three sessions at once. Each has its own lifetime and its own owner, and ending one does not end the others.

Layer Default lifetime What ends it What the visitor sees next
Entra (the identity provider) set by Entra and its Conditional Access policy, not by Drawbridge Entra's own policy, or the visitor signing out of Entra Entra may sign them in again without a prompt, or ask for credentials
Gateway (mod_auth_openidc, one per app host) 8 hours total, 1 hour idle (session_seconds, session_idle_seconds) either clock, the ?logout= link, drawbridge revoke (every host at once), or, with the default shm store, a restart or reload of the gateway (the cache lives in shared memory and starts empty) a protected path sends them to Entra; an api path answers 401
App (SESAME) 720 minutes total, 120 minutes idle (session.absolute_minutes, session.idle_minutes) either clock, or the app calling sesame_logout() the app's login route asks the gateway for a fresh assertion

How they fit together:

  • The assertion is used once, when the app signs the visitor in (it lives 60 seconds and SESAME's replay guard refuses a second use). After that the app's session runs on SESAME's clocks; a protected page reads SESAME's session, not the gateway.
  • So the app session can outlast the gateway session. With the defaults it can: the app allows 12 hours, the gateway 8. The gateway session ending does not sign anyone out of the app; the visitor finds out the next time the app sends them through its login route. To make the app never outlive the gateway sign-in, set the app's session.absolute_minutes to session_seconds / 60 or less (480 for the default).
  • Signing out through the ?logout= link ends the gateway session and asks Entra to end its own for that browser, not the app's. The app ends its own session first (sesame_logout()), then sends the browser to the link.
  • With the default shm store, a gateway restart signs everyone out of the gateway layer only; apps keep their sessions until their own clocks run out.

Where the sessions live#

By default the gateway keeps its sessions in Apache's shared memory, encrypted per host: one instance, nothing extra to run, and a restart or reload signs everyone in again. Set gateway.session_store: redis and gateway.redis_host (and redis_port, default 6379) to keep them in a Redis server you run. Sessions then survive a restart and a graceful reload (the rig's redis run proves the reload: RedisTest::testSessionSurvivesAGatewayReload; the last step of redis-rotation proves the restart: RedisRotationTest::testRestartTheSessionSurvivesAGatewayRecreatedFromItsEnvironment), and more than one gateway instance can serve the same hosts when every instance uses the same Redis and passphrase. That also gives DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS a session to decrypt during a passphrase change, so nobody is signed out by it, proven by rig/run.sh redis-rotation (RedisRotationTest): see Changing the passphrase. The password comes from DRAWBRIDGE_REDIS_PASSWORD, never from the config file. Redis holds the sessions; ending one person's sessions from outside is drawbridge revoke and its revocation list, which every instance must share (see Signing out).

Changing the passphrase#

With the default shm store a new DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE and a restart sign everyone in again: safe, but noisy. With gateway.session_store: redis you can change the castle password without locking out the people already inside the walls:

  1. Set DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS to the value in use now and DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE to a new one (32+ characters), then restart the gateway. Sessions sealed under the old value keep working; new sign-ins use the new one.
  2. Wait session_seconds (8 hours by default), so the sessions sealed under the old value run out on their own.
  3. Remove DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS and restart again. A session still sealed under the old value is sent to sign in (a redirect, not an error page); the rest carry on.

rig/run.sh redis-rotation (rig\run.ps1 redis-rotation on Windows) walks these steps against the pinned mod_auth_openidc on one gateway instance, with in-place reloads and a final restart of the gateway container: RedisRotationTest. With several instances, take each step on all of them before the next. rig/run.sh multi (rig\run.ps1 multi) proves it with two instances on one Redis (MultiInstanceRotationTest): once both hold the new and the old value, a session either one issues opens the app on the other, and once the old value is gone from both, both send a session sealed under it to sign in. It also shows the cost of a slow roll: while one instance holds only the old value, it cannot read a session another instance sealed under the new one, and sends that visitor to sign in again (a redirect, not an error page).

One session per app host#

Each host encrypts its sessions with a passphrase of its own, so a session cookie carried to another host opens nothing there. The session and state cookies are removed before the request is proxied, and no provider token (ID, access or refresh) ever reaches an app.