Scopes and the claims parameter

Scopes that request claims

OpenID Connect defines four scope values that request claims. Each one stands for a fixed group:

The provider treats every claim these scopes request as voluntary: the relying party would like it, but the sign-in does not depend on it. You may be able to decline some of them on the consent screen, and the provider may withhold others under its own policy.

These are still OAuth scopes. They describe what the access token issued at the end of the exchange may be used for, and here that use is reading claims about you. With the authorization code flow, the claims requested by these scopes come back from the UserInfo endpoint, which the printer calls with that access token. They are placed in the ID token only when the flow issues no access token at all. That happens only with a response type the printer does not use, which Response types and response modes describes. Many providers also copy a few of them, often a name and an email address, into the ID token. The printer can read them there when they appear, but its code should not depend on them.

The profile scope is the blunt part of the printer's request. The printer uses your given name in greetings and your picture beside your saved projects. Through profile, it also asked for your birth date, gender, website, and time zone. The photo service happens to hold none of those for you, but another customer's account might, and a consent screen that mentions your "profile" may not say how much that word covers.

Asking for individual claims

The claims request parameter lets a relying party name the claims it wants one at a time, and say where each one should be returned. Its value is a JSON object with two defined members. userinfo lists claims to return from the UserInfo endpoint, and id_token lists claims to add to the ID token. A narrower version of the printer's request could carry this, shown decoded:

{
  "userinfo": {
    "given_name": null,
    "picture": null,
    "email": {"essential": true},
    "email_verified": {"essential": true}
  }
}

In the authentication request, the JSON is URL-encoded into a single parameter, and the scope shrinks to openid:

scope=openid
&claims=%7B%22userinfo%22%3A%7B%22given_name%22%3Anull%2C...

The encoded value is shortened here, and the rest of the request is unchanged. Dropping profile and email from the scope matters. Claims named in the claims parameter are added to whatever the scopes request, so a request that kept profile would still ask for all fourteen of its claims. Because the userinfo member asks for claims from UserInfo, the request must also use a response type that issues an access token, which the authorization code flow always does.

Each entry says how the claim is wanted. null requests it in the ordinary way, as a voluntary claim. An object can add detail. {"essential": true} marks an essential claim, one the relying party considers important for what you are trying to do. A provider can use that to explain on the consent screen why the printer is asking. It is not a guarantee. The provider must not fail the request because a claim could not be returned, essential or not, unless that claim's own definition says otherwise. Authentication context and methods meets the main exception, a requested level of authentication.

An object can also carry value or values, asking for a claim only if it has a particular value or one of a list. A claim that does not match is left out of the response. That is mostly useful for claims about the sign-in rather than about you. Authentication context and methods uses values to request an authentication context, and a value for sub under id_token tells the provider to fail the sign-in unless that particular account is the one signed in.

Placement is a choice too. Moving email under id_token would put your address inside the signed ID token, so the printer could read it without calling UserInfo. The cost is that an ID token can travel further than a UserInfo response. A relying party may keep it to send back to the provider later as a hint, in a URL that passes through your browser, as RP-initiated logout will show, and any claims inside travel with it. Information the printer needs only at sign-in is usually better fetched from UserInfo.

Support for the claims parameter is optional. A provider that supports it sets claims_parameter_supported to true in its discovery document, and a missing field means it does not. A provider without support is expected to return whatever set of claims it judges useful, which may be more or less than the printer asked for. Either way, the printer works with what actually arrives.

When claims are missing

Suppose you clear the box for your email address on the consent screen. The UserInfo response for the narrower request might then be:

{
  "sub": "user-2048",
  "given_name": "Robin",
  "picture": "https://photos.example/avatars/user-2048.jpg"
}

The email claims are simply absent. A claim can be missing for several reasons, and the printer usually cannot tell which. You may have declined it. The provider may not hold it, as with a phone number the photo service never had. The provider's policy may withhold it from some relying parties, or it may have ignored a claims parameter it does not support. Some providers also report a narrower scope in the token response, as Exchanging a code for tokens described, but the claims that actually arrive are what count. None of this is an error.

The specification asks providers to leave a missing claim out rather than send it as null or an empty string. The printer treats all three in the same way, and it never reads a missing claim as a default value. A missing email_verified, in particular, is not a quiet way of saying true.

What happens next depends on what the claim was for. Without given_name, the greeting says "Welcome" without a name. Without picture, your projects show your initials. Without an email address on a first sign-in, the printer still needs somewhere to send order confirmations, so it asks you for an address and verifies it itself, by sending a code, before relying on it.

Two reactions make things worse. Failing the sign-in punishes you for a choice the provider offered, even though the ID token has already established who you are. Sending you back to the photo service again and again, hoping for a different answer, ignores an answer you or the provider have already given.

The opposite happens too. A provider can return claims the printer did not ask for, or more than it needs. The printer reads what each feature uses and leaves the rest behind rather than storing everything that arrived. Claim stability and privacy explains why that restraint matters.