Single sign-out

Cross tab and browser sign out and server side session invalidation

Single sign-out

Single sign-out is a feature that allows users to sign out of the application in one tab/browser and have the same user session invalidated in other tabs/browsers.

This is useful for compliance purposes, as it ensures that if a user signs out of the application, the session will be invalidated across all devices.

Sessions without a refresh token live in the browser session, which the server can't revoke. For them, single sign-out only works in the same browser and with the same session, and the session data stays in the browser until it expires.

How it works

Single sign-out groups the persistent sessions of one user per provider by the sub claim of the access token, or of the ID token when the access token has none. singleSignOutIdField only decides whether a session joins a group: a session joins when the configured claim is present in the access or ID token. A refreshable session without a group, for example because no sub is available, logs a warning at login and its single sign-out only covers its own session.

Each group has a random revocation generation in the oidc storage under an sso-generation: key, and each persistent session stores the generation that was current when it was created.

When a session of the group is cleared on the server, by logout or because it expired or could not be refreshed:

  1. The server replaces the group's generation in the oidc storage
  2. The server removes the session and its cookie
  3. The server notifies event stream clients of the group that are connected to the same server process
  4. Notified clients fetch their session, see that they are signed out and update their state

Every server-side read of a persistent session, for example in getUserSession, getAccessToken, refreshUserSession and the session API, compares the stored generation with the current one. A session with an older generation is removed and rejected, so other browsers, offline clients and clients connected to other server instances are signed out on their next request. A token refresh that is still running when the group signs out does not restore the session. A new login receives the new generation.

The event stream only speeds up the client update; it doesn't revoke anything. If the generation can't be read from storage, requests with sessions of the group fail instead of continuing with an unchecked session.

To sign out sessions across several server instances, all instances need the same oidc storage, for example a shared Redis instance. With storage local to each instance, a logout only revokes sessions stored on the instance that handled it.

Persistent sessions stored without a generation, for example by an earlier module version, are rejected and need a new login.

Sessions without a refresh token keep using the browser session. If they store tokens, for example for exposeAccessToken, a sign-out of the group removes those stored tokens, but the browser session stays valid until it expires.

Limitations

  • Storage has no conditional writes, so two first logins of the same user at the same moment can invalidate one another. The rejected session fails closed and the user signs in again.
  • If the generation can't be written, logout fails and the session stays signed in, so the group is never left signed in while the session reports being signed out.
  • The GET logout routes only log out requests that the browser marks with Sec-Fetch-Site: same-origin or none, which covers useOidcAuth().logout(), links in the application, the /auth/logout redirect and typed URLs. Requests marked cross-site or same-site, such as a link on another site or on a sibling subdomain, keep the session and redirect to the application root. Browsers that don't send Fetch Metadata headers are not protected, so in them a cross-site request still signs out the whole group of the session.

Event stream authorization

beta.12+

The /api/_auth/sso event stream accepts only a valid sealed session cookie for a configured provider whose current session has singleSignOut: true. With expiration checks enabled, definitively expired non-refreshable sessions receive 401; sessions with expiration checks disabled, or expired refreshable sessions with automatic refresh enabled, continue through normal session handling. Refreshable sessions must also satisfy the configured missing-persistent-session policy. Invalid or otherwise ineligible requests receive 401 before an event stream is opened.

Local session-error and logout redirects include Nuxt's configured app.baseURL. For example, an application mounted at /portal/ returns to /portal/ rather than the origin root.

Configuration

Example configuration in nuxt.config.ts with Keycloak provider:

nuxt.config.ts
      keycloak: {
        baseUrl: '',
        clientId: '',
        clientSecret: '',
        redirectUri: 'http://localhost:3000/auth/keycloak/callback',
        userNameClaim: 'preferred_username',
        logoutRedirectUri: 'http://localhost:3000',
        // Single sign-out
        sessionConfiguration: {
          singleSignOut: true,
          singleSignOutIdField: 'sub',
        },
      },

Options

OptionTypeDefaultDescription
singleSignOutbooleanfalseEnable single sign-out across tabs
singleSignOutIdField'sub' | 'aud''sub'Token claim a session needs to join a single sign-out group

Provider Support

Single sign-out is supported by all providers that issue refresh tokens. The feature requires a persistent session to work across browsers.