OpenID Connect Claims and ID Tokens

OpenID Connect (OIDC) adds an identity layer on top of OAuth 2.0. While OAuth 2.0 handles authorization (what can this app access?), OIDC answers the identity question (who is the user?). OIDC is implemented by adding the "openid" scope to an OAuth 2.0 request, which causes the authorization server to return an ID token alongside the access token.

The OIDC ID token is a JSON Web Token (JWT) containing claims about the authenticated user. The JWT is signed by the authorization server using its private key (RS256 or ES256 typically), and the relying party (client application) verifies the signature using the authorization server's published public keys (JWKS endpoint).

Required and commonly used ID token claims: "sub" (subject, unique user identifier), "iss" (issuer, authorization server URL), "aud" (audience, client ID), "exp" (expiration Unix timestamp), "iat" (issued-at Unix timestamp). Optional: "auth_time" (when authentication occurred), "nonce" (replay prevention), "at_hash" (hash of access token), "acr" (authentication context class), "amr" (authentication methods used).

The OIDC UserInfo endpoint returns additional claims about the authenticated user when called with a valid access token. Clients request specific claim sets via scopes: "profile" (name, picture, locale), "email" (email, email_verified), "address" (formatted address), "phone" (phone_number, phone_number_verified). The UserInfo response is a JSON object or JWT.

ID token validation begins with signature verification. The client fetches the authorization server's JWKS (JSON Web Key Set) from the well-known endpoint, finds the key matching the JWT header's "kid" (key ID) parameter, and verifies the JWT signature. This proves the token was issued by the legitimate authorization server and was not tampered with.

After signature verification, the client must validate: "iss" must match the expected authorization server URL exactly (including scheme and path). "aud" must contain the client's own client_id. "exp" must be in the future (reject expired tokens). "iat" should be reasonably recent. All four checks are mandatory per the OIDC specification.

The nonce claim prevents ID token replay attacks. The client generates a random nonce and includes it in the authorization request. The authorization server embeds the nonce in the ID token. The client verifies the nonce in the ID token matches what it sent. This prevents an attacker who captures an ID token from replaying it to authenticate to a different session.

When OIDC uses the implicit flow (response_type=id_token), the ID token is returned directly in the URL fragment. The client must validate at_hash (the hash of the access token) to bind the access token to the ID token. Without at_hash validation, access token substitution attacks are possible. This is another reason the implicit flow is deprecated.

OIDC defines standard scope-to-claim mappings. The "openid" scope is mandatory and returns the "sub" claim. "profile" returns name, given_name, family_name, nickname, picture, website, locale, zoneinfo, updated_at. "email" returns email and email_verified. Requesting unnecessary scopes violates the principle of minimal disclosure and may expose sensitive user data.

When implementing OIDC multi-provider login (e.g., "Sign in with Google" and "Sign in with GitHub"), claim injection attacks are possible. If an attacker creates an account on Provider B with the email address of a victim who uses Provider A, they might gain access if the application matches accounts by email claim alone. Always match accounts by (iss, sub) pair, not email alone.

The OIDC hybrid flow (response_type=code id_token) returns both an authorization code and an ID token from the authorization endpoint. The ID token allows immediate identity verification while the code is exchanged for tokens via the back-channel. Used when the client needs to immediately render user information before completing the back-channel token exchange.

Which combination of claims must a relying party validate in an OIDC ID token?

OIDC adds a signed JWT ID token to OAuth 2.0 flows. Validate signature (JWKS), iss (exact match), aud (client_id), exp (not expired), and nonce (if sent). The UserInfo endpoint provides additional claims via scopes. Match accounts by (iss, sub) pair, never by email alone, to prevent claim injection. The implicit flow is deprecated; use authorization code with PKCE for OIDC.