Specify values for extended OIDC id_token fields - Identity as a Service

Use this reference to configure the values of extended OpenID Connect (OIDC) id_token fields and understand which fields support rewriting.

Field value types

Three value types are available when filling in extended id_token fields: Variable, Constant, and Expression.

Type	Input format	Description
Variable	Enter a supported variable name (e.g., `user.email`)	Maps a user attribute directly to the field. See Supported variables for the full list.
Constant	Enclose the value in double quotation marks (e.g., `"my-app"`)	Sets a fixed string that is the same for all users.
Expression	Enter an expression using supported functions (e.g., `ArrayMap(user.groups, __item.groupId)`)	Concatenates or transforms values dynamically. See Advanced account field expressions for syntax details.

Supported variables

Variable	Description
`user.username`	The username.
`user.displayName`	The display name.
`user.phone` (expired)	The mobile phone number, excluding the country code. This variable has expired. Use `user.phoneNumber` instead.
`user.phoneNumber`	The mobile phone number, excluding the country code.
`user.email`	The email address.
`user.status`	The user's status. Valid values: `enabled`, `disabled`.
`user.primaryOrganizationalUnitId`	The ID of the primary organizational unit (OU) the user belongs to.
`user.organizationalUnits`	Full details of all OUs the user belongs to, returned as a JSON array.
`ArrayMap(user.organizationalUnits, __item.organizationalUnitId)`	The IDs of all OUs the user belongs to, returned as a JSON array.
`user.groups`	Full details of all groups the account belongs to, returned as a JSON array.
`ArrayMap(user.groups, __item.groupId)`	The IDs of all groups the account belongs to, returned as a JSON array.
`ArrayMap(user.groups, __item.groupExternalId)`	The external IDs of all groups the account belongs to, returned as a JSON array.
`user.customFields`	All custom fields for the user, returned as a JSON array of `{fieldName, fieldValue}` objects.
`user.customFieldMap.$fieldname$.fieldValue`	The value of a specific custom field. Replace $fieldname$ with the actual field name.

User object structure

The following example shows the structure of a user object, which reflects the data available through the variables above.

{
  ...
  "customFieldMap": {
    "place": {
      "fieldName": "place",
      "fieldValue": "beijing"
    },
    "age": {
      "fieldName": "age",
      "fieldValue": "18"
    }
  },
  "identityProviderUserMap": {
    "idp_m2gngriuenktdkxxxxxx": {
      "identityProviderId": "idp_m2gngriuenktdkxxxxxx",
      "identityProviderType": "ding_talk",
      "identityProviderExternalId": "corp_1234xxxxxxx",
      "identityProviderUserId": "b2ed5fc0xxxxx"
    }
  },
  "organizationalUnits": [
    {
      "organizationalUnitId": "ou_sdfadtaaxxxxxx",
      "organizationalUnitName": "AD",
      "primary": false
    },
    {
      "organizationalUnitId": "ou_werttxxxxxx",
      "organizationalUnitName": "name_002",
      "primary": true
    }
  ],
  "primaryOrganizationalUnitId": "ou_werttxxxxxx",
  "customFields": [
    {
      "fieldName": "place",
      "fieldValue": "beijing"
    },
    {
      "fieldName": "age",
      "fieldValue": "18"
    }
  ],
  "groups": [
    {
      "groupId": "group_jp6al4sn4n4wjgjxxxxxx",
      "groupName": "group1",
      "groupExternalId": "group_jp6al4sn4n4wjgjxxxxxx"
    },
    {
      "groupId": "group_vavikcxewkf5h3oxxxxxx",
      "groupName": "group2",
      "groupExternalId": "group_vavikcxewkf5h3oxxxxxx"
    }
  ],
  ...
}

Expression examples

All examples below use the user object from the previous section.

The organizationalUnits field in id_token is parsed by using the user.organizationalUnits expression, which returns the full OU details as a JSON array.

[
  {
    "organizationalUnitId": "ou_sdfadtaaxxxxxx",
    "organizationalUnitName": "AD",
    "primary": false
  },
  {
    "organizationalUnitId": "ou_werttxxxxxx",
    "organizationalUnitName": "name_002",
    "primary": true
  }
]

The organizationalUnitIds field in id_token is parsed by using the ArrayMap(user.organizationalUnits, __item.organizationalUnitId) expression, which extracts only the OU IDs.
```
[
  "ou_sdfadtaaxxxxxx",
  "ou_werttxxxxxx"
]
```

The groups field in id_token is parsed by using the user.groups expression, which returns the full group details as a JSON array.

[
  {
    "groupId": "group_jp6al4sn4n4wjgjxxxxxx",
    "groupName": "group1",
    "groupExternalId": "group_jp6al4sn4n4wjgjxxxxxx"
  },
  {
    "groupId": "group_vavikcxewkf5h3oxxxxxx",
    "groupName": "group2",
    "groupExternalId": "group_vavikcxewkf5h3oxxxxxx"
  }
]

The groupIds field in id_token is parsed by using the ArrayMap(user.groups, __item.groupId) expression, which extracts only the group IDs.
```
[
  "group_jp6al4sn4n4wjgjxxxxxx",
  "group_vavikcxewkf5h3oxxxxxx"
]
```
The groupExternalIds field in id_token is parsed by using the ArrayMap(user.groups, __item.groupExternalId) expression, which extracts only the external group IDs.
```
[
  "group_jp6al4sn4n4wjgjxxxxxx",
  "group_vavikcxewkf5h3oxxxxxx"
]
```
The customFields field in id_token is parsed by using the user.customFields expression, which returns all custom fields as a JSON array.
```
[
  {
    "fieldName": "place",
    "fieldValue": "beijing"
  },
  {
    "fieldName": "age",
    "fieldValue": "18"
  }
]
```
The age field in id_token is parsed by using the user.customFieldMap.age.fieldValue expression, which returns the value of a single custom field.
```
18
```

Field rewrite rules

Fields that cannot be rewritten

The following standard JWT and OIDC claims cannot be rewritten regardless of configuration:

exp, nbf, iat, iss, jti, at_hash, c_hash, nonce, sid

The sub claim supports rewriting.

Fields with conditional rewrite restrictions

The following user information fields can be rewritten only when the associated scope is absent or the corresponding user attribute is empty. When the condition in the Non-rewritable condition column is met, the field is locked and cannot be overridden.

Field	Associated scope	Non-rewritable condition
`email`, `email_verified`	`email`	Scope includes `email` and the user's email is not empty
`phone_number`, `phone_number_verified`	`phone`	Scope includes `phone` and the user's `phoneNumber` is not empty
`name`, `preferred_username`, `updated_at`, `locale`	`profile`	Scope includes `profile`
`instance_id`, `application_id`	`instance`	Scope includes `instance`

Configuration notes

Select scopes carefully in the user information configuration — the scopes you include determine which fields are locked from rewriting.
To rewrite a specific field, either exclude the associated scope or ensure the corresponding user attribute is empty.