nonce Claim in an OpenID Connect ID Token
nonce carries back the exact random value the client sent in its authentication request. Comparing it to the value you stored is what proves the ID token came from the request you made rather than being replayed from another one.
At a glance
- Claim
- nonce
- Defined in
- OpenID Connect Core 1.0 section 2
- Value type
- String, passed through unmodified by the authorization server
- Required
- Required in the implicit flow and any hybrid flow that returns an ID token from the authorization endpoint. Optional but recommended in the authorization code flow.
- Sample value
- n-0S6_WzA2Mj
- In the decoder
- Shown under Custom claims with its raw value, since only the seven RFC 7519 claims are explained by name.
In detail
The client generates a random value, sends it as the nonce parameter on the authentication request, and keeps a copy tied to that browser session. The authorization server copies the value into the ID token without changing it. The relying party then compares the claim against the stored copy and rejects the token if they differ or if the claim is missing when it expected one.
The attack this blocks is replay of a token captured somewhere else. Without a nonce, an ID token that is otherwise valid, correctly signed, in date, addressed to the right audience, can be injected into a different login attempt and accepted. Binding the token to a value only the initiating client knew makes that impossible, since the attacker's captured token carries the wrong nonce.
It is easy to confuse with the state parameter, which travels in the redirect and protects the request against cross site request forgery. state is checked before the token is even fetched and never appears inside the token. nonce lives inside the signed ID token and is checked after the signature. They defend different steps and are not substitutes for each other.
The decoder lists nonce under Custom claims with the raw string it found. It cannot verify anything about it, because the value it would need to compare against is in the client's own session, not in the token. What the tool is good for here is confirming that the authorization server actually echoed a nonce, which is the usual reason a login is failing with a nonce mismatch.
Examples
// Authentication request, abbreviated
GET /authorize?response_type=id_token&client_id=web-dashboard&nonce=n-0S6_WzA2Mj
// Resulting ID token payload
{
"iss": "https://auth.example.com",
"aud": "web-dashboard",
"nonce": "n-0S6_WzA2Mj"
}Things that catch people out
- Generating a nonce and never comparing it on the way back. An unchecked nonce provides exactly no protection while looking like it does.
- Reusing one nonce across logins, or deriving it from something predictable. It has to be fresh and unguessable per authentication request.
- Assuming state covers this. state protects the redirect; nonce protects the token, and a deployment that returns ID tokens from the authorization endpoint needs both.
Try it: JWT Decoder
Paste a token to decode the header and payload, read the claims and expiry, and verify the signature in your browser. Nothing is uploaded.
JWT Decoder
LOCAL · Browser-OnlyDecode and inspect JSON Web Tokens without sending them to a server
Related JWT claims and algorithms
All jwt claims and algorithms →azp (Authorized Party) Claim in a JWT
The azp claim names the client an ID token was issued to. When OpenID Connect requires it, how it differs from aud, and what the decoder shows.
c_hash (Code Hash) Claim in an ID Token
The c_hash claim binds an ID token to the authorization code returned with it. Where hybrid flows need it, how it is computed, and what the decoder shows.
at_hash (Access Token Hash) Claim in an ID Token
The at_hash claim ties an ID token to the access token issued with it. How the left half hash is computed, when it must be checked, and decoder limits.
auth_time Claim in an OpenID Connect ID Token
The auth_time claim records when the end user actually authenticated, not when the token was issued. How max_age uses it and how the decoder shows it.
acr (Authentication Context Class Reference) Claim
The acr claim states how strongly the user was authenticated. Why its values are provider specific, what the value 0 means, and how the decoder shows it.
amr (Authentication Methods References) Claim
The amr claim lists how the user authenticated. The registered values from RFC 8176, why the list is not proof of strength, and what the decoder shows.
Tools for this
- JWT Decoder Free online JWT decoder - decode and inspect JSON Web Tokens without sending them to a server