What a session is here, and how it is tracked

Three different things in this service are called a session, and they are not variants of one another. Two more things look like sessions and are not. Getting this wrong is the single commonest source of confusion about /admin/sessions, /admin/metrics and the CAEP events — so this page is the definition, and every page and endpoint named below is a view of it rather than a separate model.

  What it is Where it lives When it ends
Browser sign-on session the cookie every browser protocol here shares a map in authn/authn.ts, in memory absolute expiry, or a sign-out
Kerberos TGT the ticket-granting ticket is the Kerberos session nowhere — a blob in somebody’s cache its own endtime, sealed in by the KDC
LDAP connection the Bind is a state of the connection (RFC 4511 §4.2) the socket Unbind, a re-Bind, or the socket closing
GNAP grant a delegated session between a client instance and the person who approved it (RFC 9635) GNAP’s grant store, per realm its client revokes it, an administrator does, or a sign-out of the person — or of the session it was approved on — ends it; it has no expiry of its own

Only the first is a record this service keeps. The LDAP one is the live socket itself — there is no session object beside it, and when the socket dies the session is gone with it. The Kerberos one this service does not hold at all: a TGT is a blob in somebody’s cache, and a KDC that kept a record of the tickets it had issued could not be replicated read-only. Almost everything below follows from that one difference.


1. The browser sign-on session

One session, shared by every browser protocol. OAuth 2.0 / OIDC, WS-Federation, SAML 2.0, SAML 1.1 and the admin console all read the same cookie, which is why signing in through one signs you in to all of them and why signing out of one signs you out of all of them. There is no per-protocol session anywhere in this service. The person it belongs to is a user, and the other party is an application. Directory.

In product mode over TLS the browser holds it as __Host-sts_session, or __Secure-sts_session where authn.cookieDomain is set, and every other cookie this service sets is prefixed the same way. An unprefixed one is ignored. See Security in product mode.

sts_session, Path=/, HttpOnly, SameSite=Lax, and Secure only when the port is TLS (global.https). That last one is conditional rather than always on for a reason worth knowing: a browser silently drops a Secure cookie that arrives over plain http, so setting it unconditionally would leave a plain-http deployment with a sign-in that appears to succeed and a session that is never there again — which looks exactly like a session that expired and points nowhere near the cookie.

SameSite=Lax and not None, deliberately: WS-Federation section 13.2.1 sends its sign-in request as a cross-site form POST, and None would be a change that needs its own argument.

sts_session is a bearer cookie: copied off a machine, it works anywhere. With authn.deviceBoundSessions on (per realm, off by default), this service speaks the relying-party side of the W3C WebAppSec Device Bound Session Credentials draft:

  1. The answer that sets sts_session carries Secure-Session-Registration: (ES256 RS256);path="/authn/dbsc/register";challenge="…".
  2. A browser that supports DBSC makes a key pair and posts a proof of it — a dbsc+jwt JWT with the public key in its header and the challenge as its jti, in Secure-Session-Response — to POST /authn/dbsc/register. The session is now bound to that key, and the answer is the session’s JSON instructions and a second cookie, sts_session_bound, that lives authn.deviceBoundCookieLifetimeS (ten minutes by default).
  3. From then on the session is honoured only beside a current sts_session_bound. When it runs out, the browser posts to POST /authn/dbsc/refresh with Sec-Secure-Session-Id; the answer is a 403 with a Secure-Session-Challenge, the browser signs it, and the cookie is renewed.

A refresh signed by any other key, or replaying a challenge already spent, ends the session as a sign-out does — CAEP session-revoked, Back-Channel Logout Tokens, and the session’s audit row. A request that presents sts_session without the bound cookie is simply not signed in; the session is not ended, because the browser that holds the key renews the cookie before it sends anything.

With several accounts in one browser on, each account binds on its own: a binding’s cookie is named sts_session_bound_<id> after its DBSC session, each account is honoured only beside its own, and a refresh that ends one account’s session leaves the others signed in.

A browser that does not support DBSC ignores the header and keeps an ordinary session. A browser that declines or fails registration sends Secure-Session-Skipped. That is recorded on the session, and /admin/sessions and the portal’s Overview say binding skipped with the reason. A header that is not a list of tokens is recorded and the session stays unbound.

authn.deviceBoundIncludeSite (off by default) sets scope.include_site and widens the bound cookie’s Domain to the registrable domain. Off, the cookie stays host-only. The debugger’s public host and a custom listener’s host under that domain are excluded. Realm paths are the same origin and need no site scope.

A passkey profile can require a bound session (deviceBoundRequired), off by default, and the save is refused while authn.deviceBoundSessions is off. Issuance to that application waits while registration is still pending (authn.deviceBoundIssuanceWaitS, 60 seconds, read at the issuance, not by a timer) and is refused when the browser skipped registration or the wait has elapsed. A session that was never offered registration is not refused. A browser that has not been offered the header keeps an ordinary session.

Federated device-bound sessions, where one origin’s key is reused at another, are not implemented. The draft’s well-known document does not yet describe one grammar.

/admin/sessions and the portal’s Overview say whether a session is bound. The challenges and the bound cookie are MACs under a secret every node shares, so nothing about them is stored and every node accepts what another minted; each challenge is spent once for the whole cluster.

What the record holds

Keyed by an opaque 24-byte id, which is also on the record — because everything that is handed a session gets the object and not the key, and without it the tokens issued on a session could not name the session they were issued on.

Field What it is
id the opaque identifier; what a token records, what the CAEP subject names
user { username, sub } — the name typed, and the urn: subject derived from it
authTime when the authentication happened, in seconds — OIDC’s auth_time
expires the absolute instant it stops being honoured, in milliseconds
amr / acr how they authenticated, and to what context class. Stated rather than omitted: a relying party that asked for a second factor has to be able to see that it did not get one
via which protocol the sign-in came through
oidcClients OIDC relying parties issued an authorization response on this session
wsfedRealms WS-Federation realms signed into, with the wreply each was sent to
saml2ServiceProviders SAML 2.0 service providers signed into, with their ACS URLs

via is the protocol it was created through and not the only one it serves. A session started at a SAML 2.0 sign-in and then used to answer an OIDC authorization request says SAML 2.0 for its whole life. What is riding on it is the three lists — which is what /admin/sessions shows in its Carries column.

Those three lists live on the session on purpose, rather than in maps of their own: that is exactly the lifetime they should have. When the session goes, so does the list, and nothing has to be swept. They are also what a sign-out has to fan out to, so seeing them in advance is the only way to know what a sign-out is about to do. SAML 1.1 has no such list because that profile has no Single Logout, and SPNEGO and federation add none because neither defines one.

Lifetime: an hour by default, absolute, not extended by use

Fixed when the session is created, from authn.sessionLifetimeS (3600 by default); changing it reaches the next session and leaves live ones as they were. In product mode a session also ends after 30 idle minutes (authn.sessionIdleTimeoutS: 1800 by default in product mode, and 0, meaning none, in development mode), whichever limit comes first. The idle timeout is checked whenever a session is read, so it applies to sessions that already exist, and a request to the admin console or the user portal counts as use of the sign-on session behind it.

How long a session may last, and why

Product mode ends a sign-on session one hour after it starts, and after 30 minutes without use, whichever comes first. NIST SP 800-63B-4 sets these limits for reauthentication:

Level Overall limit Inactivity limit
AAL1 SHOULD be no more than 30 days MAY apply, not required
AAL2 SHOULD be no more than 24 hours SHOULD be no more than 1 hour
AAL3 SHALL be no more than 12 hours SHOULD be no more than 15 minutes

Product mode requires a second factor at the sign-in screen, so its sessions are meant for AAL2. One hour and 30 minutes are well inside both limits. The shorter overall limit is deliberate: a stolen session is useful for at most an hour, and a person who is still working signs in again. A deployment that needs AAL3 sets authn.sessionIdleTimeoutS to 900.

These do not follow the two numbers:

Case What applies, and why
A management API, SCIM or SPIRE Server API client session Extended by authn.sessionLifetimeS on each call. No person is involved, and it exists only while the client calls
A refresh token (oauth2.refreshTokenTtlS, 24 hours) Ends with the session it came from. An offline_access refresh token outlives the session by design, up to its own lifetime
An access token (oauth2.accessTokenTtlS, one hour) Ends with the session at this service’s own endpoints. A resource server that checks only the signature accepts it until it expires
A SAML assertion or a Kerberos ticket Cannot be recalled and lasts its own lifetime. See What ending a session stops
A federated session Ends at the partner’s SessionNotOnOrAfter, if that is sooner

Reauthentication uses the sign-in itself: prompt=login, max_age, acr_values or SAML ForceAuthn adds an authentication to the same session.

An expiry ends the session properly, not lazily when something next looks the session up — somebody who closed their browser would never be looked up again, and the session would sit in the map, counted as live, for as long as the process ran. A sweep runs every 30 seconds, inside every trust realm, and an expiry writes the same session.end audit row and the same CAEP session-revoked any other ending writes. See CAEP events for what a receiver is told.

How one is created

Every one goes through a single funnel, which is why there is no protocol here that can start a session without being counted, audited and reported:

Activity via
A name typed at /authn/login, reached from an OAuth 2.0 / OIDC authorization request OAuth 2.0 / OIDC
The same screen reached from a WS-Federation wsignin1.0 WS-Federation
The same screen reached from a SAML 2.0 AuthnRequest SAML 2.0
The same screen reached from a SAML 1.1 inter-site transfer SAML 1.1
A Kerberos ticket spent at /authn/spnego — no screen Kerberos v5 (SPNEGO)
A wallet’s presentation of a credential this service issued — collected by the wait page at /authn/wallet/wait in the browser that started it, or answered to that page through the Digital Credentials API (/authn-api/wallet/{state}/dc-api) OpenID4VP (a wallet)
A self-issued ID Token (SIOPv2) from a wallet, signed by a key the person enrolled at /portal/self-issued — the sign-in screen’s Sign in with a self-issued ID, collected the same way SIOPv2 (a self-issued ID)
A federated assertion accepted at /federation/acs/{id} — the person authenticated somewhere else entirely Federation (SAML 2.0), and the same for the other federation protocols

No password is checked at any of them in development mode. The Kerberos one verifies the ticket against a real long-term key, and the wallet one verifies the presentation — the issuer’s signature and a fresh holder proof against the key the credential is bound to, whichever of the four formats it is in — an mso_mdoc only when this realm issued it — and signs in only the directory entry the credential was issued for, and only while this service has not disowned it — see what is not checked.

A re-authentication makes a new session rather than refreshing this one: prompt=login, SAML 2.0’s ForceAuthn or a stale session against a freshness demand, and a WS-Federation wfresh too old all end at the screen.

How one ends

Activity What it reaches
GET\|POST /oauth2/logout OpenID Connect RP-Initiated Logout
GET\|POST /wsfed?wa=wsignout1.0 WS-Federation 1.2 §13.2.4
GET\|POST /saml2/slo SAML 2.0 Single Logout
GET\|POST /logout the protocol-independent sign-out — everything, across every family
/admin/logout, /admin/sessions an operator ending somebody else’s
End every session in this realm on /admin/sessions (POST /admin-api/sessions/end-all) every sign-on session in the realm started before that moment, the administrator’s own included, each ended the next time it is read
the lifetime running out the sweep, or the next lookup

All of them go through one function, which is what stops four protocols’ words for one act from drifting apart. That function is also where the RFC 9700 §2.2.2 refresh-token revocation lives and where the session.end audit row is written, so a sign-out that revoked nothing and logged nothing is not reachable. Signing out has the rest.

In development mode, ending a session does not recall what it produced. Access tokens, ID Tokens, SAML assertions and Kerberos tickets issued on it stay valid — that is what /admin/tokens lists, and it is the state an OIDC client is in when its ID Token still verifies and the browser would be asked to sign in again. Refresh tokens issued on the session without offline_access are the exception, in every mode: a sign-out revokes them (OpenID Connect Back-Channel Logout section 2.7, oauth2.revokeRefreshOnLogout, on by default and settable per client). In product mode the access tokens are revoked as well; see What ending a session stops.

End every session in this realm is the exception to both: it records one instant, so its cost does not grow with the number of sessions, and it revokes no token. Use Revoke all on the Tokens page (POST /admin-api/tokens/revoke-all) as well.

One session per sign-in, several per person

A person may hold up to authn.maxSessionsPerSubject sessions at once (32 by default), and past that their oldest one ends. A sign-in ends that oldest session at once. After the cap is lowered, the session sweep catches the rest a slice of people at a time and finishes a pass in 64 runs. authn.maxSessions is the realm’s limit, where a new session is refused. Two browsers is two sessions. They are folded onto one person by an identity key — the normalisation that makes alice, alice@REALM and a token’s urn:uuid:<entryUUID> subject one identity (the older urn:sts:user:alice form is still read) — which is what /admin/users, /admin/logout and /admin/sessions all file rows under.

Per trust realm

The session store is per realm, so a session belongs to the realm it was created in and cannot be presented in another. Removing a realm drops its sessions with everything else it held.

The admin console is the one exception in the whole service: it reads the default realm’s session whichever realm’s console you are looking at, because the two console roles are groups in the default realm’s directory. See trust realms.

Nothing about it survives a restart

Sessions are held in memory in every persistence mode, deliberately, and so is everything this service mints. The signing key is regenerated on every start, so a token that outlived it would verify against nothing. See persistence for the three things that are written down.


What ending a session stops

In product mode, ending a session revokes its refresh tokens (except offline_access ones) and its access tokens, so introspection, UserInfo and this service’s own APIs refuse them at once. The record of each token is kept.

Some things cannot be recalled. A SAML assertion already held by a service provider stays valid until it expires, and a Kerberos ticket stays valid until its own end time, because neither is checked with this service when it is used. An ID Token is not revoked, since RP-Initiated Logout accepts one as id_token_hint after the session has ended.

2. The Kerberos ticket-granting ticket

A TGT is the Kerberos session; a service ticket is one use of it. That is not an analogy — it is why /admin/metrics counts TGTs and not service tickets.

This service holds no state for one, and neither would a real KDC: a KDC keeps no record of the tickets it has issued, which is exactly what lets one be replicated read-only. A ticket is valid because it decrypts and its endtime has not passed, and the service that accepts it never contacts the KDC. Short lifetimes are the whole of Kerberos’s revocation model.

Consequences worth stating:

  • its expiry is the endtime the KDC sealed into the ticket, and nothing here can move it or take it back;
  • ending one is not per-ticket. /admin/sessions and /logout stamp a sign-out instant on the principal, after which a TGS-REQ presenting a ticket authenticated before that instant is refused KDC_ERR_TGT_REVOKED (20) — a registered code whose text says what is meant and for which the specification defines no mechanism, so this is an invention using it. It reaches no service ticket already in a cache;
  • a fresh AS-REQ succeeds, because signing out is not being locked out, and does not lift the instant: its ticket is accepted while every ticket from before the sign-out, renewed or not, stays refused until the latest one could still be valid;
  • a Kerberos client never touches the browser session at all — unless the ticket is spent at /authn/spnego, which is a different act: that door mints a browser session from a ticket, and from then on there are two sessions.

The list of live TGTs on /admin/sessions comes from the issued register — this service’s record of what it minted — and not from any store the KDC keeps.


3. The LDAP connection

RFC 4511 §4.2 makes a Bind the authorization state of a connection, so in LDAP the connection is the session and closing it is the only sign-out the protocol has. It follows that:

  • it has no expiry at all — it lasts until the next Bind, an Unbind, or the socket closing. expiresAt: 0 in the API means no expiry, not the epoch;
  • a re-Bind on the same socket is a new session, and /admin/sessions dates it from that Bind rather than from the first one;
  • ending it closes the socket, which the client sees as its connection dropping mid-conversation. An unsolicited notice of disconnection (§4.4.1) would be the polite form, and the vendored node-ldapjs has no way to send one;
  • an anonymous bind is not somebody’s session and is not listed as one. /admin/ldap/service counts every connection.

It is gated: logout.ldapDisconnect off leaves directory connections alone, and they are shown as untouched rather than hidden.


4. The GNAP grant

A grant a person approved to a GNAP client instance is listed as a GNAP grant row (#432): RFC 9635 makes it the state between that client and that person, its end is already reported as CAEP session-revoked, and its access tokens are renewed through it. It has no expiry of its own. Revoking the row revokes every token the grant issued and finalizes it, as the client’s own revocation would. A global sign-out, a disabled account and a Revoke of the session it was approved on end it too; an ordinary sign-out of one application and a session expiring do not. See GNAP.


What is not a session

Five things are easy to mistake for one:

  • A token, an assertion, a ticket or an SVID. Those are things this service has handed out. They outlive every session here, several by design and one (a Kerberos service ticket) beyond recall entirely. They are /admin/tokens.
  • A pending authentication record. Between an authorization request arriving and a name being typed, this service holds what to do with the person afterwards — for ten minutes. Nobody is signed in yet.
  • A pending MFA step (five minutes) and a pending consent — the same shape, both halves of one ceremony, neither a session.
  • A half-finished SPNEGO exchange. Two minutes, keyed by door and remote address, and it can be spent only at the door that began it.
  • A row in the CAEP register. That is a record about a session, and it deliberately outlives one: the session store forgets a session the moment it is signed out, so a row saying revoked is the only remaining evidence that the session existed and was revoked. See below.

Where a session is visible

Six views, and they answer different questions. The first two are the ones people mix up.

/admin/sessions — what is live, right now

Every session this service is holding, across all four kinds, with who is signed in, the protocol it was started through, what it carries, when it expires and how that expiry is worked out — and a Revoke button on each row that goes through the same termination /logout performs.

GET /admin-api/sessions is the same list without a browser; POST /admin-api/sessions/revoke is the button. Below the list, an administrator holding Admin Write has End every session in this realm (POST /admin-api/sessions/end-all); see How one ends. Every row carries the two fields that write needs, and — for a browser session — the sessionId that GET /admin-api/tokens?session= takes.

The Unauthenticated tab is not every browser that has not signed in. It lists sessions somebody started with Continue without signing in (authn.unauthenticatedSessions, off by default). An arrival session — a browser that reached a front door and has not signed in — is not on this page. No protocol reads it as a sign-in, and this page draws no row for it and no button that would end it. Signing in moves it to Live sessions. Continuing without signing in, when that setting is on, is what puts a row on the Unauthenticated tab. An empty tab does not mean this service is holding no unsigned-in browser.

/admin/metrics — the count, both ways

That page counts sessions twice, and the two numbers disagree on purpose:

  • the sign-on sessions this service really holds — the map described above;
  • the sessions implied by what it has issued, which is a definition rather than a measurement: a subject has an artifact-derived session in a protocol family when that family has issued it at least one artifact that is still valid — unexpired, and unrevoked where revocation exists.

They differ in both directions and each direction is real. A client_credentials access token has no human and no browser behind it, so it is a session in the second sense and nothing at all in the first. A signed-in browser that has been issued nothing yet is a session in the first sense and nothing in the second. A Kerberos client is in the second only.

In ?format=json they are two members with two names: signOnSessions — held, active, and a row per session — and sessions, the derived count broken down by family. Reading one of them as the other is the mistake this paragraph exists to prevent.

The other four

  • /admin/users?user=… — one person: every session they hold, with the tokens issued on each of them, plus the tokens whose session has since ended and the tokens that never had one (sessions, tokensOnEndedSessions, tokensWithNoSession in the JSON). Those three buckets are the answer to “why is this token not under a session”, and the middle one is not an error: sessions expire and are swept, and the token outlives the sign-on it came from.
  • /admin/logout — one person, across all eleven families: what is still live and what cannot be ended, with the reason. It is /admin/sessions asked the other way round.
  • /admin/caep-sessions — what has been said about each session over Shared Signals, including sessions this service no longer holds.
  • The audit log — session.start and session.end, one row each. They are deliberately separate from the authentication row beside them: a Kerberos AS-REQ and a WS-Trust UsernameToken authenticate somebody and start no session at all, so a log that could not tell those apart could not answer when did this browser get its session.

What a receiver is told

If a Shared Signals stream is agreed, a session starting, being presented and ending each emit a CAEP event with nobody having asked — the only place in this service where an endpoint is not what starts the work. CAEP events is the whole of it: which activity fires each of the eight, what each carries, and the three gates an event passes on its way out.