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 User 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.

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. One who signed in within it goes straight through.
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.

How long a session lasts

A session’s lifetimes are under Admin, Sessions in the admin console, and apply to every client:

Setting	Default
User session - idle timeout in seconds	7200 (2 hours)
User session - max lifetime in seconds	86400 (24 hours)

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

Check	Measured from	Set by
Idle timeout	The session’s last activity	User session - idle timeout in seconds
Maximum lifetime	When the session started, so activity never extends it	User session - max 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, and its offline refresh tokens keep working. A background job removes idle and expired sessions every 12 hours.

What keeps a session alive

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

a sign-in to any client completes through it, a silent request included;
a client refreshes with a normal refresh token from it.

Neither moves its maximum lifetime.

Single sign-on

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 it had one that’s no longer valid, and the user’s other sessions from the same device, which means the same browser User-Agent and the same IP address. Nothing those sessions handed out is revoked, though their normal refresh tokens stop working with them. 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.

Closing the browser

Closing the browser doesn’t end a session with the auth server. The cookie lasts as long as the session does, so 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.

The admin console does the opposite on purpose. Its own cookie lasts only until the browser closes, so reopening the browser asks an administrator to sign in to it again, even while the auth server still has their session. An administrator’s browser reaches every part of the deployment, so one more sign-in is worth it to keep a lost or forgotten machine from still holding that access. Some browsers restore what was open after a crash or an update, and that can bring an admin console session back with it.

Next steps

Ending sessionsWhat ends a session, and what that revokes.

promptCheck for a session silently, or always ask for a password.

ACR and AMRHow strongly a session's user signed in.