Menyesuaikan klaim yang dikeluarkan dalam token web JSON (JWT) untuk aplikasi perusahaan

platform identitas Microsoft mendukung akses menyeluruh (SSO) dengan sebagian besar aplikasi yang telah diintegrasikan sebelumnya di galeri aplikasi Microsoft Entra dan aplikasi kustom. Ketika pengguna mengautentikasi ke aplikasi melalui platform identitas Microsoft menggunakan protokol OIDC, pengguna mengirim token ke aplikasi. Aplikasi memvalidasi dan menggunakan token untuk memasukkan pengguna alih-alih meminta nama pengguna dan kata sandi.

Token Web JSON (JWT) yang digunakan oleh aplikasi OIDC dan OAuth ini berisi potongan informasi tentang pengguna yang dikenal sebagai klaim. Klaim adalah informasi yang menyatakan penyedia identitas tentang pengguna di dalam token yang mereka terbitkan untuk pengguna tersebut. Dalam respons OIDC, data klaim biasanya terkandung dalam Token ID yang dikeluarkan oleh IdP dalam bentuk JWT.

Menampilkan atau mengedit klaim

Tip

Langkah-langkah dalam artikel ini mungkin sedikit berbeda berdasarkan portal tempat Anda memulai.

Klaim JWT opsional dapat dikonfigurasi dalam pendaftaran aplikasi asli, namun mereka juga dapat dikonfigurasi di aplikasi perusahaan. Untuk melihat atau mengedit klaim yang dikeluarkan di JWT ke aplikasi:

1. Masuk ke pusat admin Microsoft Entra sebagai setidaknya Administrator Aplikasi Cloud.
2. Telusuri aplikasi Identity>Applications>Enterprise>Semua aplikasi.
3. Pilih aplikasi, pilih Akses menyeluruh di menu sebelah kiri, lalu pilih Edit di bagian Atribut & Klaim .

Aplikasi mungkin memerlukan penyesuaian klaim karena berbagai alasan. Misalnya, ketika aplikasi memerlukan serangkaian URI klaim atau nilai klaim yang berbeda. Dengan menggunakan bagian Atribut & Klaim , Anda dapat menambahkan atau menghapus klaim untuk aplikasi Anda. Anda juga dapat membuat klaim kustom yang khusus untuk aplikasi berdasarkan kasus penggunaan.

Langkah-langkah berikut menjelaskan cara menetapkan nilai konstanta:

1. Pilih klaim yang ingin Anda ubah.
2. Masukkan nilai konstanta tanpa tanda kutip di atribut Sumber sesuai organisasi Anda, lalu pilih Simpan.

Gambaran umum Atribut menampilkan nilai konstanta.

Transformasi klaim khusus

Anda dapat menggunakan fungsi transformasi klaim khusus berikut.

Fungsi	Deskripsi
ExtractMailPrefix()	Menghapus akhiran domain dari alamat email atau nama prinsipal pengguna. Fungsi ini hanya mengekstrak bagian pertama dari nama pengguna. Misalnya, joe_smith daripada joe_smith@contoso.com.
ToLower()	Mengonversi karakter atribut yang dipilih menjadi karakter huruf kecil.
ToUpper()	Mengonversi karakter atribut yang dipilih menjadi karakter huruf besar.

Menambahkan klaim khusus aplikasi

Untuk menambahkan aplikasi-klaim khusus:

1. Pada Klaim & Atribut Pengguna, pilih Menambahkan klaim baru untuk membuka halaman Kelola klaim pengguna.
2. Masukkan nama klaim. Nilai tidak benar-benar perlu mengikuti pola URI. Jika Anda memerlukan pola URI, Anda dapat meletakkannya di bidang Namespace .
3. Pilih Sumber tempat klaim akan mengambil nilainya. Anda dapat memilih atribut pengguna dari dropdown atribut source atau menerapkan transformasi ke atribut pengguna sebelum memancarkannya sebagai klaim.

Transformasi klaim

Untuk menerapkan transformasi ke atribut pengguna:

1. Di Kelola klaim, pilih Transformasi sebagai sumber klaim untuk membuka halaman Kelola transformasi.
2. Pilih fungsi dari turun bawah transformasi. Bergantung pada fungsi yang dipilih, berikan parameter dan nilai konstanta untuk dievaluasi dalam transformasi.
3. Perlakukan sumber sebagai multinilai menunjukkan apakah transformasi diterapkan ke semua nilai atau hanya yang pertama. Secara default, elemen pertama dalam klaim multinilai diterapkan transformasi. Saat Anda mencentang kotak ini, kotak ini memastikan kotak ini diterapkan ke semua. Kotak centang ini hanya diaktifkan untuk atribut multinilai. Contohnya,user.proxyaddresses.
4. Untuk menerapkan beberapa transformasi, pilih Tambahkan transformasi. Anda dapat menerapkan maksimal dua transformasi untuk satu klaim. Misalnya, Anda dapat terlebih dahulu mengekstrak awalan email dari user.mail. Kemudian, buat string huruf besar.

Anda dapat menggunakan fungsi berikut untuk mengubah klaim.

Fungsi	Deskripsi
ExtractMailPrefix()	Menghapus akhiran domain dari alamat email atau nama prinsipal pengguna. Fungsi ini hanya mengekstrak bagian pertama dari nama pengguna. Misalnya, joe_smith daripada joe_smith@contoso.com.
Join()	Membuat nilai baru dengan menggabungkan dua atribut. Secara opsional, Anda dapat menggunakan pemisah di antara kedua atribut. Untuk transformasi klaim NameID, fungsi Gabung() memiliki perilaku spesifik ketika input transformasi memiliki bagian domain. Ini menghapus bagian domain dari input sebelum menggabungkannya dengan pemisah dan parameter yang dipilih. Misalnya, jika input transformasi adalah joe_smith@contoso.com dan pemisah adalah dan parameternya adalah @ fabrikam.com, kombinasi input ini menghasilkan joe_smith@fabrikam.com.
ToLowercase()	Mengonversi karakter atribut yang dipilih menjadi karakter huruf kecil.
ToUppercase()	Mengonversi karakter atribut yang dipilih menjadi karakter huruf besar.
Contains()	Mengeluarkan atribut atau konstanta jika input cocok dengan nilai yang ditentukan. Jika tidak, Anda dapat menentukan output lain jika tidak ada kecocokan. Misalnya, jika Anda ingin mengeluarkan klaim di mana nilainya adalah alamat email pengguna jika berisi domain @contoso.com, jika tidak, Anda ingin menghasilkan nama utama pengguna. Untuk melakukan fungsi ini, Anda mengonfigurasi nilai berikut: Parameter 1(input): user.email Nilai: "@contoso.com" Parameter 2 (output): user.email Parameter 3 (output jika tidak ada kecocokan): user.userprincipalname
EndWith()	Mengeluarkan atribut atau konstanta jika input diakhiri dengan nilai yang ditentukan. Jika tidak, Anda dapat menentukan output lain jika tidak ada kecocokan. Misalnya, jika Anda ingin mengeluarkan klaim di mana nilainya adalah ID karyawan pengguna jika ID karyawan berakhir dengan 000, jika tidak, Anda ingin menghasilkan atribut ekstensi. Untuk melakukan fungsi ini, Anda mengonfigurasi nilai berikut: Parameter 1(input): user.employeeid Nilai: "000" Parameter 2 (output): user.employeeid Parameter 3 (output jika tidak ada kecocokan): user.extensionattribute1
StartWith()	Mengeluarkan atribut atau konstanta jika input dimulai dengan nilai yang ditentukan. Jika tidak, Anda dapat menentukan output lain jika tidak ada kecocokan. Misalnya, jika Anda ingin mengeluarkan klaim di mana nilainya adalah ID karyawan pengguna jika negara/wilayah dimulai dengan US, jika tidak, Anda ingin menghasilkan atribut ekstensi. Untuk melakukan fungsi ini, Anda mengonfigurasi nilai berikut: Parameter 1(input): user.negara Nilai: "US" Parameter 2 (output): user.employeeid Parameter 3 (output jika tidak ada kecocokan): user.extensionattribute1
Ekstrak() - Setelah pencocokan	Mengembalikan substring setelah cocok dengan nilai yang ditentukan. Misalnya, jika nilai input adalah Finance_BSimon, nilai yang cocok adalah Finance_, maka output klaim adalah BSimon.
Extract() - Sebelum pencocokan	Mengembalikan substring sampai cocok dengan nilai yang ditentukan. Misalnya, jika nilai input adalah BSimon_US, nilai yang cocok adalah _US, maka output klaim adalah BSimon.
Ekstrak() - Antara pencocokan	Mengembalikan substring sampai cocok dengan nilai yang ditentukan. Misalnya, jika nilai input adalah Finance_BSimon_US, nilai pencocokan pertama adalah Finance_, nilai pencocokan kedua adalah _US, maka output klaim adalah BSimon.
ExtractAlpha() - Awalan	Mengembalikan bagian alfabet awalan dari string. Misalnya, jika nilai input adalah BSimon_123, maka akan mengembalikan BSimon.
ExtractAlpha() - Akhiran	Mengembalikan bagian akhiran alfabet dari string. Misalnya, jika nilai input adalah 123_Simon, maka akan mengembalikan Simon.
ExtractNumeric() - Awalan	Mengembalikan bagian numerik awalan dari string. Misalnya, jika nilai input adalah 123_BSimon, maka akan mengembalikan 123.
ExtractNumeric() - Akhiran	Mengembalikan bagian numerik akhiran dari string. Misalnya, jika nilai input adalah BSimon_123, maka akan mengembalikan 123.
IfEmpty()	Mengeluarkan atribut atau konstanta jika input null atau kosong. Misalnya, jika Anda ingin menghasilkan atribut yang disimpan dalam atribut ekstensi jika ID karyawan untuk pengguna tertentu kosong. Untuk melakukan fungsi ini, konfigurasikan nilai berikut: Parameter 1(input): user.employeeid Parameter 2 (output): user.extensionattribute1 Parameter 3 (output jika tidak ada kecocokan): user.employeeid
IfNotEmpty()	Mengeluarkan atribut atau konstanta jika input tidak null atau kosong. Misalnya, jika Anda ingin menghasilkan atribut yang disimpan dalam atribut ekstensi jika ID karyawan untuk pengguna tertentu tidak kosong. Untuk melakukan fungsi ini, Anda mengonfigurasi nilai berikut: Parameter 1(input): user.employeeid Parameter 2 (output): user.extensionattribute1
Substring() - Panjang Tetap	Mengekstrak bagian dari jenis klaim string, dimulai pada karakter pada posisi yang ditentukan, dan mengembalikan jumlah karakter yang ditentukan. SourceClaim - Sumber klaim transformasi yang harus dijalankan. StartIndex - Posisi karakter awal berbasis nol dari substring dalam instans ini. Panjang - Panjang dalam karakter substring. Contohnya: sourceClaim - PleaseExtractThisNow StartIndex - 6 Panjang - 11 Output: ExtractThis
Substring() - EndOfString	Mengekstrak bagian dari jenis klaim string, dimulai dari karakter pada posisi yang ditentukan, dan mengembalikan sisa klaim dari indeks awal yang ditentukan. SourceClaim - Sumber klaim transformasi. StartIndex - Posisi karakter awal berbasis nol dari substring dalam instans ini. Contohnya: sourceClaim - PleaseExtractThisNow StartIndex - 6 Output: ExtractThisNow
RegexReplace()	Transformasi RegexReplace() menerima sebagai parameter input: - Parameter 1: satu atribut pengguna sebagai input regex - Opsi untuk memercayai sumber sebagai multinilai - Pola regex - Pola penggantian. Pola penggantian mungkin berisi format teks statis bersama dengan referensi yang menunjuk ke grup output regex dan parameter input lainnya.

Jika Anda memerlukan transformasi lain, kirimkan ide Anda di forum umpan balik di ID Microsoft Entra di bawah kategori aplikasi SaaS.

Transformasi klaim berbasis regex

Gambar berikut menunjukkan contoh tingkat transformasi pertama:

Tabel berikut ini menyediakan informasi tentang tingkat transformasi pertama. Tindakan yang tercantum dalam tabel sesuai dengan label di gambar sebelumnya. Pilih Edit untuk membuka bilah transformasi klaim.

Perbuatan	Bidang	Deskripsi
1	Transformation	Pilih opsi RegexReplace() dari opsi Transformasi untuk menggunakan metode transformasi klaim berbasis regex untuk transformasi klaim.
2	Parameter 1	Input untuk transformasi ekspresi reguler. Misalnya, user.mail yang memiliki alamat email pengguna seperti admin@fabrikam.com.
3	Treat source as multivalued	Sejunlah atribut pengguna input dapat berupa atribut pengguna multinilai. Jika atribut pengguna yang dipilih mendukung beberapa nilai dan pengguna ingin menggunakan beberapa nilai untuk transformasi, mereka perlu memilih Perlakukan sumber sebagai multinilai. Jika dipilih, semua nilai digunakan untuk kecocokan regex, jika tidak, hanya nilai pertama yang digunakan.
4	Regex pattern	Ekspresi reguler yang dievaluasi terhadap nilai atribut pengguna yang dipilih sebagai Parameter 1. Misalnya, ekspresi reguler untuk mengekstrak alias pengguna dari alamat email pengguna diwakili sebagai (?'domain'^.*?)(?i)(\@fabrikam\.com)$.
5	Add additional parameter	Lebih dari satu atribut pengguna dapat digunakan untuk transformasi. Nilai atribut kemudian akan digabungkan dengan output transformasi regex. Hingga lima parameter lagi didukung.
6	Replacement pattern	Pola penggantian adalah templat teks, yang berisi tempat penampung untuk hasil regex. Semua nama grup harus diletakkan di dalam kurung kurawal, seperti {group-name}. Katakanlah administrasi ingin menggunakan alias pengguna dengan beberapa nama domain lain, misalnya xyz.com dan menggabungkan nama negara dengannya. Dalam hal ini, pola penggantian adalah {country}.{domain}@xyz.com, di mana {country} adalah nilai parameter input dan {domain} merupakan output grup dari evaluasi ekspresi reguler. Dalam kasus seperti itu, hasil yang diharapkan adalah US.swmal@xyz.com.

Gambar berikut menunjukkan contoh tingkat transformasi kedua:

Tabel berikut ini menyediakan informasi tentang tingkat transformasi kedua. Tindakan yang tercantum dalam tabel sesuai dengan label di gambar sebelumnya.

Perbuatan	Bidang	Deskripsi
1	Transformation	Transformasi klaim berbasis regex tidak terbatas pada transformasi pertama dan juga dapat digunakan sebagai transformasi tingkat kedua. Metode transformasi lainnya dapat digunakan sebagai transformasi pertama.
2	Parameter 1	Jika RegexReplace() dipilih sebagai transformasi tingkat kedua, output transformasi tingkat pertama digunakan sebagai input untuk transformasi tingkat kedua. Untuk menerapkan transformasi, ekspresi regex tingkat kedua harus cocok dengan output transformasi pertama.
3	Regex pattern	Pola regex adalah ekspresi reguler untuk transformasi tingkat kedua.
4	Parameter input	Input atribut pengguna untuk transformasi tingkat kedua.
5	Parameter input	Administrator dapat menghapus parameter input yang dipilih jika mereka tidak membutuhkannya lagi.
6	Replacement pattern	Pola pengganti adalah templat teks, yang berisi tempat penampung untuk nama grup hasil regex, nama grup parameter input, dan nilai teks statis. Semua nama grup harus dibungkus di dalam kurung kurawal seperti {group-name}. Katakanlah administrasi ingin menggunakan alias pengguna dengan beberapa nama domain lain, misalnya xyz.com dan menggabungkan nama negara dengannya. Dalam hal ini, pola penggantian adalah {country}.{domain}@xyz.com, di mana {country} adalah nilai parameter input dan {domain} merupakan output grup dari evaluasi ekspresi reguler. Dalam kasus seperti itu, hasil yang diharapkan adalah US.swmal@xyz.com.
7	Test transformation	Transformasi RegexReplace() dievaluasi hanya jika nilai atribut pengguna yang dipilih untuk Parameter 1 cocok dengan ekspresi reguler yang disediakan di kotak teks pola Regex. Jika tidak cocok, nilai klaim default ditambahkan ke token. Untuk memvalidasi regex terhadap nilai parameter input, pengalaman pengujian tersedia dalam bilah transformasi. Pengalaman pengujian ini beroperasi pada nilai dummy saja. Ketika lebih banyak parameter input digunakan, nama parameter ditambahkan ke hasil pengujian alih-alih nilai aktual. Untuk mengakses bagian pengujian, pilih Uji transformasi.

Gambar berikut menunjukkan contoh pengujian transformasi:

Tabel berikut ini menyediakan informasi tentang menguji transformasi. Tindakan yang tercantum dalam tabel sesuai dengan label di gambar sebelumnya.

Perbuatan	Bidang	Deskripsi
1	Test transformation	Pilih tombol tutup atau (X) untuk menyembunyikan bagian pengujian dan merender kembali tombol Transformasi uji lagi pada bilah.
2	Test regex input	Menerima input yang digunakan untuk evaluasi pengujian ekspresi reguler. Jika transformasi klaim berbasis regex dikonfigurasi sebagai transformasi tingkat kedua, berikan nilai yang merupakan output yang diharapkan dari transformasi pertama.
3	Run test	Setelah input regex pengujian disediakan dan pola Regex, Pola penggantian dan Parameter input dikonfigurasi, ekspresi dapat dievaluasi dengan memilih Jalankan pengujian.
4	Test transformation result	Jika evaluasi berhasil, output transformasi pengujian dirender terhadap label Hasil transformasi pengujian.
5	Remove transformation	Transformasi tingkat kedua dapat dihapus dengan memilih Hapus transformasi.
6	Specify output if no match	Saat nilai input regex dikonfigurasi terhadap Parameter 1 yang tidak cocok dengan ekspresi Reguler, transformasi dilewati. Dalam kasus seperti itu, atribut pengguna alternatif dapat dikonfigurasi, yang ditambahkan ke token untuk klaim dengan memeriksa Tentukan output jika tidak ada kecocokan.
7	Parameter 3	Jika atribut pengguna alternatif perlu dikembalikan saat tidak ada kecocokan dan Tentukan output jika tidak ada kecocokan yang dicentang, atribut pengguna alternatif dapat dipilih menggunakan dropdown. Dropdown ini tersedia terhadap Parameter 3 (output jika tidak ada kecocokan).
8	Summary	Di bagian bawah bilah, ringkasan lengkap format ditampilkan yang menjelaskan arti transformasi dalam teks sederhana.
9	Add	Setelah pengaturan konfigurasi untuk transformasi diverifikasi, itu dapat disimpan ke kebijakan klaim dengan memilih Tambahkan. Pilih Simpan pada bilah Kelola Klaim untuk menyimpan perubahan.

Transformasi RegexReplace() juga tersedia untuk transformasi klaim grup.

Validasi transformasi

Pesan menyediakan informasi selengkapnya saat kondisi berikut terjadi setelah memilih Tambahkan atau Jalankan pengujian:

• Parameter input dengan atribut pengguna duplikat digunakan.
• Parameter input yang tidak digunakan ditemukan. Parameter input yang ditentukan harus memiliki penggunaan masing-masing ke dalam teks pola Penggantian.
• Input regex pengujian yang disediakan tidak cocok dengan ekspresi reguler yang disediakan.
• Tidak ada sumber untuk grup dalam pola pengganti yang ditemukan.

Memancarkan klaim berdasarkan kondisi

Anda dapat menentukan sumber klaim berdasarkan jenis pengguna dan grup tempat pengguna berada.

Tipe pengguna dapat berupa:

• Apa pun - Semua pengguna diizinkan untuk mengakses aplikasi.
• Anggota: Anggota asli penyewa
• Semua tamu: Pengguna dipindahkan dari organisasi eksternal dengan atau tanpa ID Microsoft Entra.
• Tamu Microsoft Entra: Pengguna tamu milik organisasi lain menggunakan ID Microsoft Entra.
• Tamu eksternal: Pengguna tamu milik organisasi eksternal yang tidak memiliki ID Microsoft Entra.

Salah satu skenario di mana jenis pengguna sangat membantu adalah ketika sumber klaim berbeda untuk tamu dan karyawan yang mengakses aplikasi. Anda dapat menentukan bahwa jika pengguna adalah karyawan, dapatkan NameID dari user.email. Jika pengguna adalah tamu, maka NameID berasal dari user.extensionattribute1.

Untuk menambahkan kondisi klaim:

1. Di Kelola klaim, perluas kondisi Klaim.
2. Pilih jenis pengguna.
3. Pilih grup tempat pengguna berada. Anda dapat memilih hingga 50 grup unik di semua klaim untuk aplikasi tertentu.
4. Pilih Sumber tempat klaim akan mengambil nilainya. Anda dapat memilih atribut pengguna dari dropdown atribut source atau menerapkan transformasi ke atribut pengguna sebelum memancarkannya sebagai klaim.

Urutan di mana Anda menambahkan kondisi adalah penting. Microsoft Entra pertama-tama mengevaluasi semua kondisi dengan sumber Attribute dan kemudian mengevaluasi semua kondisi dengan sumber Transformation untuk memutuskan nilai mana yang akan dikeluarkan dalam klaim. ID Microsoft Entra mengevaluasi kondisi dengan sumber yang sama dari atas ke bawah. Klaim memancarkan nilai terakhir yang cocok dengan ekspresi dalam klaim. Transformasi seperti IsNotEmpty dan Contains bertindak seperti pembatasan.

Misalnya, Britta Simon adalah pengguna tamu di penyewa Contoso. Britta milik organisasi lain yang juga menggunakan ID Microsoft Entra. Mengingat konfigurasi berikut untuk aplikasi Fabrikam, ketika Britta mencoba masuk ke Fabrikam, platform identitas Microsoft mengevaluasi kondisi.

Pertama, platform identitas Microsoft memverifikasi apakah jenis pengguna Britta adalah Semua tamu. Karena jenisnya adalah Semua tamu, platform identitas Microsoft menetapkan sumber untuk klaim ke user.extensionattribute1. Kedua, platform identitas Microsoft memverifikasi apakah jenis pengguna Britta adalah tamu Microsoft Entra. Karena jenisnya adalah Semua tamu, platform identitas Microsoft menetapkan sumber untuk klaim ke user.mail. Akhirnya, klaim dipancarkan dengan nilai user.mail untuk Britta.

Sebagai contoh lain, pertimbangkan kapan Britta Simon mencoba masuk menggunakan konfigurasi berikut. Microsoft Entra terlebih dahulu mengevaluasi semua kondisi dengan sumber Attribute. Sumber untuk klaim adalah user.mail ketika jenis pengguna Britta adalah tamu Microsoft Entra. Selanjutnya, MICROSOFT Entra ID mengevaluasi transformasi. Karena Britta adalah tamu, user.extensionattribute1 adalah sumber baru untuk klaim tersebut. Karena Britta berada di tamu Microsoft Entra, user.othermail adalah sumber baru untuk klaim ini. Akhirnya, klaim dipancarkan dengan nilai user.othermail untuk Britta.

Sebagai contoh terakhir, pertimbangkan apa yang terjadi jika Britta tidak user.othermail memiliki konfigurasi atau kosong. Klaim kembali user.extensionattribute1 mengabaikan entri kondisi dalam kedua kasus.

Pertimbangan keamanan

Aplikasi yang menerima token mengandalkan nilai klaim yang tidak dapat diubah. Saat Anda memodifikasi konten token melalui kustomisasi klaim, asumsi ini mungkin tidak lagi benar. Aplikasi harus secara eksplisit mengakui bahwa token telah dimodifikasi untuk melindungi diri mereka dari kustomisasi yang dibuat oleh aktor jahat. Lindungi dari kustomisasi yang tidak pantas dengan salah satu cara berikut:

• Mengonfigurasi kunci penandatanganan kustom
• perbarui manifes aplikasi untuk menerima klaim yang dipetakan.

Tanpa ini, MICROSOFT Entra ID mengembalikan kode kesalahan AADSTS50146.

Mengonfigurasi kunci penandatanganan kustom

Untuk aplikasi multipenyewa, kunci penandatanganan kustom harus digunakan. Jangan atur acceptMappedClaims dalam manifes aplikasi. Saat menyiapkan aplikasi di portal Azure, Anda mendapatkan objek pendaftaran aplikasi dan perwakilan layanan di penyewa Anda. Aplikasi tersebut menggunakan kunci masuk global Azure, yang tidak dapat digunakan untuk menyesuaikan klaim dalam token. Untuk mendapatkan klaim kustom dalam token, buat kunci masuk kustom dari sertifikat dan tambahkan ke perwakilan layanan. Untuk kepentingan pengujian, Anda dapat menggunakan sertifikat yang ditandatangani sendiri. Setelah Mengonfigurasi kunci penandatanganan kustom, kode aplikasi Anda perlu memvalidasi kunci penandatanganan token.

Tambahkan informasi berikut ke perwakilan layanan:

• Kunci privat (sebagai info masuk kunci)
• Kata sandi (sebagai info masuk kata sandi)
• Kunci umum (sebagai info masuk kunci)

Ekstrak base-64 kunci privat dan publik yang dikodekan dari ekspor file PFX sertifikat Anda. Pastikan bahwa keyId untuk keyCredential digunakan untuk "Menandatangani" kecocokan dengan keyId dari passwordCredential. Anda dapat membuat customkeyIdentifier dengan mendapatkan hash dari thumbprint sertifikat.

Minta

Catatan

Pertama-tama nonaktifkan konfigurasi kunci perwakilan layanan apa pun pada aplikasi yang baru dibuat dari bilah pendaftaran aplikasi pusat admin Microsoft Entra sebelum mencoba melakukan PATCH pada perwakilan layanan, menghasilkan 400 Permintaan Buruk.

Contoh berikut menunjukkan format permintaan HTTP PATCH untuk menambahkan kunci penandatanganan kustom ke perwakilan layanan. Nilai "kunci" di properti keyCredentials diperpendek untuk keterbacaan. Nilainya adalah base-64 yang dikodekan. Untuk kunci privat, penggunaan properti adalah Sign. Untuk kunci publik, penggunaan properti adalah Verify.

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/aaaaaaaa-bbbb-cccc-1111-222222222222

Content-type: servicePrincipals/json
Authorization: Bearer {token}

{
    "keyCredentials":[
        {
            "customKeyIdentifier": "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=", 
            "endDateTime": "2021-04-22T22:10:13Z",
            "keyId": "aaaaaaaa-0b0b-1c1c-2d2d-333333333333",
            "startDateTime": "2020-04-22T21:50:13Z",
            "type": "X509CertAndPassword",
            "usage": "Sign",
            "key":"cD2eF3gH4iJ5kL6mN7-oP8qR9sT==",
            "displayName": "CN=contoso"
        },
        {
            "customKeyIdentifier": "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=",
            "endDateTime": "2021-04-22T22:10:13Z",
            "keyId": "bbbbbbbb-1c1c-2d2d-3e3e-444444444444",
            "startDateTime": "2020-04-22T21:50:13Z",
            "type": "AsymmetricX509Cert",
            "usage": "Verify",
            "key": "cD2eF3gH4iJ5kL6mN7-oP8qR9sT==",
            "displayName": "CN=contoso"
        }

    ],
    "passwordCredentials": [
        {
            "customKeyIdentifier": "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=",
            "keyId": "cccccccc-2d2d-3e3e-4f4f-555555555555",
            "endDateTime": "2022-01-27T19:40:33Z",
            "startDateTime": "2020-04-20T19:40:33Z",
            "secretText": "mypassword"
        }
    ]
}

Mengonfigurasi kunci penandatanganan kustom menggunakan PowerShell

Gunakan PowerShell untuk membuat instans MSAL Public Client Application dan gunakan alur Authorization Code Grant untuk mendapatkan token akses izin khusus untuk Microsoft Graph. Gunakan token akses untuk memanggil Microsoft Graph dan mengonfigurasikan kunci penandatanganan kustom untuk perwakilan layanan. Setelah Mengonfigurasi kunci penandatanganan kustom, kode aplikasi Anda perlu memvalidasi kunci penandatanganan token.

Untuk menjalankan skrip ini, Anda memerlukan:

• ID objek perwakilan layanan aplikasi Anda, ditemukan di bilah Gambaran Umum entri aplikasi Anda di Aplikasi Perusahaan di portal Azure.
• Pendaftaran aplikasi untuk membawa pengguna masuk dan mendapatkan token akses untuk memanggil Microsoft Graph. Dapatkan ID (klien) aplikasi untuk aplikasi ini di bilah Gambaran Umum entri aplikasi di Pendaftaran aplikasi di portal Azure. Pendaftaran aplikasi harus memiliki konfigurasi berikut:
  • URI pengalihan "http://localhost" tercantum dalam konfigurasi platform Aplikasi seluler dan desktop.
  • Dalam izin API, Microsoft Graph mendelegasikan izin Application.ReadWrite.All dan User.Read (pastikan Anda memberikan persetujuan Admin untuk izin ini).
• Pengguna yang masuk untuk mendapatkan token akses Microsoft Graph. Pengguna harus menjadi salah satu peran administratif Microsoft Entra berikut (diperlukan untuk memperbarui perwakilan layanan):
  • Admin Aplikasi Cloud
  • Administrator Aplikasi
• Sertifikat untuk dikonfigurasi sebagai kunci penandatanganan kustom untuk aplikasi kami. Anda dapat membuat sertifikat yang ditandatangani sendiri atau mendapatkannya dari otoritas sertifikat tepercaya Anda. Komponen sertifikat berikut digunakan dalam skrip:
  • kunci umum (biasanya file .cer )
  • kunci privat dalam format PKCS#12 (dalam file .pfx )
  • kata sandi untuk kunci privat (file.pfx )

Penting

Kunci privat harus dalam format PKCS#12 karena ID Microsoft Entra tidak mendukung jenis format lainnya. Menggunakan format yang salah dapat mengakibatkan kesalahan "Sertifikat tidak valid: Nilai kunci adalah sertifikat yang tidak valid" saat menggunakan Microsoft Graph untuk MENAMBAL perwakilan layanan dengan keyCredentials yang berisi informasi sertifikat.

##########################################################
# Replace the variables below with the appropriate values 

$fqdn="yourDomainHere" # This is used for the 'issued to' and 'issued by' field of the certificate
$pwd="password" # password for exporting the certificate private key
$tenantId   = "aaaabbbb-0000-cccc-1111-dddd2222eeee" # Replace with your Tenant ID
$appObjId = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" # Replace with the Object ID of the App Registration

##########################################################

# Create a self-signed cert

$cert = New-SelfSignedCertificate -certstorelocation cert:\currentuser\my -DnsName $fqdn
$pwdSecure = ConvertTo-SecureString -String $pwd -Force -AsPlainText
$path = 'cert:\currentuser\my\' + $cert.Thumbprint
$location="C:\\temp" # path to folder where both the pfx and cer file will be written to
$cerFile = $location + "\\" + $fqdn + ".cer"
$pfxFile = $location + "\\" + $fqdn + ".pfx"
 
# Export the public and private keys
Export-PfxCertificate -cert $path -FilePath $pfxFile -Password $pwdSecure
Export-Certificate -cert $path -FilePath $cerFile

$pfxpath = $pfxFile # path to pfx file
$cerpath = $cerFile # path to cer file
$password = $pwd  # password for the pfx file
 
# Check PowerShell version (minimum 5.1) (.Net) or PowerShell Core (.Net Core) and read the certificate file accordingly
 
if ($PSVersionTable.PSVersion.Major -gt 5)
    { 
        $core = $true
    }
else
    { 
        $core = $false
    }
 
    #  this is for PowerShell Core
    $Secure_String_Pwd = ConvertTo-SecureString $password -AsPlainText -Force
 
    # reading certificate files and creating Certificate Object
    if ($core)
    {
        $pfx_cert = get-content $pfxpath -AsByteStream -Raw
        $cer_cert = get-content $cerpath -AsByteStream -Raw
        $cert = Get-PfxCertificate -FilePath $pfxpath -Password $Secure_String_Pwd
    }
    else
    {
        $pfx_cert = get-content $pfxpath -Encoding Byte
        $cer_cert = get-content $cerpath -Encoding Byte
        # calling Get-PfxCertificate in PowerShell 5.1 prompts for password - using alternative method
        $cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($pfxpath, $password)
    }

 
    # base 64 encode the private key and public key
    $base64pfx = [System.Convert]::ToBase64String($pfx_cert)
    $base64cer = [System.Convert]::ToBase64String($cer_cert)
 
    # getting id for the keyCredential object
    $guid1 = New-Guid
    $guid2 = New-Guid
 
    # get the custom key identifier from the certificate thumbprint:
    $hasher = [System.Security.Cryptography.HashAlgorithm]::Create('sha256')
    $hash = $hasher.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($cert.Thumbprint))
    $customKeyIdentifier = [System.Convert]::ToBase64String($hash)
 
    # get end date and start date for our keycredentials
    $endDateTime = ($cert.NotAfter).ToUniversalTime().ToString( "yyyy-MM-ddTHH:mm:ssZ" )
    $startDateTime = ($cert.NotBefore).ToUniversalTime().ToString( "yyyy-MM-ddTHH:mm:ssZ" )
 
    # building our json payload
    $object = [ordered]@{    
    keyCredentials = @(       
         [ordered]@{            
            customKeyIdentifier = $customKeyIdentifier
            endDateTime = $endDateTime
            keyId = $guid1
            startDateTime = $startDateTime 
            type = "AsymmetricX509Cert"
            usage = "Sign"
            key = $base64pfx
            displayName = "CN=$fqdn" 
        },
        [ordered]@{            
            customKeyIdentifier = $customKeyIdentifier
            endDateTime = $endDateTime
            keyId = $guid2
            startDateTime = $startDateTime 
            type = "AsymmetricX509Cert"
            usage = "Verify"
            key = $base64cer
            displayName = "CN=$fqdn"   
        }
        )  
    passwordCredentials = @(
        [ordered]@{
            customKeyIdentifier = $customKeyIdentifier
            displayName = "CN=$fqdn"
            keyId = $guid1           
            endDateTime = $endDateTime
            startDateTime = $startDateTime
            secretText = $password
            hint = $null
        }
    )
    }
 
Connect-MgGraph -tenantId $tenantId -Scopes Application.ReadWrite.All
$graphuri = "https://graph.microsoft.com/v1.0/applications/$appObjId"
Invoke-MgGraphRequest -Method PATCH -Uri $graphuri -Body $object

    $json = $object | ConvertTo-Json -Depth 99
    Write-Host "JSON Payload:"
    Write-Output $json

Validasi kunci penandatanganan token

Aplikasi yang mengaktifkan pemetaan klaim harus memvalidasi kunci penandatanganan token mereka dengan menambahkan appid={client_id} ke permintaan metadata OpenID Connect mereka. Contoh berikut menunjukkan format dokumen metadata OpenID Connect yang harus Anda gunakan:

https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration?appid={client-id}

Memperbarui manifes aplikasi

Untuk aplikasi penyewa tunggal, Anda dapat menetapkan properti acceptMappedClaims ke true di manifes aplikasi. Seperti yang apiApplication didokumenkan pada jenis sumber daya. Mengatur properti memungkinkan aplikasi untuk menggunakan pemetaan klaim tanpa menentukan kunci penandatanganan kustom.

Peringatan

Jangan atur properti acceptMappedClaims ke true untuk aplikasi multi-penyewa, yang dapat memungkinkan aktor jahat membuat kebijakan pemetaan klaim untuk aplikasi Anda.

Audiens token yang diminta diperlukan untuk menggunakan nama domain terverifikasi dari penyewa Microsoft Entra Anda, yang berarti Anda harus mengatur Application ID URI (diwakili oleh identifierUris dalam manifes aplikasi) misalnya ke https://contoso.com/my-api atau (cukup menggunakan nama penyewa default) https://contoso.onmicrosoft.com/my-api.

Jika Anda tidak menggunakan domain terverifikasi, MICROSOFT Entra ID mengembalikan AADSTS501461 kode kesalahan dengan pesan "_AcceptMappedClaims hanya didukung untuk audiens token yang cocok dengan GUID aplikasi atau audiens dalam domain terverifikasi penyewa. Ubah pengidentifikasi sumber daya atau gunakan kunci penandatanganan khusus aplikasi."

Opsi klaim tingkat lanjut

Konfigurasikan opsi klaim tingkat lanjut untuk aplikasi OIDC untuk mengekspos klaim yang sama dengan token SAML. Juga untuk aplikasi yang ingin menggunakan klaim yang sama untuk token respons SAML2.0 dan OIDC.

Konfigurasikan opsi klaim tingkat lanjut dengan mencentang kotak di bawah Opsi Klaim Tingkat Lanjut di bilah Kelola klaim .

Konten terkait

• Klaim dan token yang digunakan dalam ID Microsoft Entra.