Claims & Scopes

IDToken implements a selective disclosure system that allows relying parties to request only the identity data they need. Users can also choose to grant a subset of the requested scopes.

How It Works

1. The relying party registers with specific allowed_scopes
2. During auth initiation, the RP requests scopes (subset of allowed)
3. The mobile app can further restrict to grantedScopes
4. The server builds the JWT with only the granted claims

Atomic Scopes

These are the individual scopes that map to specific identity claims:

Scope	Claims Included	Source
identity:name	givenName, familyName	VDS gn, fn
identity:given_name	givenName	VDS gn
identity:family_name	familyName	VDS fn
identity:date_of_birth	dateOfBirth	VDS dob
identity:nationality	nationality	VDS nat
identity:document	documentNumber	VDS doc
identity:photo	photoBase64	VDS photo
identity:trust_level	trustLevel	Enrollment trust level
identity:age_over_18	ageOver18 (boolean)	Derived from dob
identity:age_over_21	ageOver21 (boolean)	Derived from dob
identity:age_over_25	ageOver25 (boolean)	Derived from dob
identity:age_range	ageRange (bracket)	Derived from dob
identity:is_eu_citizen	isEuCitizen (boolean)	Derived from nat
identity:name_initial	nameInitial (e.g., “J. D.”)	Derived from gn, fn

Composite Scopes

Composite scopes expand into multiple atomic scopes for convenience:

Composite Scope	Expands To
identity:basic	identity:name + identity:trust_level
identity:age_verification	identity:age_over_18 + identity:name
identity:full	identity:name + identity:date_of_birth + identity:nationality + identity:document + identity:trust_level
identity:full_with_photo	identity:full + identity:photo

Derived Claims

Some claims are computed at authentication time from VDS payload data rather than stored directly:

Age Claims

Age is calculated from the dob field using year difference with month/day adjustment:

Claim	Computation
ageOver18	currentDate - dob >= 18 years
ageOver21	currentDate - dob >= 21 years
ageOver25	currentDate - dob >= 25 years
ageRange	Bracket: under_18, 18-25, 26-35, 36-50, 51+

Nationality Claims

Claim	Computation
isEuCitizen	nationality is in the 27 EU member states list

Name Claims

Claim	Computation
nameInitial	First letter of given name + ”. ” + First letter of family name + ”.”

JWT Claims Structure

The JWT idtoken claim object contains only the fields matching granted scopes:

Full claims example

{
  "iss": "https://idtoken.example.com",
  "aud": "https://services.example.com",
  "sub": "vds-token-id",
  "iat": 1705312800,
  "exp": 1705316400,
  "scope": "identity:name identity:date_of_birth identity:age_over_18",
  "idtoken": {
    "tokenId": "vds-token-id",
    "givenName": "Jean",
    "familyName": "Dupont",
    "dateOfBirth": "1990-05-15",
    "ageOver18": true,
    "trustLevel": 3
  }
}

Minimal claims example (age verification only)

{
  "iss": "https://idtoken.example.com",
  "aud": "https://services.example.com",
  "sub": "vds-token-id",
  "iat": 1705312800,
  "exp": 1705316400,
  "scope": "identity:age_over_18",
  "idtoken": {
    "tokenId": "vds-token-id",
    "ageOver18": true
  }
}