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

This topic describes the rules for the values of extended OpenID Connect (OIDC) id_token fields and provides configuration examples.

Rules for filling in id_token extended fields

Type	Value	Description
Variable	user.username	The username.
	user.displayName	The display name.
	user.phone (expired)	The mobile phone number that does not include the country code and has expired.
	user.phoneNumber	The mobile phone number, excluding the country code.
	user.email	The email address.
	user.status	The status of the user. Valid values: enabled disabled
	user.primaryOrganizationalUnitId	The ID of the primary organization to which the user belongs.
	user.organizationalUnits	The information about the organization to which the user belongs.
	ArrayMap(user.organizationalUnits, __item.organizationalUnitId)	The IDs of all organizations to which the user belongs. The value is a JSON array.
	user.groups	The information about the group to which the account belongs. The value is a JSON array.
	ArrayMap(user.groups, __item.groupId)	The IDs of the groups to which the account belongs. The value is a JSON array.
	ArrayMap(user.groups, __item.groupExternalId)	The external IDs of the groups to which the account belongs. The value is a JSON array.
	user.customFields	The information about all extended fields. The value is a JSON array.
	user.customFieldMap.$fieldname$.fieldValue	The value of an extended field.
Constant	Enclose constants in double quotation marks ("").
Expression	An advanced feature. You can flexibly concatenate and change values by using expressions. For more information, see Advanced expressions for account fields.

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

Examples of OIDC expressions

The organizationalUnits field in id_token is parsed by using the user.organizationalUnits expression.

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

The groups field in id_token is parsed by using the user.groups expression.

[
  {
    "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.
```
[
    "group_jp6al4sn4n4wjgjxxxxxx",
    "group_vavikcxewkf5h3oxxxxxx"
]
```
The groupExternalIds field in id_token is parsed by using the ArrayMap(user.groups, __item.groupExternalId) expression.
```
[
    "group_jp6al4sn4n4wjgjxxxxxx",
    "group_vavikcxewkf5h3oxxxxxx"
]
```

The customFields field in id_token is parsed by using the user.customFields expression.

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

The age field in id_token is parsed by using the user.customFieldMap.age.fieldValue expression.
```
18
```

Rules for rewriting id_token extended fields

Default field rules

Default fields do not support rewriting: exp, nbf, iat, iss, jti, at_hash, c_hash, nonce, sid.
Fields that support rewriting: sub.

User information field rules

The following fields in the user id_token can be rewritten based on scope:

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

Configuration recommendations

Exercise caution when selecting scopes in the user information configuration because this will affect which user fields can be rewritten.
To rewrite specific fields, you must ensure that the corresponding scope is not included or the corresponding user field is empty.