ID Tokens

In an OIDC-based Authorization Grant flow, an RP (the client) requests specific information about the subject (user) from the issuer (authN server), and the issuer creates and provides an ID token to that RP. This token is a JSON Web Token (JWT), cryptographically signed by the issuer to guarantee its authenticity. Inside the encrypted payload are claims, which are pieces of data that the server provides to identify the subject: the subject’s name, a unique identifier, their email address, phone number, and such. Some of these claims are specified by the OIDC standard, but not every ID token will contain all claims. OIDC also defines certain scopes as granting access to particular pieces of claim data. As a JWT, an encrypted ID Token appears on the surface as just a long sequence of ASCII characters:

**ID Token \(encrypted\)**
eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiI0ZmE2ZmZlMS05NmMwLTQ3ODAtYjNkYi1kNTMwY2RjNTJh
OGIiLCJhdWQiOiJzZW5zaWNhbERldmljZUdyYW50LU9JREMtQ2xpZW50IiwiZW1haWxfdmVyaWZpZWQiOnRydWUsImtpZCI
6InJzYTEiLCJpc3MiOiJodHRwczpcL1wvc2Vuc2ljYWwtdWxtLXBkdC5tMWFtZG9jcy5pb1wvb2lkYyIsIm5hbWUiOiJQcm
ltYXJ5IFVzZXIgRGlzcGxheSBOYW1lIEhlcmUiLCJ1bG1fdXNlcl9pZCI6MTAzLCJleHAiOjE2MTA0Njg4ODAsImlhdCI6M
TYxMDQ2ODI4MCwianRpIjoiYWMzOTUxY2YtZTlhZC00MjBmLTk3OGYtYmJiOGU2Y2YzZTViIiwiZW1haWwiOiJ0Z29rY2Vu
MjAyMTAxMTJAbWFpbGluYXRvci5jb20ifQ.Hp0fDfODZ08F25HRYZmzImb-mH7-IsPHNLmWN6L7IfM791z7qDBpVRPT1SIKD
875rGG88xBGbD0QgiPqnnUmz3xz0zycokk8pmwzFYGyo2LE0ySeL4K-N2iUv4LUieDCE323KvHxKZV2QsazHivaTKGJ1aCy6
dv_90LMf0Mv0_pAD3Zyd8eaM2Plt8zUe-TtYQ-ojxrseD6lw2v1YJJpU8h1jtDKjFGLiMGUwDrV7bcUEsVZEOBZ_y1Abfhah
bADnttrmN2Kifw9HeeFkGxVkwfFuswNvBx0F0nvLPHkWqbOLdotGlQrn6fhFoW1Ibg_PUWNz3ZCXS5uO6r-cpxTWQ

However, this is actually three separate base-64 encoded blocks, each separated by the period character. The first block is a JavaScript Object Signing and Encryption (JOSE) header. When decrypted, it indicates algorithm token type:

**Header \(decrypted\)**
{ 
  "kid": "rsa1", 
  "alg": "RS256" 
}

These values indicate that the signature uses the RSA256 algorithm, and that the name of the signature key (key-ID) is “rsa1”. The second code block, when decrypted, is the payload of user claims:

**Payload \(decrypted\)**
{
  "sub": "4fa6ffe1-96c0-4780-b3db-d530cdc52a8b",
  "aud": "experienceDeviceGrant-OIDC-Client",
  "email_verified": true,
  "kid": "rsa1",
  "iss": "https://experience-ulm-pdt.m1amdocs.io/oidc",
  "name": "Primary User Display Name Here",
  "ulm_user_id": 103,
  "exp": 1610468880,
  "iat": 1610468280,
  "jti": "ac3951cf-e9ad-420f-978f-bbb8e6cf3e5b",
  "email": "jsmith@mailinator.com"
}

The fields are as follows:

Field	Description
`sub`	Subject – A unique identifier for the user. This identifier for a given user may or may not be different for each RP. This value is guaranteed not to change even if the end-user changes the properties of their account (for example, changes email address or phone number). If your application wants to store user data, it should use the `sub` string as the unique identifier.
`aud`	Audience – The relying party for whom the ID token has been issued.
`email_verified`	Standard claim that indicates whether the user’s primary email address has been verified by the issuer.
`kid`	Key-ID for the ID Token signature.
`iss`	Issuer – URL to the authentication server; in this case M1 Digital Identity Management.
`name`	Standard claim that contains the user’s stated name.
`ulm_user_id`	An M1 Digital Identity Management extension claim that indicates the user’s unique, internal ID in the Digital Identity Management data store. This claim value may not always be present.Note: ulm refers to user lifecycle management, the functional type of service delivered by Digital Identity Management.
`exp`	The expiry time of this ID token, expressed in UNIX Epoch seconds.After the expiry time, the ID token must be considered invalid. The data is stale, and any endpoint which might have accepted the ID token must refuse it.
`iat`	Issued At – The time when this ID Token was issued, as UNIX Epoch time in seconds.
`jti`	JSON Token ID – a unique identifier for this token.
`email`	Standard claim containing the user’s primary email address.
Much like access tokens, ID tokens expire because the data may become stale (for example, the subject changes their preferred phone number). An RP can obtain a replacement ID token using its refresh token, if any. Alternatively, an RP can obtain the latest claim data by calling the issuer’s `/userinfo` endpoint.

Parent topic:OAuth 2.0 and OpenID Connect

Home

Guides

APIs