Ending sessions
This page helps you end a user’s session, and know what that cuts off.
A session ends in one of four ways: someone ends it from the admin console or the API, the user signs out, the user’s credentials change, or a different user signs in on the same browser. And when an app redeems an authorization code twice, the auth server ends the session the code came from if it had refresh tokens to revoke: see auth_code_reuse_detected in the audit log. Each is a security action rather than housekeeping, so each one decides what happens to the tokens the session handed out. A session that merely expires is different: it revokes nothing.
End a session
Section titled “End a session”-
Find the session. A user sees their own under Account, Sessions in the admin console. An administrator sees a user’s on the user’s Sessions tab, and every session signed in to a client on the client’s Sessions tab.
-
Choose End session beside it, and confirm.
The same goes through the API: an administrator calls
DELETE /api/v1/admin/user-sessions/{id}, and a user callsDELETE /api/v1/account/sessions/{id}for one of their own. -
The browser that held the session has to sign in again, and the tokens the session handed out stop working, as below.
What ending a session revokes
Section titled “What ending a session revokes”| What | What happens |
|---|---|
| The session | It’s deleted. The browser that held it has to sign in again |
| Refresh tokens from it | Revoked, offline ones included |
| Authorization codes from it | Revoked, so a code that was issued but not redeemed yet can’t be exchanged |
| The user’s other sessions | Untouched |
That’s what sets ending a session apart from one expiring. An offline refresh token is meant to outlive the session it came from, so it keeps working when that session times out. Ending the session revokes it on purpose.
Each one leaves two entries in the audit log: terminated_user_session, which records what was revoked, and deleted_user_session, the record that the session is gone. Count terminated_user_session to know how many sessions were ended.
Telling your apps
Section titled “Telling your apps”Ending a session also tells the apps the session was signed in to. Each one with a back-channel logout URI is sent a logout token there: a signed statement naming the user (sub) and the session (sid), so the app can end its own session for that user. That happens whenever a session that was still valid ends:
- someone ends it from the admin console or the API;
- the user signs out. With an
id_token_hint, only the app that signed the user out is told, since only its part of the session ended; - a different user signs in on the browser;
- a sign-in ends it: the user’s own session the browser had, their other sessions from the same browser, or the ones over the cap;
- an app redeems an authorization code from it twice;
- the user changes their own password, which ends their other sessions.
A session that has expired tells nobody, whatever removes it. Disabling or deleting a user, a password reset, an administrator setting the password and the recover command tell every app that knew the user instead, expired sessions or not: see Credential changes.
Back-channel logout gives the request, the token, its retries, what your app answers, and what happens when a delivery is lost.
A session that has expired
Section titled “A session that has expired”You can’t end a session that has passed its idle timeout or maximum lifetime, because it’s already gone. The session lists leave it out, and both DELETE calls answer it with 404, just as they would a session that was never there. Nothing is revoked and nothing is written to the audit log. The background job deletes the row later, and that revokes nothing either.
Its offline refresh tokens keep working, as they’re meant to. To cut them, withdraw the user’s consent to the client: on the user’s Consents tab in the admin console, with DELETE /api/v1/admin/user-consents/{id}, or by the user under Account, Consents. Or change the user’s credentials, as below.
A sign-in under way
Section titled “A sign-in under way”A sign-in can’t slip past an ended session. If someone was partway through signing in to an app on the strength of the session you ended, the sign-in goes back to the password step rather than quietly starting a new session. That holds on the consent screen too: just before it issues the code, the auth server checks the session again, so a sign-in left waiting there goes back to the password step as well, and so does one whose session timed out while the screen was open.
A silent request can’t show a page, so it gets login_required instead, and your app decides when to send the user to sign in. Two things withhold that error: a client that registered itself is never sent one, and neither is a redirect URI no longer registered on the client. A silent request that doesn’t come back is then the signal. See The app gets no error back.
Signing out
Section titled “Signing out”Your app signs a user out by sending them to /auth/logout. Signing out revokes nothing: no refresh token and no authorization code is revoked. What it ends depends on what the request carries:
- With an
id_token_hint, the auth server removes your app from the session the hint names. The session itself ends only when no other client is using it, so the user stays signed in to the others. - Without one, once the user confirms on the sign-out page, the whole session ends.
Either way the browser’s cookie is cleared, so its next sign-in starts from the password. A normal refresh token stops working once the session behind it has ended. Offline refresh tokens aren’t tied to a session and keep working.
A sign-out’s audit log entries are on Logout.
Credential changes
Section titled “Credential changes”When a user’s credentials change, their sessions and refresh tokens stop being usable:
| Action | What happens | reason |
|---|---|---|
| The user resets a forgotten password | Every session of theirs is ended and every refresh token revoked | password_reset |
| The user changes their own password | The same, except the session they’re changing it from | password_change |
| An administrator sets the user’s password | Every session of theirs is ended and every refresh token revoked | admin_password_set |
| An administrator disables the user | The same. Enabling them again doesn’t bring the sessions back | account_disabled |
The auth server’s recover command recovers the user, whatever it was asked to do |
Every session of theirs is ended and every refresh token revoked | recovery_command |
That covers every grant, offline refresh tokens whose session has already expired and tokens from the password grant included, and an authorization code that was issued but not redeemed yet can’t be exchanged any more. Each change leaves a revoked_user_auth_state entry in the audit log, with the reason above and the sessions and refresh tokens it ended.
Telling the apps that knew the user
Section titled “Telling the apps that knew the user”A password reset, an administrator setting the password and disabling the user end every session the user has, and so do deleting the user and recovering them with the recover command. Each of these tells every app that knew the user: each app with a back-channel logout URI that was on any of the user’s sessions, expired ones included, or holds one of the user’s refresh tokens that’s still unrevoked and unexpired. It’s sent one logout token naming the user (sub) and no session, which asks it to end every session it has for that user.
An app that requires the session identifier is sent a token naming the session instead, one for each of the user’s sessions it was on that was still valid. It’s told nothing for a refresh token alone.
A user changing their own password ends only their other sessions, so only those tell their apps: each app on each of them that was still valid gets a token naming the user and that session. The apps on the session they changed it from, and the apps holding only a refresh token, are told nothing.
A user changing their own password normally stays signed in to the app they did it from. If that app refreshes at the same moment as the change, it may be asked to sign in again.
These end nothing:
- Changing an email address. The change already asks for the current password, so signing other devices out would protect nothing that person couldn’t do again. Tokens issued before it carry the old
emailclaim until they’re refreshed or expire. - Setting up or removing two-factor authentication. Each session is checked again for a second factor before it’s used for a level above
urn:goiabada:level1, and removing it also lowers each session to what a password alone reaches. See ACR and AMR. For a lost or stolen device, end the user’s sessions as well: see A user who lost their authenticator.
A different user signs in on the same browser
Section titled “A different user signs in on the same browser”A shared or borrowed browser can reach the sign-in page still holding someone else’s session. That happens whenever a client sends prompt=login or an id_token_hint naming another user, and whenever the session there has stopped being valid.
When the person who signs in is a different user, the browser has changed hands:
| What | What happens |
|---|---|
| The previous user’s session | Ended, as if someone had ended it: deleted, with its refresh tokens and unredeemed authorization codes revoked |
| The new user | Never gets the session that was there |
| The previous user’s other devices | Untouched. Only what this browser’s session handed out is revoked |
| The apps on the previous user’s session | Told that it ended, as in Telling your apps, when it was still valid |
The grants that session held were reachable from this browser, and the browser is now someone else’s. An offline refresh token from it would otherwise keep working in the background indefinitely.
Nothing carries over. If the client asks for a one-time code, the new user is asked for one, however the previous user signed in, and the acr and amr in their tokens describe only what they did.
Each handover leaves a cross_user_session_replaced entry in the audit log, naming both users and the session that was ended, beside the terminated_user_session and deleted_user_session entries for that session and the started_new_user_session entry for the new one, when one starts. It’s the entry that tells a browser changing hands apart from an administrator ending a session.
Access tokens already issued
Section titled “Access tokens already issued”An access token is a signed JWT, and nothing on this page changes a token already issued. What happens to it depends on who checks it:
- The auth server’s own endpoints,
/userinfoand the Admin and Account APIs, refuse an access token on the very next request once its session has ended or expired, its user was disabled or changed their credentials, or its grant was revoked. Ending a session from the admin console or the API revokes the grants it handed out, offline ones included, so this reaches an offline grant’s access tokens too. Withdrawing the user’s consent to the client and making the client public revoke the grant as well, and disabling the client refuses its tokens while it stays disabled. Signing out revokes nothing. - An API that introspects the token, asking the introspection endpoint, gets
{"active": false}from the same moment, for every one of these. - An API checking the signature alone accepts the token until it expires.
That’s inherent to signed tokens, and it’s the main reason to keep access tokens short-lived: the token lifetime, 5 minutes in a new install, is the longest a token can outlive any of this at an API that doesn’t introspect.