OIDC-ID-Token-Validator

The checks a relying party must make

An ID token is a signed JWT in which an OpenID Provider asserts that a user authenticated, for a particular client, at a particular time. Decoding it proves nothing; a relying party has to validate it, and OpenID Connect Core 1.0 §3.1.3.7 lists what that means. The validator runs those steps in order and reports each one:

• iss must equal the issuer you configured, character for character. The validator also tells a near miss — a trailing slash, a different letter case — from a plain mismatch, because that is the most common cause of issuer did not match errors in client libraries.
• aud must contain your client_id. Additional audiences are reported, and when there are several, azp should name your client.
• The signature must verify with the provider's key, chosen by kid from its JWK Set. When no key matches, the validator lists every candidate and the reason it was skipped (kid, kty, alg, use), the usual story behind unable to find a signing key. An alg of none, or an algorithm other than the one registered for your client, is rejected.
• exp, iat and nbf are compared with the check time, allowing a clock skew you can set (60 seconds by default). Tokens issued too long ago can be rejected too.
• nonce must equal the value you sent in the authentication request — the defence against a token injected into another user's session.
• auth_time is required when you sent max_age or asked for it as an essential claim, and must be recent enough; acr should be one of the values you requested.

Header checks come first: a typ of at+jwt (an access token) or logout+jwt (a logout token) is never an ID token, and keys embedded in the header (jwk, jku, x5u) must not be trusted just because they are there.

at_hash, c_hash and s_hash

When an ID token is returned together with an access token or an authorization code — the implicit and hybrid flows — it binds them with a hash claim: at_hash for the access token, c_hash for the code (Core §3.2.2.9 and §3.3.2.11), and s_hash for state in FAPI 1.0 Advanced. The value is the base64url encoding of the left half of the hash of the ASCII value, with the hash function taken from the token's alg: SHA-256 for RS256, ES256 and PS256, SHA-384 and SHA-512 for the larger variants. Paste the access token or code and the validator computes the expected value next to the one in the token. Both are used only in this page and never go into a share link.

The discovery audit

An OpenID Provider describes itself in a JSON document at {issuer}/.well-known/openid-configuration (OpenID Connect Discovery 1.0): its issuer identifier, endpoints, the location of its keys (jwks_uri) and the algorithms and flows it supports. The validator runs a pasted or downloaded document through oauth4webapi — the client library many JavaScript relying parties use — and reports whether it would accept it. It then checks the document against the specification and the OAuth 2.0 Security Best Current Practice (RFC 9700): the issuer matches exactly and has no query or fragment, every endpoint uses TLS, RS256 is offered for ID tokens, none is not, PKCE with S256 is advertised, and the implicit and password grants are flagged. When a token is validated too, its alg must be one the document advertises.

Examples and share links

The examples are the four ID tokens of Core Appendix A, signed in 2011 with the RSA key of Appendix A.7, so the example sets the check time inside their validity window. A share link carries your validation set-up — issuer, client_id, nonce, policy, the discovery document and keys. It carries the ID token only once the token has expired: until then, an ID token is a credential at services that accept ID tokens as bearer tokens, such as Google Cloud Run and Identity-Aware Proxy.

To decode an access token or any other JWT, use the JWT debugger; to fetch and audit a JWKS from its URL, the JWKS checker; and for tokens bound to a client key, the DPoP proof inspector. The same checks are walked through with code in OIDC ID token validation, step by step.