Konfigurasi bidang kustom OIDC id_token - Identity as a Service

Dokumen ini menjelaskan cara menambahkan bidang kustom ke OIDC id_token dan menyediakan contoh konfigurasinya.

Aturan bidang kustom id_token

Tipe	Nilai	Deskripsi
variable	user.username	Username.
	user.displayName	Nama tampilan.
	user.phone (deprecated)	Nomor telepon, tanpa kode negara. Variabel ini sudah tidak digunakan lagi.
	user.phoneNumber	Nomor telepon, tanpa kode negara.
	user.email	Email pengguna.
	user.status	Status pengguna. Nilai yang valid: `enabled`: Pengguna diaktifkan. `disabled`: Pengguna dinonaktifkan.
	user.primaryOrganizationalUnitId	ID unit organisasi utama pengguna.
	user.organizationalUnits	Unit organisasi tempat pengguna tergabung.
	ArrayMap(user.organizationalUnits, __item.organizationalUnitId)	ID unit organisasi tempat pengguna tergabung. Format: JSON array.
	user.groups	Grup tempat akun pengguna tergabung. Format: JSON array.
	ArrayMap(user.groups, __item.groupId)	ID grup untuk pengguna. Format: JSON array.
	ArrayMap(user.groups, __item.groupExternalId)	ID grup eksternal untuk pengguna. Format: JSON array.
	user.customFields	Bidang kustom pengguna. Format: JSON array.
	user.customFieldMap.$fieldname$.fieldValue	Nilai dari bidang kustom tertentu. Ganti $fieldname$ dengan nama bidang kustom tersebut.
constant	Nilai string tetap. Sertakan konstanta dalam tanda kutip ganda ("").
expression	Fitur lanjutan untuk menggabungkan atau mentransformasi nilai. Untuk informasi selengkapnya, lihat Advanced account field expressions.

Contoh objek pengguna:

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

Contoh ekspresi OIDC

Pada halaman application IDaaS, klik Hide advanced configuration untuk memperluas area konfigurasi lanjutan. Di bagian Extend id_token, tambahkan nama bidang kustom dan ekspresi yang sesuai ke Tabel pemetaan.

Ekspresi user.organizationalUnits mengembalikan hasil berikut:

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

Ekspresi ArrayMap(user.organizationalUnits, __item.organizationalUnitId) mengembalikan hasil berikut:
```
[
  "ou_sdfadtaaxxxxxx",
  "ou_werttxxxxxx"
]
```

Ekspresi user.groups mengembalikan hasil berikut:

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

Ekspresi ArrayMap(user.groups, __item.groupId) mengembalikan hasil berikut:
```
[
    "group_jp6al4sn4n4wjgjxxxxxx",
    "group_vavikcxewkf5h3oxxxxxx"
]
```
Ekspresi ArrayMap(user.groups, __item.groupExternalId) mengembalikan hasil berikut:
```
[
    "group_jp6al4sn4n4wjgjxxxxxx",
    "group_vavikcxewkf5h3oxxxxxx"
]
```

Ekspresi user.customFields mengembalikan hasil berikut:

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

Ekspresi user.customFieldMap.age.fieldValue mengembalikan hasil berikut:
```
18
```

Aturan untuk menulis ulang bidang kustom id_token

Aturan bidang default

Bidang default sistem tidak dapat ditulis ulang: exp, nbf, iat, iss, jti, at_hash, c_hash, nonce, sid.
Mendukung penulisan ulang bidang: sub.

Aturan bidang informasi pengguna

Kemampuan menulis ulang bidang informasi pengguna berikut dalam id_token bergantung pada scope yang diminta.

Nama bidang	Scope terkait	Kondisi tidak dapat ditulis ulang
`email`, `email_verified`	`email`	Ketika `scope` yang diminta mencakup `email` dan atribut email pengguna tidak kosong.
`phone_number`, `phone_number_verified`	`phone`	Ketika `scope` yang diminta mencakup `phone` dan atribut phoneNumber pengguna tidak kosong.
`name`, `preferred_username`, `updated_at`, `locale`	`profile`	Ketika `scope` yang diminta mencakup `profile`.
`instance_id`, `application_id`	`instance`	Ketika `scope` yang diminta mencakup `instance`.

Rekomendasi konfigurasi

Pilih scope secara hati-hati dalam konfigurasi aplikasi Anda. Scope yang diminta menentukan bidang pengguna mana yang dapat ditulis ulang.
Untuk menulis ulang bidang tertentu, pastikan Anda tidak meminta scope terkait atau bahwa atribut pengguna yang sesuai kosong.