ID tokens

This describes the structure and semantics of the ID token returned by Mosaic upon successful user authentication.

Default claims

Default claims are returned in the ID token without being requested. These claims include standard JWT claims, such as basic user profile data, and info about their authentication.

Custom claims

Aside from the default claims, custom claims can be added to the token by request (see Requesting claims) or included automatically if they were enabled in the ID token - Pre-defined custom claims client configuration (see Manage clients). This includes user roles and permissions, additional user profile data, and custom data set by your application.

The following claims can be requested:

Requesting claims

Additional claims are requested using the claims request parameter, as defined by the OIDC standard. For example, the following claims parameter value is used to request all the user's permissions:

{
   "id_token":{
      "permissions": null
   }
}

Your custom user data can be added to the ID token by requesting the custom_data or custom_app_data claims. If their value is set to null in the request, the entire object will be returned. However, you can also include only a subset of fields in these claims by using a fields member to specify the names of the fields to return as an array.

The following example is used to request 2 fields (named field1 and field2) from the tenant-level custom data and another field (named field3) from the app-level custom data:

{
   "id_token":{
      "custom_data":{
         "fields":[
            "field1",
            "field2"
         ]
      },
      "custom_app_data":{
         "fields":[
            "field3"
         ]
      }
   }
}

Token example

Here's an ID token that includes the user's secondary emails and specific fields from the custom data:

{
  "sub": "ufnbfps4ki0qm1twdo79g",
  "tid": "6oijksdf9esfehwjkfey9",
  "email": "user@acme.com",
  "groups": [],
  "new_user": false,
  "amr": [
    "social"
  ],
  "email_verified": true,
  "secondary_emails": [
    {
      "value": "user@email.com",
      "email_verified": false
    }
  ],
  "custom_data": {
    "field1": "value1",
    "field2": "value2"
  },
  "custom_app_data": {
    "field3": "value3"
  },
  "auth_time": 1674562962,
  "at_hash": "gUWf6OJKHDKUAYDAIX7LQ",
  "aud": "pVEZaxFuQyCQ95NNhiBLe",
  "exp": 1674566580,
  "iat": 1674562980,
  "iss": "https://userid.security"
}