email Claim in an OpenID Connect ID Token
email holds the end user's preferred email address as a string. It is a profile attribute, not an identifier: it can change, it may be unverified, and the provider makes no uniqueness promise about it.
At a glance
- Claim
- Defined in
- OpenID Connect Core 1.0 section 5.1
- Value type
- String, an addr-spec as defined by RFC 5322
- Required
- Optional. Returned when the email scope was requested and the provider chooses to release it.
- Sample value
- jordan.reyes@example.com
- In the decoder
- Shown under Custom claims with its raw value. Only the seven RFC 7519 claims are explained by name.
In detail
OpenID Connect is explicit that this value must not be assumed unique, and that it may change over time. A provider is free to release the same address for two accounts, to release an address nobody has proven ownership of, or to release a different address next month for the same person. The claim describes an attribute of the user, and it is only present at all when the email scope was granted.
Because of that, the account key is the iss and sub pair, never the email address. Systems keyed on email break in a predictable order: first a person changes address and appears as a new account, then a recycled corporate address gives a new employee access to their predecessor's records. Storing email as a searchable attribute alongside the real key avoids both without losing anything.
Account linking is where the temptation is strongest. Matching an incoming email claim to an existing local account merges two identities on the strength of a string, and whether that string was verified is a separate claim entirely. If linking has to happen, it should require email_verified to be true, and even then it is safer to confirm with the user than to do it silently.
Personal data in a token is worth a moment's thought as well. The claim sits in the payload, which is base64url encoded and not encrypted, so anything holding the token can read the address. The decoder shows it under Custom claims exactly as encoded, and because decoding happens in your browser with nothing uploaded, pasting a real token here does not put that address anywhere new.
Examples
{
"iss": "https://auth.example.com",
"sub": "8f14e45fceea167a5a36dedd4bea2543",
"email": "jordan.reyes@example.com",
"email_verified": true,
"preferred_username": "jreyes"
}Only iss and sub together identify the account. The other three are attributes that can change.
Things that catch people out
- Using email as a primary key. Addresses change and get recycled, and the provider never promised uniqueness.
- Linking accounts on an email match alone. Without email_verified being true, the address is only a claim the provider passed along.
- Expecting the claim to be present. It requires the email scope, and providers may still withhold it.
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 →email_verified Claim in an OpenID Connect ID Token
The email_verified claim says whether the provider verified the address. Why account linking depends on it, the string true trap, and decoder behaviour.
sub (Subject) Claim in a JWT
The sub claim says who the token is about. Why it is only unique within one issuer, what pairwise subjects change, and how the decoder shows it.
preferred_username Claim in an ID Token
The preferred_username claim carries a shorthand name for the user. Why OpenID Connect says it is neither unique nor stable, and how the decoder shows it.
HS256: HMAC with SHA-256 in a JWT
HS256 signs a JWT with a shared secret using HMAC and SHA-256. Key sizing, the algorithm confusion attack, and verifying one in your browser.
HS384: HMAC with SHA-384 in a JWT
HS384 signs a JWT with a shared secret using HMAC and SHA-384. How it differs from HS256, why SHA-384 is a truncated SHA-512, and verification support.
HS512: HMAC with SHA-512 in a JWT
HS512 signs a JWT with a shared secret using HMAC and SHA-512. Secret sizing, the token size cost, and how the decoder verifies one in your browser.
Tools for this
- JWT Decoder Free online JWT decoder - decode and inspect JSON Web Tokens without sending them to a server