Search

Documentation ID token

NB: This is a draft specification!

The ID token that ZorgDomein provides in the access token response (step 11) is a JWT (JSON web token). This is a token that consists of a header, a payload and a signature. See the OpenID token specifications for detailed documentation.

ID token header

The ID token header contains the following elements:

  • alg – fixed value: RS256. Indicates that tokens are signed using the RSA SHA-256 algorithm.
  • typ – fixed value: JWT. Indicates that this is a JSON web token.
  • kid – id of the key that was used to sign the token. This is issued by ZorgDomein upon registration of the app.

Header example:

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "zorgdomein-2019101711300530"
}

ID token payload

The payload of the ID token contains the following claims:

  • iss – Fixed value: https://zorgdomein.nl/.
  • sub – Subject identifier. A locally unique and never reassigned identifier within ZorgDomein for the user. The sub value is a case sensitive string.
  • aud – Audience(s) that this ID Token is intended for. It will contain the OAuth 2.0 client_id of the app. This is a single case sensitive string.
  • exp – Expiration time on or after which the ID Token MUST NOT be accepted for processing.
  • iat – Time at which the JWT was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
  • nonce (optional) – String value used to associate an app session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the authentication request (step 4/5) to the ID Token. If present in the ID Token, the app MUST verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request. The nonce value is a case sensitive string.
  • name (optional) – Full name of the user in displayable form including all name parts, possibly including titles and suffixes.
  • family_name (optional) – Surname(s) or last name(s) of user.
  • given_name (optional) – Given name(s) or first name(s) of the user.
  • gender (optional) – Gender of the user (female or male).
  • birthdate (optional) – Birthday of the user, represented as an YYYY-MM-DD format.
  • email (optional) – Preferred e-mail address of the user.
  • email_verified (optional) – true if the user's e-mail address has been verified; otherwise false.
  • address (optional) – Preferred postal address of the user. This value is a JSON object containing some or all of the members defined in section 5.1.1 of the OpenID specifications.
  • phone_number (optional) – Preferred telephone number of the user.
  • phone_number_verified (optional) – true if the user's phone number has been verified; otherwise false.
  • http://zorgdomein.nl/terminology/identity-claims/bsn (optional) - BSN of the user.

Payload example:

{
  "iss": "https://zorgdomein.nl",
  "sub": "1af216e4-61cc-4fa4-ba93-c1708ae5f6e0",
  "aud": "mysmartappid",
  "exp": 1571327663,
  "iat": 1571325863,
  "name": "Ingrid Testgebruiker - van ZorgDomein",
  "family_name": "Testgebruiker - van ZorgDomein",
  "given_name": "Ingrid",
  "gender": "female",
  "birthdate": "1976-10-14",
  "email": "ingrid@mail.com",
  "email_verified": true,
  "address": {
    "formatted": "Straatweg 68\r\n3621 BR\r\nBreukelen",
    "street_address": "Straatweg 68",
    "locality": "Breukelen",
    "postal_code": "3621 BR"
  },
  "phone_number": "0612345678",
  "phone_number_verified": true,
  "http://zorgdomein.nl/terminology/identity-claims/bsn": "12344321"
}

ID token signature

Following the JWT specification the signature is generated using the encoded header, the encoded payload, and both the key pair and algorithm specified in the header.