Sovrain
  1. Documentation
  2. Identity provider

Explanation

Sessions and sign-out

How long a Sovrain session lasts and why, how one sign-out reaches every application, where that reach ends, and how refresh tokens are tied to the session.

Single sign-on creates more than one session. When Anna signs in to Sovrain, she gets a session with Sovrain. When she then opens an application, the application starts a session of its own, based on what Sovrain told it. The two live separately: Sovrain cannot reach into an application and delete its cookie. This page explains how long Sovrain’s session lasts, how a sign-out travels from Sovrain to the applications, and why that journey has limits.

A 60-day session with no idle timeout

A Sovrain session lasts 60 days from the moment of sign-in. It does not get longer with use, and it does not end after a period of inactivity. Whether Anna uses Sovrain every hour or not at all, the session ends 60 days after she typed her password, and she signs in again. The length is fixed and not configurable.

The upside is that people rarely see a sign-in page, which matters for an identity provider: every unnecessary password prompt teaches people to type their password whenever asked, which is what phishing relies on. The downside is real too. A browser that someone forgot to sign out of, on a shared or lost computer, stays signed in for the rest of those 60 days. Nothing ends it automatically after an evening of inactivity.

Several things balance that:

  • People can see their sessions, with device, address and last activity, and end any of them from Sessions on their profile.
  • Changes that matter, such as adding a second step, generating backup codes or approving command-line access, need a sign-in from the last few minutes, so an old session cannot be used to take over the account.
  • Suspending or removing an account ends its sessions at once: every request checks that the account is still usable.
  • An application can demand a recent sign-in whenever it wants, with max_age or prompt=login in OpenID Connect or ForceAuthn in SAML. Sovrain then asks for the password again; signing in again ends the old session and starts a new one, so other applications with back-channel logout receive a sign-out and their refresh tokens from the old session stop working.

The last point is the important one for developers. The Sovrain session tells you that the person is the same one who signed in, possibly weeks ago. If your application handles something sensitive, ask for the freshness you need rather than relying on Sovrain’s session length.

One sign-out for every application

When a session ends, Sovrain tries to tell every application that the person signed in to during that session. It keeps a register of which applications received a sign-in in which browser session, precisely so that it can name them at sign-out; the tokens themselves are self-contained and leave no other trace. In OpenID Connect, the shared sid claim identifies that browser session to every application.

Sovrain uses three channels, because applications support different ones:

Back-channel logout (OpenID Connect). Sovrain’s server sends a signed logout token straight to each application’s server. It does not need the person’s browser, so it also works when the session ends because an admin suspended the account, the person changed their password, or a delegation ended.

Front-channel logout (OpenID Connect). The sign-out page loads each application’s logout address in a hidden frame, so the application can clear its cookie in the browser. This only reaches applications in the browser the person is signing out from, and only when the sign-out goes through a page, not when an admin acts.

SAML single logout. Sovrain sends the browser to each SAML application with SLO enabled, one after another, and collects their answers. It covers the person’s sessions in those applications from every browser, but again only when the person signs out through Sovrain, not when an admin acts.

The same event starts all three: signing out of Sovrain, or confirming a sign-out that an application requested. When an application asks Sovrain to sign someone out, Sovrain always shows a confirmation page first, because the person is about to be signed out of every application, not only the one that asked.

Where sign-out stops

Sign-out is a message, not a command, and it has limits worth knowing before you rely on it.

  • It is best effort. A back-channel call gets one attempt, with a few seconds to connect and answer. An application that is down at that moment never hears about it; there are no retries. The result of each call is written to the application’s activity, so you can see failures.
  • It reaches at most 20 applications per sign-out, both for back-channel calls and for front-channel frames. The cap keeps one sign-out from turning into a burst of outgoing connections or a page that never finishes loading.
  • Front-channel frames depend on the browser. Browsers increasingly restrict what an embedded page from another site can do with its cookies, which can stop a hidden frame from clearing anything.
  • Admin actions reach only back-channel applications. When an admin suspends Bob, OpenID Connect applications with back-channel logout hear about it. SAML applications and front-channel-only applications are not told and keep their own session until it expires.
  • SAML sign-out started by an application does not reach other SAML applications. It can end the Sovrain session, when signature checking is on for that application; OpenID Connect applications with back-channel logout then hear about it, but Sovrain does not run SAML single logout for the other SAML applications.
  • A session that reaches its 60 days ends silently. Its refresh tokens stop working, but no application is sent a sign-out.

What this means in practice: if an application must stop working promptly when access is withdrawn, give it back-channel logout and make it respect the logout token, keep its own session short, or both. The steps are in End your app’s session when people sign out elsewhere.

Refresh tokens belong to the session

An OpenID Connect application can be allowed to receive refresh tokens, so it can get new access tokens without sending the person back through sign-in. In Sovrain a refresh token is not a separate, longer-lived credential. It lives as long as the Sovrain session that produced it, and no longer: when the session ends, by sign-out, by an admin, or because its 60 days are up, the refresh token stops working too. No application gets offline access that outlives the person’s session. Command-line access to the Admin API is the exception: it is approved separately and lasts up to 90 days (see Approve command-line access).

Each refresh also checks again whether the person may still use the application: whether the account is active, whether one of their groups still grants access, whether the application is still enabled and whether the session still meets the application’s two-step requirement. A refresh token is replaced every time it is used. If an old one shows up again, which means it was copied, Sovrain revokes the whole chain of tokens descended from it.

Access tokens, on the other hand, are valid for an hour and cannot be revoked one by one. Sovrain’s userinfo endpoint stops accepting one as soon as the session behind it has ended, but an application that only checks the token’s signature will accept it until it expires. Short access tokens plus refresh tokens tied to the session are the compromise: an application learns about lost access within the hour, without asking Sovrain on every request. See Keep users signed in with refresh tokens.