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.
Sign users out
Section titled “Sign users out”-
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.
-
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. -
When the user clicks your app’s sign-out button, read the ID token from their session. Then revoke the refresh token at
/auth/revokewith your client’s credentials, or the access token if your app keeps no refresh token:POST /auth/revoke HTTP/1.1Host: auth.example.comContent-Type: application/x-www-form-urlencodedAuthorization: Basic bXktYXBwOm15LXNlY3JldA==token=eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...A public client, such as a single-page app, sends its
client_idin the body instead of the header. The answer is200 OKwith an empty body. Then end your app’s own session, and delete every token your app kept for them. -
Answer with a redirect that sends the browser to
/auth/logout, with the ID token asid_token_hint, the address from step 2 aspost_logout_redirect_uri, and a new randomstate:HTTP/1.1 302 FoundLocation: https://auth.example.com/auth/logout?id_token_hint=eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...&post_logout_redirect_uri=https%3A%2F%2Fapp.example.com%2Fsigned-out&state=af0ifjsldkjThe 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.
-
The auth server signs the user out at once, without asking, and sends the browser back with your
state:HTTP/1.1 302 FoundLocation: https://app.example.com/signed-out?state=af0ifjsldkjCheck that
stateis the one you sent, and show the user they’re signed out.
What a sign-out ends
Section titled “What a sign-out ends”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.
Your app’s tokens
Section titled “Your app’s tokens”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_accessscope, isn’t tied to a session at all. - An access token works at
/userinfoand 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.
Where the user lands
Section titled “Where the user lands”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.
Hiding the hint
Section titled “Hiding the hint”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.1Host: auth.example.comContent-Type: application/x-www-form-urlencoded
id_token_hint=eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...&post_logout_redirect_uri=https%3A%2F%2Fapp.example.com%2Fsigned-out&state=af0ifjsldkjA 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.
When it’s refused
Section titled “When it’s refused”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.
Get told when a session ends
Section titled “Get told when a session ends”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.
-
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. -
When the auth server calls it, read
logout_tokenfrom the form body:POST /backchannel-logout HTTP/1.1Host: app.example.comContent-Type: application/x-www-form-urlencodedlogout_token=eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiIsInR5cCI6ImxvZ291dCtqd3QifQ... -
Check the token. Refuse it unless all of these hold:
- its signature verifies with one of the keys at
/certs, and its header’salgisRS256; - its header’s
typislogout+jwt; issis the issuer,audis your client’s identifier, it has aniat, and itsexphasn’t passed;eventsis an object holding the memberhttp://schemas.openid.net/event/backchannel-logout;- it has a
sub, asidor both; - it has no
nonce.
Most JWT libraries check the signature,
alg,typ,iss,audandexpwhen you tell them what to expect. Thetyp,eventsandnoncechecks 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. - its signature verifies with one of the keys at
-
End your app’s sessions the token names. With a
sid, that’s each session whose ID token has thatsidand the samesub. Without one, it’s every session your app has for thatsub, on every device. Delete the tokens your app kept for them. -
Answer
200 OKwithCache-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, answer400, with no-store too:HTTP/1.1 400 Bad RequestContent-Type: application/jsonCache-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.