Login hints

Suggesting an account

The printer adds a login hint to its request:

https://auth.photos.example/authorize
  ?response_type=code
  &client_id=photo-printer
  &redirect_uri=https%3A%2F%2Fprinter.example%2Fsignin%2Fcallback
  &scope=openid%20profile%20email
  &state=demo-signin-5
  &nonce=demo-nonce-5
  &code_challenge=yifcz29Q4ncDY9kb-79GH-Lwj3XpnDAY0NdoxWaKkJI
  &code_challenge_method=S256
  &login_hint=robin%40mail.example

login_hint tells the photo service which login identifier you are likely to use. If it has no session for you in your phone's browser, its sign-in page can open with [email protected] already filled in, and you go straight to your password or passkey. If you are signed in there to both your own account and the photography club's, the hint lets it choose yours, instead of showing the account chooser from Prompt and account selection or picking whichever you used last.

What a hint may contain is up to the provider. An email address is the most common form, and the specification also allows a phone number written the way the phone_number claim writes it. Some providers accept their own usernames, and some accept the subject identifier they issued. The specification leaves the use of the hint entirely to the provider, so the printer follows the photo service's documentation rather than assuming.

An email address in a URL deserves a second thought. The request travels through your browser, so the address is saved in your browser history and can appear in logs anywhere full URLs are recorded. The photo service already knows your address, so the hint tells it nothing new, but the printer sends one only when it saves you real effort. Where a provider accepts the subject identifier, that value reveals less to anyone else who sees the URL. Pushed authorization requests, covered in The problem PAR solves in Advanced OAuth, keep parameters like this out of the browser altogether: the client sends them to the provider directly, and the browser carries only a reference.

Hinting with an earlier ID token

An email address is a guess about what you might type. When the printer holds an ID token from your current session, it can be exact. The id_token_hint parameter carries an ID token the photo service issued earlier, and tells the photo service that this request concerns the person that token names.

The printer had no token to send with the silent check in Prompt and account selection, because your printer session, and the ID token stored with it, had already ended. Back on your computer, things are different. The printer still has the session it created at 08:00 from that check, and it keeps the ID token from that sign-in on its server with the session, as Establishing an application session described. Later today it will need to send you back to the photo service while that session is active, for a reason Session age and reauthentication explains. Whatever the reason, the answer must be about you, not about whoever happens to be signed in to the photo service in this browser at that moment.

So the request carries one more parameter. The token is shortened here:

&id_token_hint=eyJhbGciOiJSUzI1NiIsImtpZCI6InBob3Rvcy1ycy0yMDI2LTA5IiwidHlwIjoiSldUIn0...

The photo service reads the token's subject, user-2048, and compares it with its own session. If you are signed in as that account, or sign in as it during the request, the result is an ordinary sign-in. Otherwise the photo service must return an error, such as login_required, rather than a sign-in for someone else.

Suppose you had switched the photo service to your club account in another tab. Without the hint, a request from the printer could come back as a perfectly valid sign-in for the club account. With it, the photo service knows that is not the account the printer is asking about. This matters most with prompt=none, where nobody is shown a page that might reveal the mismatch. The specification asks clients to send id_token_hint with prompt=none whenever they have one, and allows a provider to refuse a silent request that arrives without it, although it should answer if it can.

A few details make this work. The token's exp passed hours ago. The specification asks only for an ID token the provider issued earlier, because the printer is not presenting it as proof of a current sign-in, only as a pointer to the person it names. The photo service also does not need to appear in the token's audience, which is just as well, because the token was addressed to the printer. And the token travels through the browser like the rest of the request. The printer's ID tokens carry no profile claims, so little beyond your subject identifier is exposed. A token full of profile claims would put all of them in the URL.

Hints are not authority

A hint changes what the photo service shows you. It changes nothing about what it takes to sign in. Anyone can put any email address in a URL, so the photo service authenticates the person in front of it exactly as it would without a hint. A provider that skipped the password because a hinted account looked right would let anyone sign in as anyone.

The same caution applies on the way back. The printer's evidence of who signed in is the validated ID token, never the hint it sent. On your phone, you could clear the prefilled address and sign in with the club account, and the photo service may ignore a login_hint altogether, as the specification allows. Either way, the printer reads iss and sub from the validated token and looks up the account that pair belongs to.

That leaves the printer with a decision when the result is not the account it expected. The proof belongs to user-2048. If the sign-in on your phone comes back for a different subject, the printer signs that person in to their own account, if they have one, and does not show them your proof. It can say that the order belongs to another account and offer to sign in again.

When the hint came from an active session, a different subject is more serious. Before a sensitive change, the printer sends id_token_hint because it needs the person who owns the session to prove themselves again. A sign-in by anyone else, however valid, is not that. Session age and reauthentication shows how the printer checks for it, along with the one thing neither a hint nor a prompt value tells it: how recently you signed in.