Sign-out

Sign users out of your application and OneiD with RP-initiated logout, and design for applications that are not notified.

View as Markdown

Signing a user out involves two sessions: your application’s own session and the OneiD session that gives single sign-on. Your application clears its own session, then sends the browser to OneiD’s end session endpoint, which ends the OneiD session and can return the user to your application. This follows OpenID Connect RP-Initiated Logout 1.0.

How sign-out works

1. The user chooses Sign out in your application.
2. Your application clears its own session and removes the tokens it holds.
3. Your application redirects the browser to https://YOUR_ONEID/connect/logout
   with id_token_hint, post_logout_redirect_uri and state.
4. OneiD ends the OneiD session and revokes your application's tokens for the user.
   If users sign in at an upstream OpenID Connect provider, OneiD continues
   to that provider's sign-out.
5. OneiD redirects the browser to your post_logout_redirect_uri with state.

Before you start

Ask your administrator to register your post-logout redirect URIs on the client, for example https://app.example.com/signed-out. They must match exactly, like redirect URIs. See Register an application.

Keep the ID token from sign-in. You send it as id_token_hint.

Send the sign-out request

The end session endpoint accepts GET and POST.

GET /connect/logout
  ?id_token_hint=eyJhbGciOiJSUzI1NiIsImtpZCI6IkVYQU1QTEVfS0lEIn0.EXAMPLE_ID_TOKEN_PAYLOAD.EXAMPLE_SIGNATURE
  &post_logout_redirect_uri=https%3A%2F%2Fapp.example.com%2Fsigned-out
  &state=r7Kp2Xw9Tq4Lm1Vz HTTP/1.1
Host: YOUR_ONEID

As a POST, from a form the browser submits:

POST /connect/logout HTTP/1.1
Host: YOUR_ONEID
Content-Type: application/x-www-form-urlencoded

id_token_hint=eyJhbGciOiJSUzI1NiIsImtpZCI6IkVYQU1QTEVfS0lEIn0.EXAMPLE_ID_TOKEN_PAYLOAD.EXAMPLE_SIGNATURE&post_logout_redirect_uri=https%3A%2F%2Fapp.example.com%2Fsigned-out&state=r7Kp2Xw9Tq4Lm1Vz

POST keeps the ID token out of the URL. Use it if your framework supports it.

If you no longer have the ID token, send client_id instead:

GET /connect/logout?client_id=YOUR_CLIENT_ID&post_logout_redirect_uri=https%3A%2F%2Fapp.example.com%2Fsigned-out&state=r7Kp2Xw9Tq4Lm1Vz HTTP/1.1
Host: YOUR_ONEID

Checkpoint After sign-out, the browser lands on https://app.example.com/signed-out?state=r7Kp2Xw9Tq4Lm1Vz. Open your application and choose Sign in: OneiD asks for the password again.

Parameters

Parameter Required Description
id_token_hint Recommended An ID token OneiD issued to your application for this user. Identifies the user and the client.
post_logout_redirect_uri No Where to send the user afterwards. Must be registered for the client, exactly.
client_id When there is no id_token_hint Your client ID.
state Recommended An opaque value OneiD returns to the post_logout_redirect_uri. Check it there.

Rules

  • A post_logout_redirect_uri needs id_token_hint or client_id. Without either, OneiD refuses the request with invalid_request, because it cannot tell which client’s registered URIs to check.
  • The redirect URI must be registered. An unregistered post_logout_redirect_uri is not followed.
  • A forged id_token_hint is refused. OneiD accepts only ID tokens it issued.
  • A different user asks for confirmation. If the hint names another user than the one signed in to OneiD, OneiD asks the user to confirm the sign-out.
  • Without post_logout_redirect_uri, the user stays on OneiD. They end on OneiD’s signed-out page.
  • A disabled client gets unauthorized_client.

What sign-out ends

What Ended
Your application’s session Only if your application clears it. OneiD cannot reach into your application.
The OneiD session Yes. Signing out of OneiD ends the OneiD session, so the next sign-in asks for the password again.
Your application’s tokens for this user Yes. Refresh tokens and access tokens issued to your client for this user are revoked in OneiD’s store.
Other applications’ tokens No.
Other applications’ sessions No. See below.
The upstream provider’s session When users sign in at an upstream OpenID Connect provider, OneiD continues to that provider’s sign-out.

An API that validates access tokens locally, as most do, accepts a revoked access token until it expires. Keep access token lifetimes short; they are 1 hour by default.

What is not supported

Not supported OneiD does not support front-channel logout, back-channel logout or the session management iframe. When a user signs out of one application, OneiD does not notify the other applications the user signed in to.

Other applications keep their own sessions until those end. Design for this:

  • Keep application sessions short, or tie them to the access token’s lifetime.
  • Check silently on important pages. Send an authorisation request with prompt=none as a top-level redirect, not in a hidden iframe: OneiD pages cannot be framed. If OneiD answers login_required, the user has signed out of OneiD; end your session. See Sessions, prompt and max_age.
  • Treat a failed refresh as sign-out. When a refresh returns invalid_grant, end your session and remove the tokens.
  • Tell users. On your signed-out page, say that other applications may still be signed in.

Clear your application’s session

Do this before you redirect to OneiD, so the user is signed out of your application even if the redirect fails:

  1. Delete your session cookie, or end the server session.
  2. Remove the access token, ID token and refresh token you hold. Keep a copy of the ID token only long enough to build the sign-out request.
  3. Redirect to /connect/logout.

Make sign-out a POST in your application, from a button in a form, so another site cannot sign your users out with a link.

On the post_logout_redirect_uri page, check state, then show a signed-out page. Do not start a new sign-in automatically.

If your application only wants to sign the user out of itself and keep the OneiD session, skip the redirect and revoke the refresh token at /connect/revoke instead. See Refresh tokens.

Learn more