id_token_hint
This page helps your app make sure a sign-in comes back for the user it expects.
id_token_hint is an OpenID Connect parameter of the authorization request. Its value is an ID token the auth server gave your app earlier, and it names the user your app expects by that token’s subject, its sub. The auth server never gives your app a code for anyone else.
Send a hint
Section titled “Send a hint”-
Keep the ID token from the user’s last sign-in.
-
Send it, URL-encoded, as
id_token_hint. It’s most useful withprompt=none, to renew the user’s tokens without showing them anything:GET /auth/authorize?client_id=my-app&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&response_type=code&scope=openid%20profile&prompt=none&id_token_hint=eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...&code_challenge=...&code_challenge_method=S256&state=... HTTP/1.1Host: auth.example.com -
If the browser’s session is the hinted user’s, a code comes back as usual. If it isn’t,
error=login_requiredcomes back: send the user to sign in again, without the hint if someone else may sign in. See login_required.
What the auth server checks
Section titled “What the auth server checks”The hint must be an ID token the auth server signed, with its issuer in iss and a sub. Access tokens and refresh tokens are refused, although the same key signs them.
Two things aren’t checked. The token can be expired, as OpenID Connect recommends, since a hint usually comes from a sign-in some time ago. And it doesn’t have to have been issued to the client that sends it.
A hint that fails a check is refused with invalid_request:
error_description |
Why |
|---|---|
| “The id_token_hint is invalid.” | It isn’t a token the auth server signed, or it’s an access or refresh token. |
| “The id_token_hint was not issued by this server.” | Its iss isn’t the auth server’s issuer. |
| “The id_token_hint does not contain a valid sub claim.” | It has no sub. |
That error reaches your app like any other error in the request: at once when the request has prompt=none, or when the browser has a valid session and the request doesn’t have prompt=login, and otherwise after the user signs in. See The app gets no error back.
What the hint changes
Section titled “What the hint changes”| The browser has | With prompt=none |
Without it |
|---|---|---|
| A session of the hinted user | A code, silently | A code, with single sign-on |
| A session of someone else | login_required: “The current session user does not match the id_token_hint” |
The user is asked to sign in |
| No session | login_required: “User authentication is required” |
The user is asked to sign in |
Without prompt=none, whoever then signs in has to be the hinted user. If someone else does, the request ends with login_required: “The authenticated user does not match the id_token_hint”. To let whoever is at the browser sign in, send the request again without the hint. Whoever signs in over another user’s session ends it, the hinted user or not, as Ending sessions describes.
With prompt=login, the user signs in again even over their own session, and it still has to be the hinted user. Send the two together to confirm it’s still the same person before a sensitive operation.
Signing out
Section titled “Signing out”/auth/logout takes an id_token_hint too, with rules of its own, an encrypted hint among them. See Logout.