Sessions, prompt and max_age

OneiD remembers a signed-in user with a browser session, which gives single sign-on across your applications. The prompt, max_age and id_token_hint parameters let your application decide when that session is good enough and when the user must sign in again. The ID token’s auth_time, amr and acr claims tell you how and when the user actually signed in.

The OneiD session

When a user signs in, OneiD keeps a browser session for 8 hours, extended while the user is active. While it lasts, any of your applications that sends the user to /connect/authorize gets a sign-in without a password prompt.

Your application has its own session, separate from OneiD’s. OneiD’s session decides whether the user must type a password; your session decides whether your application sends the user to OneiD at all.

Signing out of OneiD ends the OneiD session. See Sign-out.

Authorisation request parameters

Add these to the authorisation request described in Authorization code flow with PKCE.

Not supported OneiD accepts login_hint, ui_locales, display and acr_values but they have no effect. In particular, sending acr_values=urn:oltin:ac:mfa does not force MFA.

How and when the user signed in

The ID token carries three claims about the sign-in:

These claims are in the ID token only, not in the access token or userinfo.

Require a recent sign-in

For actions such as changing payment details, ask for a fresh sign-in and then check that you got one.

GET /connect/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&scope=openid&state=Wd2kP8sLq5Xn0Rt3&nonce=Hy6cV1mZb9Jf4Ks7&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256&max_age=300 HTTP/1.1
Host: YOUR_ONEID

After the code exchange, check the ID token: auth_time must be no more than 300 seconds ago, allowing a small clock skew. Use prompt=login instead of max_age to force a sign-in regardless of age.

Always check auth_time yourself. The parameters ask OneiD to re-authenticate; the claim proves it happened.

Require MFA for an action

OneiD does not enforce acr_values. To require MFA:

1. Check the claims. After sign-in, accept the action only if amr contains mfa (equivalently, acr is urn:oltin:ac:mfa).
2. If it does not, ask the user to sign in again with prompt=login, then check the new ID token. Whether the new sign-in includes an authenticator code depends on the user’s MFA setup in OneiD.
3. If MFA must always apply, ask your administrator to make MFA mandatory for the users concerned. This is the only way to make OneiD itself require it.

function hasMfa(idTokenClaims) {
  return Array.isArray(idTokenClaims.amr) && idTokenClaims.amr.includes('mfa');
}

Note When users sign in at an upstream OpenID Connect provider, amr is ["external"] and acr is urn:oltin:ac:external. That provider’s own MFA applies, and OneiD does not add its own code on top. The ID token does not tell you whether the provider used MFA.

Check the session silently with prompt=none

prompt=none asks OneiD to complete the sign-in only if it can do so without showing anything. Use it to find out whether the user still has a OneiD session, for example on an important page of an application whose session outlives OneiD’s.

GET /connect/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&scope=openid&state=Fn3qR7tYw2Lp9Vx1&nonce=Pz8mK4cX6bJs0Dh5&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256&prompt=none HTTP/1.1
Host: YOUR_ONEID

If the user has a session and nothing else is needed, the callback carries a code as usual. Otherwise it carries an error:

GET /callback?error=login_required&state=Fn3qR7tYw2Lp9Vx1 HTTP/1.1
Host: app.example.com

Run the check as a top-level redirect. OneiD pages cannot be framed, so a check in a hidden iframe does not work. For browser applications that need fresh tokens in the background, use refresh tokens instead. See Browser applications and CORS.

Pending password change or MFA enrolment

An administrator can require a user to change their password or to set up MFA. Until the user does so:

• On a normal sign-in, OneiD sends the user to change the password or enrol an authenticator before the sign-in to your application can complete.
• Under prompt=none, your application receives interaction_required.
• A refresh token request returns invalid_grant.

Your application does not need special handling beyond these errors. The user completes the step at OneiD.

Learn more

• Authorization code flow with PKCE
• Sign-out
• Claims
• OneiD accounts and MFA