Skip to content
Goiabada

ID Token Hint

The id_token_hint parameter allows clients to pass a previously issued ID token as a hint about which user should be authenticated. Include it in authorization requests to /auth/authorize.

Why use it

Section titled “Why use it”

Security: Prevents session fixation attacks. If the hint identifies user A, only user A can complete the authorization — even if user B has an active session or successfully authenticates.

User Experience: Enables seamless SSO by indicating which user the client expects to authenticate.

How it works

Section titled “How it works”

When you provide id_token_hint, Goiabada:

  1. Validates the token signature and issuer
  2. Accepts expired tokens (per OIDC spec)
  3. Extracts the sub claim
  4. Enforces that only the specified user can receive tokens

Common usage

Section titled “Common usage”

Silent token renewal (prompt=none)

Section titled “Silent token renewal (prompt=none)”
GET /auth/authorize?
  client_id=my-spa&
  redirect_uri=https://my-spa.com/callback&
  response_type=code&
  scope=openid profile&
  prompt=none&
  id_token_hint=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...&
  state=abc123

If the user has a valid session matching the hint’s sub, authorization succeeds silently. Otherwise, returns login_required.

Re-authentication (prompt=login)

Section titled “Re-authentication (prompt=login)”
GET /auth/authorize?
  client_id=my-app&
  redirect_uri=https://my-app.com/callback&
  response_type=code&
  scope=openid profile&
  prompt=login&
  id_token_hint=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...&
  state=abc123

Forces re-authentication, but only the user specified in the hint can complete it. If they authenticate as a different user, authorization fails.

SSO with hint

Section titled “SSO with hint”
GET /auth/authorize?
  client_id=my-app&
  redirect_uri=https://my-app.com/callback&
  response_type=code&
  scope=openid profile&
  id_token_hint=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...&
  state=abc123
  • If the user has a session matching the hint → SSO succeeds
  • If the user has a session for a different user → re-authentication required
  • If no session → normal login flow (only hinted user can complete)

Error responses

Section titled “Error responses”

When subject mismatch is detected, Goiabada returns:

https://my-app.com/callback?
  error=login_required&
  error_description=The+authenticated+user+does+not+match+the+id_token_hint&
  state=abc123

Invalid hints (bad signature, wrong issuer, missing sub) return invalid_request.

OIDC compliance

Section titled “OIDC compliance”

Goiabada follows OIDC Core 1.0 Section 3.1.2.1:

  • ✅ Validates issuer
  • ✅ Accepts expired tokens
  • ✅ Enforces subject matching (MUST NOT issue tokens for different user)
  • ✅ Does not validate audience (per spec exemption)