Skip to content

Sessions

This page helps you understand when users are asked to sign in, and when they go straight through.

When a user signs in, the auth server starts a session for their browser and names it in a cookie. The next time any client sends that browser to sign in, the session is enough: the user isn’t asked for their password again. That’s single sign-on. The session remembers who signed in, when, and how strongly, as its ACR level.

Each user can see their sessions under Account, Sessions in the admin console, and an administrator sees them on the user’s Sessions tab and on a client’s Sessions tab.

A session can be hours old. When an operation needs the user to have signed in recently, such as changing their payment details, ask for it.

  1. Add max_age to the authorization request, in seconds. This asks for a sign-in within the last five minutes:

    GET /auth/authorize?client_id=my-app&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&response_type=code&scope=openid&max_age=300&code_challenge=...&code_challenge_method=S256&state=... HTTP/1.1
    Host: auth.example.com

    A user who signed in longer ago than that enters their password again, and gets a new session in place of the old one: the user’s other apps on it stop refreshing, and are told it ended. One who signed in within it goes straight through. prompt=login asks for the password too, but keeps the session.

  2. Check auth_time in the ID token before you allow the operation. It’s when the user last entered a credential, so it’s no older than max_age allows:

    {
    "sub": "c5b9b6a2-4b39-4b8e-9a8e-6f7f2b3a1d10",
    "auth_time": 1760000000,
    "acr": "urn:goiabada:level1"
    }

To ask for a password every time, whatever the session, send prompt=login instead. With both, prompt=login wins.

A session’s lifetimes, how many sessions one user can hold, and whether users stay signed in after closing the browser are under Admin, Sessions in the admin console, and apply to every client:

Setting Default
Idle timeout, in seconds 7200 (2 hours)
Maximum lifetime, in seconds 86400 (24 hours)
Maximum sessions per user 20 (0 means no limit)
Keep users signed in after the browser closes Let each user choose

A session can be used only while all of these hold:

Check Measured from Set by
Idle timeout The session’s last activity Idle timeout, in seconds
Maximum lifetime When the session started, so activity never extends it Maximum lifetime, in seconds
max_age When the user last entered a credential, which is auth_time. When the user’s two-factor authentication is removed, it’s when they entered the password, as ACR and AMR explains The authorization request, when it has one

Each bound includes its last second: a session idle for exactly the idle timeout still counts, and so does a sign-in exactly max_age seconds ago, as OpenID Connect Core 1.0 section 3.1.2.1 describes. The idle timeout can’t be longer than the maximum lifetime.

A session that fails one of them isn’t used, and the user signs in again. It isn’t ended either: a session that has merely expired revokes nothing, its offline refresh tokens keep working, and no app is sent a logout token for it. A background job removes idle and expired sessions every 12 hours.

A session’s last activity moves forward whenever it’s used:

Neither moves its maximum lifetime.

When a browser arrives with a session that’s valid and belongs to the user signing in, the user isn’t asked for their password, and goes on with the session’s ACR level. They’re asked for a one-time code only when the client needs a higher level than the session reached, which is a step-up. A request whose id_token_hint names someone else, or with prompt=login, asks for a password whatever the session, and for a one-time code whenever the level needs one.

A user who has been disabled can’t use a session. Disabling them ends their sessions, so their next sign-in starts from the password, which answers “Your user account is disabled.” once the right password is entered, and a silent request gets login_required. A session of a disabled user that’s still found ends the request with access_denied and “The user account is disabled.”

Once the user has signed in, the auth server checks them again before it records anything:

  • A disabled user is refused with access_denied, and no session is written.
  • A user whose credentials changed while they were signing in, because their password was changed or reset, signs in again from the password, with nothing written.

Then it records the sign-in in a session:

  • The browser’s session is valid and the user’s own. It’s reused: its last activity moves forward, and its ACR level goes up when this sign-in reached a higher one. Reusing it never lowers its level. When the user entered a credential in this sign-in, its auth_time is updated to then. A sign-in that asked for the password again, such as one with prompt=login, replaces the session’s level and methods with its own, as described in A session that’s already there.
  • Otherwise, a new session starts. It replaces the user’s own session the browser had, if that one had expired or was older than the request’s max_age, and the user’s other sessions from the same browser, recognized by its device cookie. Their sessions in other browsers stay, unless the user would then hold more than the cap. Nothing those sessions handed out is revoked, though their normal refresh tokens stop working with them, and the apps on each one still within its idle timeout and maximum lifetime are told it ended. A session the browser had for another user is ended, as Ending sessions describes.

A new session needs a password entered in this sign-in. A sign-in that was relying on a session that ended partway through goes back to the password step rather than starting one from nothing.

The cookie’s identifier changes whenever a session starts and whenever its ACR level goes up, so an identifier copied before the sign-in names nothing afterwards.

A browser can have up to five sign-ins in progress at once, each started by its own authorization request, and each finishes on its own. A user signing in to two clients from two tabs finishes both. A link or redirect to /auth/authorize from another site starts a sign-in of its own, or gets its own error, and leaves the others alone.

When a sixth starts, the one that moved least recently is pushed out. A sign-in moves whenever the user goes on to its next step, so one the user is working through outlives the tabs they abandoned. The next page of a pushed-out sign-in says “This request is no longer active”, and the user starts again from your app. Signing out ends every sign-in in progress in that browser. When a password or one-time code is accepted in a browser, any sign-in in progress there for a different user stops, so one abandoned after its password was entered doesn’t carry on into the next person’s session.

A page that keeps sending a window it opened to sign in can push the user’s sign-in out by starting five of its own. That costs the user a retry and nothing more: nothing is issued for a pushed-out sign-in.

The auth server gives each browser a cookie of its own, __Host-authserver_device, or authserver_device when its base URL is plain http, so a sign-in can tell which of the user’s sessions came from that browser. It holds a random identifier that only the auth server reads, and it’s used for nothing else: a first-party cookie the auth server needs to work, not a tracker.

  • It’s written when a sign-in starts a new session, for the maximum lifetime, 24 hours by default: as long as that session can last. The longest it asks for is 400 days, the most a browser keeps a cookie. A browser that already has one keeps its identifier.
  • Signing out doesn’t clear it, and neither does an administrator ending a session: it names the browser, not a session.
  • A session stores the identifier’s SHA-256, never the identifier, and neither is shown in the admin console, returned by an API or logged.
  • A browser whose cookies were cleared counts as a new browser. Its next sign-in leaves the old session alone, to expire or be ended by the cap.

The browser and IP address shown on a sessions page play no part: a second browser profile, or a colleague’s machine behind the same router, keeps its own session.

One person rarely needs more than a handful of sessions: a phone, a laptop, a browser at work. Maximum sessions per user caps them, from 0 to 1000.

When a sign-in starts a new session and leaves the user over the cap, the auth server ends as many of their other sessions as it takes, never the new one:

  1. Expired sessions first, those past their idle timeout or maximum lifetime that the background job hasn’t removed yet.
  2. Then the least recently used.

Ending a session this way revokes nothing it handed out, though its normal refresh tokens stop working with it. The apps on it are told it ended when it was still valid. The audit log records it with the reason session_cap.

The cap catches pile-ups, such as a script that signs in with a fresh browser every time. Set 1 for one session per user, or 0 for no limit. Lowering it ends nothing at once: a user’s sessions over the new cap end at their next sign-in.

Closing the browser doesn’t end a session with the auth server: the session still ends at its idle timeout or maximum lifetime. What closing it decides is whether the browser still has the auth server’s cookie when it opens again, and that’s the Keep users signed in after the browser closes setting:

Setting The password page The auth server’s cookie
Let each user choose Shows a Keep me signed in box, unticked Ticked, it lasts as long as the session, up to 400 days. Unticked, it ends when the browser closes.
Always Shows no box Lasts as long as the session, up to 400 days. Whether that needs cookie consent is yours to decide: see Personal data.
Never Shows no box Ends when the browser closes

When the cookie lasts, reopening the browser within the idle timeout signs the user straight back in, and a restarted machine or a laptop shut for lunch costs nobody a password. When it ends with the browser, the user enters their password again. The session they left behind stays on the server until it expires, or until their next sign-in from that browser ends it, as How the auth server recognizes a browser describes. On a shared or public computer, leaving the box unticked is what keeps the next person from walking into the account.

The answer belongs to the browser’s session:

  • A single sign-on keeps it. A sign-in that goes straight through asks nothing.
  • Each password entry replaces it. Whenever the password page shows again, for prompt=login, max_age, an expired session or another user, the box asks again, unticked.
  • A password entered with no box leaves no answer, under Always or Never, and a browser with no answer counts as unticked under Let each user choose.

A changed setting reaches a browser the next time the auth server writes its cookie, at its next sign-in at the latest. While a browser isn’t signed in yet, the cookie of its sign-in in progress lasts 30 minutes whatever the setting, so restarting the browser partway through loses nothing. Some browsers restore what was open, cookies included, after a crash or an update, or when they’re set to continue where you left off, and that brings back a cookie meant to end with the browser.

The admin console’s own cookie always ends when the browser closes. But the console signs in through the auth server, without prompt=login or max_age, so after a restart an administrator whose auth server cookie outlived the browser is signed straight back in without a password.