OIDC id_token custom field configuration - Identity as a Service

id_token custom field rules

Type	Value	Description
variable	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 user's email.
	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	The organizational units to which the user belongs.
	ArrayMap(user.organizationalUnits, __item.organizationalUnitId)	The IDs of the organizational units to which the user belongs. Format: JSON array.
	user.groups	The groups to which the user account belongs. Format: JSON array.
	ArrayMap(user.groups, __item.groupId)	The group IDs for the user. Format: JSON array.
	ArrayMap(user.groups, __item.groupExternalId)	The external group IDs for the user. Format: JSON array.
	user.customFields	The user's custom fields. Format: JSON array.
	user.customFieldMap.$fieldname$.fieldValue	The value of a specific custom field. Replace $fieldname$ with the name of the custom field.
constant	A fixed string value. Enclose the constant in double quotation marks ("").
expression	An advanced feature for concatenating or transforming values. For more information, see Advanced account field expressions.

Example 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 application page, click Hide advanced configuration to expand the advanced configuration area. In the Extend id_token section, add custom field names and their corresponding expressions to the mapping table.

The expression user.organizationalUnits returns the following:

[
  {
    "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:
```
[
  "ou_sdfadtaaxxxxxx",
  "ou_werttxxxxxx"
]
```

The expression user.groups returns the following:

[
  {
    "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:
```
[
    "group_jp6al4sn4n4wjgjxxxxxx",
    "group_vavikcxewkf5h3oxxxxxx"
]
```
The expression ArrayMap(user.groups, __item.groupExternalId) returns the following:
```
[
    "group_jp6al4sn4n4wjgjxxxxxx",
    "group_vavikcxewkf5h3oxxxxxx"
]
```

The expression user.customFields returns the following:

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

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

Rules for rewriting id_token custom fields

Default field rules

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

User information field rules

Whether you can rewrite the following user information fields in the id_token depends on the requested scope.

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

Configuration recommendations

Select scopes carefully in your application's configuration. The scopes you request determine which user fields can be rewritten.
To rewrite a specific field, ensure that you do not request the associated scope or that the corresponding user attribute is empty.