Bagikan melalui

Memvalidasi token Microsoft Entra

  • Artikel

BERLAKU UNTUK: Semua tingkatAN API Management

Kebijakan ini validate-azure-ad-token memberlakukan keberadaan dan validitas token web JSON (JWT) yang disediakan oleh layanan Microsoft Entra (sebelumnya disebut Azure Active Directory) untuk sekumpulan prinsipal tertentu dalam direktori. JWT dapat diekstrak dari header HTTP, parameter kueri, atau nilai tertentu yang disediakan menggunakan ekspresi kebijakan atau variabel konteks.

Catatan

Untuk memvalidasi JWT yang disediakan oleh penyedia identitas selain Microsoft Entra, API Management juga menyediakan kebijakan umum validate-jwt .

Catatan

Tetapkan elemen kebijakan dan elemen turunan dalam urutan yang disediakan dalam pernyataan kebijakan. Pelajari lebih lanjut cara mengatur atau mengedit kebijakan API Management.

Pernyataan kebijakan

<validate-azure-ad-token
    tenant-id="tenant ID or URL (for example, "https://contoso.onmicrosoft.com") of the Microsoft Entra ID tenant"
    header-name="name of HTTP header containing the token (alternatively, use query-parameter-name or token-value attribute to specify token)"
    query-parameter-name="name of query parameter used to pass the token (alternative, use header-name or token-value attribute to specify token)"
    token-value="expression returning the token as a string (alternatively, use header-name or query-parameter attribute to specify token)"
    failed-validation-httpcode="HTTP status code to return on failure"
    failed-validation-error-message="error message to return on failure"
    output-token-variable-name="name of a variable to receive a JWT object representing successfully validated token">
    <client-application-ids>
        <application-id>Client application ID from Microsoft Entra</application-id>
        <!-- If there are multiple client application IDs, then add additional application-id elements -->
    </client-application-ids>
    <backend-application-ids>
        <application-id>Backend application ID from Microsoft Entra</application-id>
        <!-- If there are multiple backend application IDs, then add additional application-id elements -->
    </backend-application-ids>
    <audiences>
        <audience>audience string</audience>
        <!-- if there are multiple possible audiences, then add additional audience elements -->
    </audiences>
    <required-claims>
        <claim name="name of the claim as it appears in the token" match="all|any" separator="separator character in a multi-valued claim">
            <value>claim value as it is expected to appear in the token</value>
            <!-- if there is more than one allowed value, then add additional value elements -->
        </claim>
        <!-- if there are multiple possible allowed values, then add additional value elements -->
    </required-claims>
    <decryption-keys>
        <key>Base64 encoded signing key | certificate-id="mycertificate"</key>
        <!-- if there are multiple keys, then add additional key elements -->
    </decryption-keys>
</validate-azure-ad-token>

Atribut

Atribut Deskripsi Wajib diisi Default
tenant-id ID penyewa atau URL penyewa MICROSOFT Entra ID, atau salah satu penyewa terkenal berikut:

- organizations atau https://login.microsoftonline.com/organizations - untuk mengizinkan token dari akun di direktori organisasi apa pun (direktori Microsoft Entra apa pun)
- common atau https://login.microsoftonline.com/common - untuk mengizinkan token dari akun di direktori organisasi apa pun (direktori Microsoft Entra apa pun) dan dari akun Microsoft pribadi (misalnya, Skype, XBox)

Ekspresi kebijakan diizinkan.		 Ya T/A
nama-header Nama header HTTP yang menyimpan token. Ekspresi kebijakan diizinkan. Salah satu dari header-name, query-parameter-name atau token-value harus ditentukan. Authorization
nama-parameter-kueri Nama parameter kueri yang memegang token. Ekspresi kebijakan diizinkan. Salah satu dari header-name, query-parameter-name atau token-value harus ditentukan. T/A
nilai token Ekspresi menampilkan string yang berisi token tersebut. Anda tidak boleh menampilkan Bearer sebagai bagian dari nilai token. Ekspresi kebijakan diizinkan. Salah satu dari header-name, query-parameter-name atau token-value harus ditentukan. T/A
gagal-validasi-kode http Kode status HTTP untuk dikembalikan jika JWT tidak lulus validasi. Ekspresi kebijakan diizinkan. No 401
gagal-validasi-pesan-kesalahan Pesan kesalahan untuk dikembalikan dalam isi respons HTTP jika JWT tidak lulus validasi. Pesan ini harus memiliki karakter khusus yang lolos dengan benar. Ekspresi kebijakan diizinkan. No Pesan kesalahan default bergantung pada masalah validasi, misalnya "JWT tidak ada."
output-token-variable-name String. Nama variabel konteks yang akan menerima nilai token sebagai objek jenis Jwt setelah validasi token berhasil. Ekspresi kebijakan tidak diizinkan. No T/A

Elemen

Elemen Deskripsi Wajib diisi
audiens Berisi daftar klaim audiens yang dapat diterima yang dapat ada di token. Jika ada beberapa audience nilai, maka setiap nilai dicoba hingga semua habis (dalam hal ini validasi gagal) atau sampai satu berhasil. Ekspresi kebijakan diizinkan. No
backend-application-ids Berisi daftar ID aplikasi backend yang dapat diterima. Ini hanya diperlukan dalam kasus lanjutan untuk konfigurasi opsi dan umumnya dapat dihapus. Ekspresi kebijakan tidak diizinkan. No
client-application-ids Berisi daftar ID aplikasi klien yang dapat diterima. Jika ada beberapa application-id elemen, maka setiap nilai dicoba sampai semuanya habis (dalam hal ini validasi gagal) atau sampai satu berhasil. Jika ID aplikasi klien tidak disediakan, satu atau beberapa audience klaim harus ditentukan. Ekspresi kebijakan tidak diizinkan. No
klaim-yang diperlukan Berisi daftar claim elemen untuk nilai klaim yang diharapkan ada pada token agar dianggap valid. match Ketika atribut diatur ke all, setiap nilai klaim dalam kebijakan harus ada dalam token agar validasi berhasil. match Ketika atribut diatur ke any, setidaknya satu klaim harus ada dalam token agar validasi berhasil. Ekspresi kebijakan diizinkan. No
dekripsi-kunci Daftar kunci yang dikodekan Base64, dalam key subelemen, digunakan untuk mendekripsi token. Jika ada beberapa kunci keamanan, maka setiap kunci akan dicoba hingga semua kunci habis (dalam hal ini validasi gagal) atau kunci berhasil.

Untuk mendekripsi token yang dienkripsi dengan kunci asimetris, secara opsional tentukan kunci publik menggunakan atribut dengan nilai yang certificate-id diatur ke pengidentifikasi sertifikat yang diunggah ke API Management.		 No

atribut klaim

Atribut Deskripsi Wajib diisi Default
nama Nama klaim seperti yang diharapkan muncul dalam token. Ekspresi kebijakan diizinkan. Ya T/A
cocok Atribut match pada elemen claim menentukan apakah setiap nilai klaim dalam kebijakan harus ada dalam token agar validasi berhasil. Kemungkinan nilai adalah:

- all - setiap nilai klaim dalam kebijakan harus ada dalam token agar validasi berhasil.

- any - setidaknya satu nilai klaim harus ada dalam token agar validasi berhasil.

Ekspresi kebijakan diizinkan.		 No all
pemisah String. Menentukan pemisah (misalnya, ",") yang akan digunakan untuk mengekstrak sekumpulan nilai dari klaim multinilai. Ekspresi kebijakan diizinkan. No T/A

atribut kunci

Atribut Deskripsi Wajib diisi Default
certificate-id Pengidentifikasi entitas sertifikat yang diunggah ke API Management, digunakan untuk menentukan kunci publik untuk memverifikasi token yang ditandatangani dengan kunci asimetris. No T/A

Penggunaan

Catatan penggunaan

  • Anda dapat menggunakan kebijakan pembatasan akses dalam cakupan yang berbeda untuk tujuan yang berbeda. Misalnya, Anda dapat mengamankan seluruh API dengan autentikasi Microsoft Entra dengan menerapkan validate-azure-ad-token kebijakan pada tingkat API, atau Anda dapat menerapkannya pada tingkat operasi API dan menggunakannya claims untuk kontrol yang lebih terperinci.
  • ID Microsoft Entra untuk pelanggan (pratinjau) tidak didukung.

Contoh

Validasi token sederhana

Kebijakan berikut adalah bentuk validate-azure-ad-token kebijakan minimal. Ini mengharapkan JWT disediakan di header default Authorization menggunakan Bearer skema . Dalam contoh ini, ID penyewa Microsoft Entra dan ID aplikasi klien disediakan menggunakan nilai bernama.

<validate-azure-ad-token tenant-id="{{aad-tenant-id}}">
    <client-application-ids>
        <application-id>{{aad-client-application-id}}</application-id>
    </client-application-ids>
</validate-azure-ad-token>

Memvalidasi bahwa audiens dan klaim sudah benar

Kebijakan berikut memeriksa bahwa audiens adalah nama host instans API Management dan bahwa ctry klaimnya adalah US. ID penyewa Microsoft adalah penyewa terkenal organizations , yang memungkinkan token dari akun di direktori organisasi apa pun. Nama host disediakan menggunakan ekspresi kebijakan, dan ID aplikasi klien disediakan menggunakan nilai bernama. JWT yang didekodekan disediakan dalam jwt variabel setelah validasi.

Untuk detail selengkapnya tentang klaim opsional, baca Memberikan klaim opsional ke aplikasi Anda.

<validate-azure-ad-token tenant-id="organizations" output-token-variable-name="jwt">
    <client-application-ids>
        <application-id>{{aad-client-application-id}}</application-id>
    </client-application-ids>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>
    </audiences>
    <required-claims>
        <claim name="ctry" match="any">
            <value>US</value>
        </claim>
    </required-claims>
</validate-azure-ad-token>

Konten terkait

Untuk informasi selengkapnya tentang bekerja dengan kebijakan, lihat: