Memvalidasi JWT

Artikel
03/18/2024

BERLAKU UNTUK: Semua tingkatAN API Management

Kebijakan memberlakukan validate-jwt keberadaan dan validitas token web JSON (JWT) yang didukung yang diekstrak dari header HTTP tertentu, yang diekstrak dari parameter kueri tertentu, atau cocok dengan nilai tertentu.

Catatan

Untuk memvalidasi JWT yang disediakan oleh layanan Microsoft Entra, API Management juga menyediakan kebijakan.validate-azure-ad-token

Catatan

Tetapkan elemen kebijakan dan elemen turunan dalam urutan yang disediakan dalam pernyataan kebijakan. Untuk membantu Anda mengonfigurasi kebijakan ini, portal menyediakan editor berbasis formulir berikut panduannya. Pelajari lebih lanjut cara mengatur atau mengedit kebijakan API Management.

Pernyataan kebijakan

<validate-jwt
    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"
    require-expiration-time="true | false"
    require-scheme="scheme"
    require-signed-tokens="true | false"
    clock-skew="allowed clock skew in seconds"
    output-token-variable-name="name of a variable to receive a JWT object representing successfully validated token">
  <openid-config url="full URL of the configuration endpoint, for example, https://login.constoso.com/openid-configuration" />
  <issuer-signing-keys>
    <key>Base64 encoded signing key | certificate-id="mycertificate" | n="modulus" e="exponent"</key>
    <!-- if there are multiple keys, then add additional key elements -->
  </issuer-signing-keys>
  <decryption-keys>
    <key>Base64 encoded signing key | certificate-id="mycertificate" | n="modulus" e="exponent" </key>
    <!-- if there are multiple keys, then add additional key elements -->
  </decryption-keys>
  <audiences>
    <audience>audience string</audience>
    <!-- if there are multiple possible audiences, then add additional audience elements -->
  </audiences>
  <issuers>
    <issuer>issuer string</issuer>
    <!-- if there are multiple possible issuers, then add additional issuer elements -->
  </issuers>
  <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 claim, then add additional claim elements -->
  </required-claims>
</validate-jwt>

Atribut

Atribut	Deskripsi	Wajib diisi	Default
nama-header	Nama header HTTP yang menyimpan token. Ekspresi kebijakan diizinkan.	Salah satu dari `header-name`, `query-parameter-name` atau `token-value` harus ditentukan.	T/A
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 ditampilkan 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."
membutuhkan-waktu kedaluwarsa	Boolean. Menentukan apakah klaim kedaluwarsa diperlukan dalam token. Ekspresi kebijakan diizinkan.	No	benar
skema kebutuhan	Nama skema token, misalnya, "Pembawa". Jika atribut ini disetel, kebijakan akan memastikan bahwa skema yang ditentukan ada di nilai header Otorisasi. Ekspresi kebijakan diizinkan.	No	T/A
token-yang harus ditandatangani	Boolean. Menentukan apakah token perlu ditandatangani. Ekspresi kebijakan diizinkan.	No	benar
penyimpangan-jam	Jangka Waktu. Gunakan untuk menentukan perbedaan waktu maksimum yang diharapkan antara jam sistem penerbit token dan instans API Management. Ekspresi kebijakan diizinkan.	No	0 detik
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
openid-config	Tambahkan satu atau beberapa elemen ini untuk menentukan URL titik akhir konfigurasi OpenID yang sesuai tempat kunci penandatanganan dan pengeluar sertifikat dapat diperoleh. Konfigurasi termasuk JSON Web Key Set (JWKS) ditarik dari titik akhir setiap 1 jam dan di-cache. Jika token yang divalidasi mereferensikan kunci validasi (menggunakan `kid` klaim) yang hilang dalam konfigurasi cache, atau jika pengambilan gagal, API Management menarik dari titik akhir paling banyak sekali per 5 menit. Interval ini dapat berubah tanpa pemberitahuan. Respons harus sesuai dengan spesifikasi seperti yang didefinisikan di URL: `https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata`. Untuk ID Microsoft Entra, gunakan titik akhir metadata OpenID Koneksi yang dikonfigurasi dalam pendaftaran aplikasi Anda seperti: - v2 `https://login.microsoftonline.com/{tenant-name}/v2.0/.well-known/openid-configuration` - Multi-Penyewa v2 `https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration` - v1 `https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration` - Penyewa pelanggan (pratinjau) `https://{tenant-name}.ciamlogin.com/{tenant-id}/v2.0/.well-known/openid-configuration` Mengganti nama atau ID penyewa direktori Anda, misalnya `contoso.onmicrosoft.com`, untuk `{tenant-name}`.	No
penerbit-penandatanganan-kunci	Daftar kunci keamanan yang dikodekan Base64, dalam `key` subelemen, digunakan untuk memvalidasi token yang ditandatangani. Jika ada beberapa kunci keamanan, maka setiap kunci akan dicoba hingga semuanya habis (dalam hal ini validasi gagal) atau satu berhasil (berguna untuk rollover token). Secara opsional tentukan kunci dengan menggunakan `id` atribut untuk mencocokkan `kid` klaim. Untuk memvalidasi token yang ditandatangani dengan kunci asimetris, secara opsional tentukan kunci publik menggunakan `certificate-id` atribut dengan nilai pengidentifikasi sertifikat yang diunggah ke API Management, atau modulus `n` RSA dan pasangan eksponen `e` kunci penandatanganan dalam format yang dikodekan Base64url.	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. Secara opsional tentukan kunci dengan menggunakan `id` atribut untuk mencocokkan `kid` klaim. Untuk mendekripsi token yang dienkripsi dengan kunci asimetris, secara opsional tentukan kunci publik menggunakan `certificate-id` atribut dengan nilai pengidentifikasi sertifikat yang diunggah ke API Management, atau modulus `n` RSA dan pasangan eksponen `e` kunci dalam format yang dikodekan Base64url.	No
audiens	Daftar klaim audiens yang dapat diterima, dalam `audience` subelemen, yang dapat ada pada token. Jika ada beberapa nilai audiens, setiap nilai akan dicoba hingga semuanya habis (dalam hal ini validasi gagal) atau hingga salah satu berhasil. Setidaknya satu audiens harus ditentukan.	No
penerbit	Daftar prinsipal yang dapat diterima, dalam `issuer` subelemen, yang mengeluarkan token. Jika ada beberapa nilai penerbit, maka setiap nilai akan dicoba hingga semuanya habis (dalam hal ini validasi gagal) atau hingga satu berhasil.	No
klaim-yang diperlukan	Daftar klaim, dalam `claim` subelemen, diharapkan ada pada token agar dianggap valid. Ketika beberapa klaim ada, token harus cocok dengan nilai klaim sesuai dengan nilai `match` atribut.	No

atribut kunci

Atribut	Deskripsi	Wajib diisi	Default
id	String. Pengidentifikasi yang digunakan untuk mencocokkan `kid` klaim yang disajikan di JWT.	No	T/A
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
n	Modulus kunci publik yang digunakan untuk memverifikasi penerbit token yang ditandatangani dengan kunci asimetris. Harus ditentukan dengan nilai eksponen `e`. Ekspresi kebijakan tidak diizinkan.	No	T/A
e	Eksponen kunci publik yang digunakan untuk memverifikasi penerbit token yang ditandatangani dengan kunci asimetris. Harus ditentukan dengan nilai modulus `n`. Ekspresi kebijakan tidak diizinkan.	No	T/A

atribut klaim

Atribut	Deskripsi	Wajib diisi	Default
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.	No	all
pemisah	String. Menentukan pemisah (misalnya, ",") yang akan digunakan untuk mengekstrak sekumpulan nilai dari klaim multinilai.	No	T/A

Penggunaan

Bagian kebijakan: masuk
Cakupan kebijakan: global, ruang kerja, produk, API, operasi
Gateway: klasik, v2, konsumsi, dihost sendiri

Catatan penggunaan

Kebijakan validate-jwt mengharuskan exp klaim terdaftar disertakan dalam token JWT, kecuali atribut require-expiration-time ditentukan dan disetel ke false.
Kebijakan ini mendukung algoritma penandatanganan simetris dan asimetris:
- Simetris - Algoritma enkripsi berikut didukung: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.
  - Jika digunakan dalam kebijakan, kunci harus disediakan sebaris dalam kebijakan dalam formulir yang dikodekan Base64.
- Asimetris - Algortithma enkripsi berikut didukung: PS256, RS256, RS512.
  - Jika digunakan dalam kebijakan, kunci dapat disediakan baik melalui titik akhir konfigurasi OpenID, atau dengan memberikan ID sertifikat yang diunggah (dalam format PFX) yang berisi kunci publik, atau pasangan modulus-eksponen dari kunci publik.
Untuk mengonfigurasi kebijakan dengan satu atau beberapa titik akhir konfigurasi OpenID untuk digunakan dengan gateway yang dihost sendiri, URL titik akhir konfigurasi OpenID juga harus dapat dijangkau oleh gateway cloud.
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-jwt kebijakan pada tingkat API, atau Anda dapat menerapkannya pada tingkat operasi API dan menggunakannya claims untuk kontrol yang lebih terperinci.
Saat menggunakan header kustom (header-name), skema yang diperlukan yang dikonfigurasi (require-scheme) akan diabaikan. Untuk menggunakan skema yang diperlukan, token JWT harus disediakan di Authorization header.

Contoh

Validasi token sederhana

<validate-jwt header-name="Authorization" require-scheme="Bearer">
    <issuer-signing-keys>
        <key>{{jwt-signing-key}}</key>  <!-- signing key specified as a named value -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>  <!-- audience is set to API Management host name -->
    </audiences>
    <issuers>
        <issuer>http://contoso.com/</issuer>
    </issuers>
</validate-jwt>

Validasi token dengan sertifikat RSA

<validate-jwt header-name="Authorization" require-scheme="Bearer">
    <issuer-signing-keys>
        <key certificate-id="my-rsa-cert" />  <!-- signing key specified as certificate ID, enclosed in double-quotes -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>  <!-- audience is set to API Management host name -->
    </audiences>
    <issuers>
        <issuer>http://contoso.com/</issuer>
    </issuers>
</validate-jwt>

Validasi token penyewa tunggal ID Microsoft Entra

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/contoso.onmicrosoft.com/.well-known/openid-configuration" />
    <audiences>
        <audience>25eef6e4-c905-4a07-8eb4-0d08d5df8b3f</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

Validasi token penyewa pelanggan ID Microsoft Entra

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
	<openid-config url="https://<tenant-name>.ciamlogin.com/<tenant-id>/v2.0/.well-known/openid-configuration" />
	<required-claims>
		<claim name="azp" match="all">
			<value>insert claim here</value>
		</claim>
	</required-claims>
</validate-jwt>

Validasi token Azure Active Directory B2C

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/tfp/contoso.onmicrosoft.com/b2c_1_signin/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>d313c4e4-de5f-4197-9470-e509a2f0b806</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

Otorisasi akses ke operasi berdasarkan klaim token

Contoh ini menunjukkan cara menggunakan validate-jwt kebijakan untuk mengotorisasi akses ke operasi berdasarkan nilai klaim token.

<validate-jwt header-name="Authorization" require-scheme="Bearer" output-token-variable-name="jwt">
    <issuer-signing-keys>
        <key>{{jwt-signing-key}}</key> <!-- signing key is stored in a named value -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>
    </audiences>
    <issuers>
        <issuer>contoso.com</issuer>
    </issuers>
    <required-claims>
        <claim name="group" match="any">
            <value>finance</value>
            <value>logistics</value>
        </claim>
    </required-claims>
</validate-jwt>
<choose>
    <when condition="@(context.Request.Method == "POST" && !((Jwt)context.Variables["jwt"]).Claims["group"].Contains("finance"))">
        <return-response>
            <set-status code="403" reason="Forbidden" />
        </return-response>
    </when>
</choose>

Autentikasi dan Otorisasi

Untuk informasi selengkapnya tentang bekerja dengan kebijakan, lihat:

Tutorial: Mengubah dan melindungi API Anda
Referensi Kebijakan untuk daftar lengkap pernyataan kebijakan dan pengaturannya
Ekspresi kebijakan
Mengatur atau mengedit kebijakan
Menggunakan kembali konfigurasi kebijakan
Repositori cuplikan kebijakan
Kebijakan penulis menggunakan Microsoft Copilot untuk Azure