Adding claims to an ID token

Preface


This article explains how to add arbitrary claims to an ID token.

How to add claims to an ID token


Authlete's /auth/authorization/issue API is the method for adding claims. In this article, the following claims are to be added.
Item
Value
"name"
"Test User"
"email"
"testuser01@example.com"
"email_verified"
true


claims is the paramater to add claims. The request will be constructed as follows. (folded for readability)

curl -s -X POST https://api.authlete.com/api/auth/authorization/issue \
-u '<API Key>:<API Secret>' \
-H 'Content-Type: application/json' \
-d '{ "ticket": "<Ticket>", "subject": "testuser01",
 "claims": "{\"name\": \"Test User\",
  \"email\": \"testuser01@example.com\",
  \"email_verified\": true}"
 }'

Authlete will issue an ID token including the claims in accordance with the request above. The payload part of the ID token is as follows:

{
  "name": "Test User",
  "email": "testuser01@example.com",
  "email_verified": true,
  "iss": "https://as.example.com",
  "sub": "testuser01",
  "aud": [
    "12898884596863"
  ],
  "exp": 1559137301,
  "iat": 1559050901,
  "nonce": "n-0S6_WzA2Mj"
}

How to specify a custom value to "sub" claim


By default, Authlete uses the value of the "subject" parameter for "sub" claim in an ID token. If you want to specify your own value for this claim, use the special "sub" parameter instead of the "claims" parameter when making an API request. An example is shown below:

curl -s -X POST https://api.authlete.com/api/auth/authorization/issue \
-u '<API Key>:<API Secret>' \
-H 'Content-Type: application/json' \
-d '{ "ticket": "<Ticket>", "subject": "testuser01",
 "claims": "{\"name\": \"Test User\",
  \"email\": \"testuser01@example.com\",
  \"email_verified\": true}",
  "sub": "1234567890"
 }'

The resulted ID token would include the custom "sub" value as follows:

{
  "name": "Test User",
  "email": "testuser01@example.com",
  "email_verified": true,
  "iss": "https://as.example.com",
  "sub": "1234567890",
  "aud": [
    "126863743267133" ],
  "exp": 1688804473,
  "iat": 1688718073,
  "nonce": "n-0S6_WzA2Mj"
}


How did we do with this article?