Claims & Scopes

A scope is what a client asks for. A claim is what ThunderID returns. The mapping between the two is what controls which user attributes end up in your ID Token and your UserInfo response.

ThunderID implements three layers:

1. Standard OIDC scopes (OIDC Core §5.4): openid, profile, email, phone, address, with fixed claim sets defined by the spec.
2. Application-defined scope-to-claim mappings (scopeClaims): request a scope, get a configurable bundle of claims.
3. The claims request parameter (OIDC Core §5.5): request specific claims directly, claim-by-claim.

Standard OIDC Scopes

Scope	Claims returned
openid	sub (always included on any OIDC request)
profile	name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, updated_at
email	email, email_verified
phone	phone_number, phone_number_verified
address	address (structured JSON object)

The actual values come from the authenticated user's attributes. Claims are omitted when the user has no value for them.

Custom Scope-to-Claim Mapping (scopeClaims)

Each application can define its own scope-to-claim bundles. Asking for the scope returns the listed claims in both the ID Token and the UserInfo response.

json

{
  "scopeClaims": {
    "profile": ["given_name", "family_name", "picture"],
    "email": ["email", "email_verified"],
    "roles": ["roles", "groups"]
  }
}

Behavior	Detail
Overrides the standard mapping	Yes, profile here returns only the three listed claims, not the full OIDC profile set
Custom scope names	Allowed, roles here is an application-defined scope
Scope not in scopeClaims	Returns no extra claims (but the scope still passes through to access tokens)
Bypasses resource-server filtering	Yes, see "Filtering rules" below

claims Request Parameter

Sometimes you want exactly one claim, not a whole scope's bundle. Pass a JSON object on the authorization request:

http

GET /oauth2/authorize
  ?response_type=code
  &client_id=$CLIENT_ID
  &scope=openid
  &claims={"id_token":{"email":{"essential":true}},"userinfo":{"phone_number":null}}

Sub-object	Targets
claims.id_token	Claims to include in the ID Token
claims.userinfo	Claims to include in the UserInfo response

Inside each sub-object, claim names map to either null (request without constraint) or an object such as { "essential": true } (request and mark as required).

ThunderID advertises claims_parameter_supported: true in Server Metadata.

Filtering Rules

How the request-time scope list becomes the issued-token scope list:

Scope category	Filtered by resource indicators?	Notes
openid, profile, email, phone, address	❌ Not by resource indicators	OpenID Connect standard scopes are reserved. When the application has a scopes allowlist, ThunderID only keeps requested scopes that the application allows.
Custom scopes covered by scopeClaims	❌ Not by resource indicators	The application owns these scopes. When the application has a scopes allowlist, ThunderID only keeps requested scopes that the application allows.
Permissions owned by a targeted resource server (see Resource Indicators)	✅ Kept	RS-defined
Permissions owned by a different resource server	❌ Dropped silently	RS-defined
Permissions not allowed on the application	❌ Rejected	Request fails with invalid_scope

Try It in ThunderID

Console

1. Open Applications or Agents in the ThunderID Console and select your client.
2. Open the Token tab to list the allowed scopes and to define custom scope-to-claim mappings.
3. Save.

Dynamic Client Registration

http

POST /oauth2/dcr/register
Content-Type: application/json

{
  "client_name": "My App",
  "redirect_uris": ["https://app.example.com/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "scope": "openid profile email roles"
}

The scopeClaims mapping is configured on the application object itself, alongside the scopes allowlist.

Related Guides

• OpenID Connect, the spec that defines standard scopes and the claims parameter
• UserInfo, receives the same claim set as the ID Token
• Resource Indicators, how scopes are filtered by targeted resource servers
• Token Formats, userAttributes selection on access and ID tokens