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

Nilai bidang kustom id_token dapat berupa variabel, konstanta, atau ekspresi. Masukkan nama variabel secara langsung tanpa tanda kutip. Untuk nilai konstanta, gunakan tanda kutip ganda ("").

Type	Value	Description
variable Masukkan nama variabel secara langsung tanpa tanda kutip.	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 terdaftar.
	ArrayMap(user.organizationalUnits, __item.organizationalUnitId)	ID unit organisasi tempat pengguna terdaftar. Format: JSON array.
	user.groups	Kelompok tempat akun pengguna terdaftar. Format: JSON array.
	ArrayMap(user.groups, __item.groupId)	ID kelompok pengguna. Format: JSON array.
	ArrayMap(user.groups, __item.groupExternalId)	ID eksternal kelompok pengguna. Format: JSON array.
	user.customFields	Bidang kustom pengguna. Format: JSON array.
	user.customFieldMap.$fieldname$.fieldValue	Nilai bidang kustom tertentu. Ganti $fieldname$ dengan nama bidang kustom tersebut.
constant	Nilai string tetap. Gunakan tanda kutip ganda ("") untuk mengapit konstanta.
expression	Fitur advanced untuk menggabungkan atau mentransformasi nilai. Untuk informasi selengkapnya, lihat Advanced account field expressions.

Contoh objek user:

{
  ...
  "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

Di halaman aplikasi IDaaS, klik Hide advanced configuration untuk memperluas area Konfigurasi Lanjutan. Pada bagian Extend id_token, tambahkan nama bidang kustom beserta ekspresi yang sesuai ke dalam 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.

Field name	Associated scope	Non-rewritable condition
`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 dengan cermat 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.