Skip to content

Sign users out

This guide adds a sign-out button that ends your app’s tokens, signs the user out of the auth server too, and brings them back to your app.

Ending your app’s own session isn’t enough. The auth server keeps a session of its own, so the next time your app sent the user to sign in, they’d be signed straight back in. And the tokens your app was given can outlive the sign-out. Your app revokes its tokens at the revocation endpoint, /auth/revoke, then sends the browser to the logout endpoint, /auth/logout, with the ID token the user signed in with, and the auth server signs them out and sends them back.

  1. When the user signs in, keep the ID token from the token endpoint’s answer with the rest of their session in your app. It tells the auth server which sign-in to end.

  2. Decide where the user lands afterwards, such as https://app.example.com/signed-out, and add it to your client’s Sign-out redirect URIs in the admin console, if it isn’t there already. The auth server sends the browser only to an address registered there, exactly as you’ll send it, port included. Your client’s redirect URIs don’t count.

  3. When the user clicks your app’s sign-out button, read the ID token from their session. Then revoke the refresh token at /auth/revoke with your client’s credentials, or the access token if your app keeps no refresh token:

    POST /auth/revoke HTTP/1.1
    Host: auth.example.com
    Content-Type: application/x-www-form-urlencoded
    Authorization: Basic bXktYXBwOm15LXNlY3JldA==
    token=eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...

    A public client, such as a single-page app, sends its client_id in the body instead of the header. The answer is 200 OK with an empty body. Then end your app’s own session, and delete every token your app kept for them.

  4. Answer with a redirect that sends the browser to /auth/logout, with the ID token as id_token_hint, the address from step 2 as post_logout_redirect_uri, and a new random state:

    HTTP/1.1 302 Found
    Location: https://auth.example.com/auth/logout?id_token_hint=eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...&post_logout_redirect_uri=https%3A%2F%2Fapp.example.com%2Fsigned-out&state=af0ifjsldkj

    The browser follows it with a GET, which is what most OpenID Connect libraries send. To keep the ID token out of the browser’s history, post the parameters instead: see Hiding the hint.

  5. The auth server signs the user out at once, without asking, and sends the browser back with your state:

    HTTP/1.1 302 Found
    Location: https://app.example.com/signed-out?state=af0ifjsldkj

    Check that state is the one you sent, and show the user they’re signed out.

With the ID token as its hint, a sign-out ends your app’s part of the user’s session on the auth server. If other apps signed in with the same session, the user stays signed in to them, and the session ends when the last one signs out. Either way the browser’s session cookie is cleared, so the next sign-in in that browser starts with the password.

A sign-out with no hint, or with one the auth server can’t confirm, asks the user “Do you want to sign out?” first, and when they click Sign out, it ends the whole session, every client’s part of it. RP-Initiated Logout, the OpenID Connect standard the endpoint follows, asks for that, since anyone can send a browser to /auth/logout. Ending sessions has the precise rules.

When your client has a back-channel logout URI, a sign-out with the hint sends your app a logout token, a signed message saying the session ended, for its part of the session too, after it has already ended its own. Answer it with 200 like any other. A sign-out with no hint sends one to every app on the session.

An ID token that has expired still works as a hint while the session it came from is there, so a user who leaves your app open all day can still sign out without the question.

Signing out at /auth/logout revokes no token. That’s why step 3 revokes them:

  • A refresh token keeps working while the session it’s tied to does, which, when other apps share that session, is after your app has signed out. An offline refresh token, from the offline_access scope, isn’t tied to a session at all.
  • An access token works at /userinfo and the auth server’s APIs until it expires or is revoked. An API that checks only its signature accepts it until it expires, revoked or not.

Revoking the refresh token, or an access token that hasn’t expired, ends the whole grant, so one call is enough. See What revoking ends.

To cut off everything a session handed out, to every app, end the session instead. A user can, under Account, Sessions in the admin console, and an administrator can, on the user’s Sessions tab. See Ending sessions.

The browser goes to your post_logout_redirect_uri only when it’s one of the sign-out redirect URIs registered on the client the hint was issued to, matched exactly. Otherwise the user stays on the auth server’s “Signed out” page. The sign-out has happened either way. Logout gives every case.

The auth server adds state exactly as you sent it, and nothing else.

The hint is the user’s ID token, and anyone who decodes it can read the claims about the user in it. In the query string of a GET, it’s kept in the browser’s history, and in the access log of any proxy in front of the auth server. The auth server’s own request log leaves it out.

To keep it out of both, post the parameters from a form your page submits on its own:

POST /auth/logout HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
id_token_hint=eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...&post_logout_redirect_uri=https%3A%2F%2Fapp.example.com%2Fsigned-out&state=af0ifjsldkj

A confidential client can go further and encrypt the hint with a key made from its client secret, so it’s unreadable wherever it’s seen or logged on the way. Send client_id beside an encrypted hint, so the auth server knows whose secret decrypts it. Encrypting the hint gives the scheme.

A POST from another origin with no hint, whether another site or another host of the same domain, is refused with 403 Forbidden, to stop a page you don’t control from signing your users out. See Sign-out answers 403.

Your app’s own session can outlive the user’s session on the auth server: when they sign out of another app with no hint, someone ends their session under Account, Sessions, or an administrator disables them. Give your client a back-channel logout URI, and the auth server tells your app each time a session it was on ends, by POSTing a signed logout token there, as OpenID Connect Back-Channel Logout 1.0 describes. Your app then signs the user out at once.

  1. Add a route to your app’s server, such as https://app.example.com/backchannel-logout. Enter it on your client’s Back-channel logout tab in the admin console, and click Save. The auth server calls it directly, not through the browser, so the auth server must be able to reach it, and the call carries no cookie: leave the route out of your app’s sign-in and CSRF checks. Back-channel logout gives the URI’s rules.

  2. When the auth server calls it, read logout_token from the form body:

    POST /backchannel-logout HTTP/1.1
    Host: app.example.com
    Content-Type: application/x-www-form-urlencoded
    logout_token=eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiIsInR5cCI6ImxvZ291dCtqd3QifQ...
  3. Check the token. Refuse it unless all of these hold:

    • its signature verifies with one of the keys at /certs, and its header’s alg is RS256;
    • its header’s typ is logout+jwt;
    • iss is the issuer, aud is your client’s identifier, it has an iat, and its exp hasn’t passed;
    • events is an object holding the member http://schemas.openid.net/event/backchannel-logout;
    • it has a sub, a sid or both;
    • it has no nonce.

    Most JWT libraries check the signature, alg, typ, iss, aud and exp when you tell them what to expect. The typ, events and nonce checks are what tell a logout token from an ID token, which is signed with the same key and names the same user. The logout token lists every claim.

  4. End your app’s sessions the token names. With a sid, that’s each session whose ID token has that sid and the same sub. Without one, it’s every session your app has for that sub, on every device. Delete the tokens your app kept for them.

  5. Answer 200 OK with Cache-Control: no-store, also when your app had no session left to end: the user is signed out either way. For a token that fails a check in step 3, answer 400, with no-store too:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    Cache-Control: no-store
    {"error":"invalid_request","error_description":"The token isn't typed logout+jwt."}

When your app doesn’t answer within 5 seconds, or answers with a 5xx, 408 or 429, the auth server sends the same token again, jti included, so a token can arrive more than once: answer 200 again. See Retries.

A token that never gets through isn’t sent later. See When a delivery is lost for what your app can still rely on.