Standard and custom claims
All domains, identifiers, and values in these examples are fictional.
The printer now accepts sign-ins from two providers, and it treats a subject as meaningful only next to the issuer that assigned it. When you sign in with your photo account, the validated ID token gives it exactly that pair: user-2048 at https://auth.photos.example, authenticated at 08:59:45. The pair is enough to find your printer account. It is not enough to greet you by name, to show your picture beside your saved projects, or to tell the printer where to send a confirmation when your calendar ships.
For those, the printer needs information about you as well as about the sign-in. OpenID Connect describes both kinds in the same way, as claims.
Statements about you
A claim is a name with a value, such as "given_name": "Robin". What is Identity? described a claim as a statement about someone that may or may not be true, and Trust across systems showed claims carrying a sign-in from an identity provider to an application. The ID token is made of claims too, but they describe the token and the authentication event: who issued it, for whom, when, and in answer to which request. The claims in this group describe you.
Here is what the photo service can say about your account:
{
"sub": "user-2048",
"name": "Robin Park",
"given_name": "Robin",
"family_name": "Park",
"picture": "https://photos.example/avatars/user-2048.jpg",
"locale": "en-US",
"email": "[email protected]",
"email_verified": true,
"updated_at": 1788220800
}Every value here is the photo service's statement, but it stands behind them in different ways. sub is its own identifier for your account, and nobody knows better than the photo service which account that is. "Robin Park" is whatever you typed when you created the account. The photo service has probably never checked it against anything. The picture is one you uploaded. email_verified says the photo service once confirmed, by its own process, that you controlled [email protected]. updated_at records when you last changed any of these details, 1 September 2026 at 00:00 UTC, written in seconds since 1970 like the times in the ID token.
So the printer weighs each claim against what it will be used for, as What is Identity? described with claims and evidence. A name shown in a greeting needs no evidence at all. If it is wrong, the greeting is wrong. An email address that receives order confirmations should at least be verified. Deciding which printer account belongs to you is a different matter, and only the issuer and subject are fit for it. Claim stability and privacy returns to that distinction.
Apart from sub, none of these claims is in the ID token the printer has already validated. Scopes and the claims parameter and The UserInfo endpoint show how the printer asks for them and where it collects them.
The standard claims
OpenID Connect defines a small set of standard claims with fixed names, types, and meanings. Because every provider uses the same names, the printer reads given_name in the same way from the photo service and from the mail service. That is the problem the /me endpoints in From delegated access to sign-in never solved, because each service chose its own field names.
| Claims | What they hold |
|---|---|
sub | The provider's identifier for the account, a case-sensitive string. |
name, given_name, family_name, middle_name | A full name for display, and its parts. A person can have several given or family names, separated by spaces, or no family name at all. |
nickname, preferred_username | A casual name, and the short name the person would like to be known by at the relying party. |
profile, picture, website | Addresses of a profile page, a profile photo, and a personal website or blog. picture must point at an image file, not at a page containing one. |
email, email_verified | The preferred email address, and a boolean saying whether the provider has verified it. |
phone_number, phone_number_verified | The preferred phone number, recommended in international format beginning with + and the country code, and a boolean saying whether the provider has verified it. |
address | A postal address as a JSON object, with parts such as street_address, locality, postal_code, and country, or a single formatted value. |
gender, birthdate | Gender, and a birth date written as YYYY-MM-DD. The year can be 0000 when the person shares only the day and month. |
zoneinfo, locale | A time zone name such as Europe/Paris, and a language tag such as en-US. |
updated_at | When the person's information last changed, as a number of seconds since 1970. |
A few of these are easy to misread. name is meant for display, with its parts in the order the person prefers, which is not always given name first. When the printer wants a full name, it shows name rather than joining given_name and family_name itself.
preferred_username looks like an identifier and is not one. It is the short name you would like to be called at the printer, such as robin.p. It may contain spaces, @ signs, and slashes, you can change it whenever you like, and the specification says plainly that relying parties must not rely on it being unique. Another photo account could prefer robin.p tomorrow. The printer can display it, but it never looks up an account with it.
Each claim also has a type. email_verified is a JSON boolean rather than the text "true", updated_at is a number, and address is an object, so code that treats every claim as a string will misread some of them.
No provider holds every claim for every account. The photo service has no phone number or birth date for you, so no request will produce them. A provider can list the claims it may be able to supply in the claims_supported field of its discovery document. That list describes the provider in general, not what it holds about any one person.
Custom claims
The standard set is deliberately small. A provider often knows other things a relying party could use, and it can send claims of its own alongside the standard ones.
Suppose the printing company and the photo service agree on a partnership: members of the photo service's paid plan get free shipping on printed books. The printer needs to know whether you are a member, and only the photo service can say. It defines a claim for the purpose:
"https://photos.example/claims/membership": "plus"The name looks like a web address, and that is deliberate. A name such as membership would be easier to read, but nothing stops the mail service from sending a membership claim of its own that means something else, such as a newsletter you joined, and the printer reads claims from both providers. A future standard could define membership with yet another meaning. A collision-resistant name, built from a domain the photo service controls, cannot clash with anyone else's, because names under photos.example are the photo service's to define. OpenID Connect recommends names like this for claims outside the standard set. Short names agreed privately between two parties are also allowed, and they are common, but they hold up only while nobody else uses the same name for something different.
The name prevents collisions. It does not explain the claim. What "plus" means, which other values can appear, whether someone without a paid plan receives a different value or no claim at all, and how current the value is all come from the photo service's documentation and the agreement between the two companies, in the same way that the meaning of photos.read came from the service that defined it. The printer needs those answers before it builds free shipping on the claim.
It also needs to know what the claim can prove. The photo service is the authority on its own memberships, so this claim is as reliable as the photo service itself, as of the moment it was issued. A membership can lapse the next morning. A custom claim that repeats something the photo service merely heard, such as a company name you typed into your profile, is no more reliable for having a name of its own. Sometimes the authority is another organization altogether, such as a university confirming that you are a student. Claims that a provider passes on from such a source are called aggregated and distributed claims, and Advanced OIDC covers them, starting with Combining claims from multiple sources.
In organizations, custom claims carry much of the useful information. Lantern's identity provider might send its project portal a claim naming each designer's team, and the portal could use it to open the right projects first. The same rules apply: a name Lantern controls, a meaning Lantern documents, and a relying party that decides for itself what the value is allowed to affect.
Each provider decides how its custom claims are requested. Some tie them to a scope of their own. Others expect the relying party to name them individually, which the next lesson shows. When a claim arrives that the printer does not recognize, it ignores it. That keeps the printer working when a provider adds claims, and it keeps information the printer never asked for out of its records.