How do I specify OIDC id_token custom field values? - Identity as a Service

This topic describes the rules for specifying OIDC id_token custom field values in the OIDC standard protocol and provides configuration examples.

id_token custom field rules

The value of an id_token custom field is one of three types: variable, constant, or expression. To specify a variable, enter the variable name directly without quotation marks. To specify a constant, enclose the constant value in double quotation marks ("").

Type	Value	Description
Variable Enter the variable name directly, without quotation marks.	user.username	The username.
	user.displayName	The display name.
	user.phone (deprecated)	The phone number, without the country code. This variable is deprecated.
	user.phoneNumber	The phone number, without the country code.
	user.email	The email address.
	user.status	The user status. Valid values: enabled: The user is enabled. disabled: The user is disabled.
	user.primaryOrganizationalUnitId	The ID of the user's primary organizational unit.
	user.organizationalUnits	All information about the organizational units to which the user belongs.
	ArrayMap(user.organizationalUnits, __item.organizationalUnitId)	The IDs of all organizational units to which the user belongs. Format: JSON array.
	user.groups	The groups to which the account belongs, including all group information. Format: JSON array.
	ArrayMap(user.groups, __item.groupId)	The IDs of the groups to which the account belongs. Format: JSON array.
	ArrayMap(user.groups, __item.groupExternalId)	The external IDs of the groups to which the account belongs. Format: JSON array.
	user.customFields	All custom field information. Format: JSON array.
	user.customFieldMap.$fieldname$.fieldValue	The value of a specific custom field.
Constant	Enclose the constant value in double quotation marks (""). For example, enter "example_value".
Expression	An advanced feature that lets you flexibly concatenate and transform values. For details, see Advanced account field expressions.

Example input (user object):

{
  ...
  "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"
        }
    ],
  ...
}

OIDC expression examples

On the IDaaS Applications page, click Hide advanced configuration to expand the advanced configuration area. In the Extend id_token area, add custom field names and their expressions to the two-column mapping table.

The expression user.organizationalUnits returns the following value in the id_token:

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

The expression ArrayMap(user.organizationalUnits, __item.organizationalUnitId) returns the following value in the id_token:
```
[
  "ou_sdfadtaaxxxxxx",
  "ou_werttxxxxxx"
]
```

The expression user.groups returns the following value in the id_token:

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

The expression ArrayMap(user.groups, __item.groupId) returns the following value in the id_token:
```
[
    "group_jp6al4sn4n4wjgjxxxxxx",
    "group_vavikcxewkf5h3oxxxxxx"
]
```
The expression ArrayMap(user.groups, __item.groupExternalId) returns the following value in the id_token:
```
[
    "group_jp6al4sn4n4wjgjxxxxxx",
    "group_vavikcxewkf5h3oxxxxxx"
]
```

The expression user.customFields returns the following value in the id_token:

[
    {
      "fieldName": "place",
      "fieldValue": "beijing"
    },
    {
      "fieldName": "age",
      "fieldValue": "18"
    }
]

The expression user.customFieldMap.age.fieldValue returns the following value in the id_token:
```
18
```

id_token custom field rewrite rules

Default field rules

System default fields cannot be rewritten: exp, nbf, iat, iss, jti, at_hash, c_hash, nonce, sid.
Rewritable field: sub.

User information field rules

Whether the following fields in the user id_token can be rewritten depends on the requested scope:

Field name	Associated scope	Condition that prevents rewriting
email, email_verified	email	The requested scope includes email and the user's email is not empty.
phone_number, phone_number_verified	phone	The requested scope includes phone and the user's phoneNumber is not empty.
name, preferred_username, updated_at, locale	profile	The requested scope includes profile.
instance_id, application_id	instance	The requested scope includes instance.

Configuration recommendations

In the user information scope configuration, select scopes carefully, because they affect which user fields can be rewritten.
To rewrite a specific field, ensure that the associated scope is not requested or that the corresponding user field is empty.