kebijakan VerifyJWT

Anda sedang melihat dokumentasi Apigee Edge.
Buka Dokumentasi Apigee X.
info

Apa

Memverifikasi tanda tangan pada JWT yang diterima dari klien atau sistem lain. Kebijakan ini juga mengekstrak klaim ke dalam variabel konteks sehingga kebijakan atau kondisi berikutnya dapat diperiksa nilai-nilai tersebut untuk membuat keputusan otorisasi atau {i>routing<i}. Lihat ringkasan kebijakan JWS dan JWT untuk pengantar mendetail.

Saat kebijakan ini dijalankan, Edge memverifikasi tanda tangan JWT, dan memverifikasi bahwa JWT valid sesuai dengan masa berlaku dan waktu selain sebelumnya jika ada. Secara opsional, kebijakan dapat verifikasi juga nilai klaim khusus pada JWT, seperti subjek, penerbit, audiens, atau nilai klaim tambahan.

Jika JWT diverifikasi dan valid, maka semua klaim yang terdapat dalam JWT akan yang diekstrak ke dalam variabel konteks untuk digunakan oleh kebijakan atau ketentuan selanjutnya, dan permintaannya diizinkan untuk melanjutkan. Jika tanda tangan JWT tidak dapat diverifikasi atau jika JWT tidak valid karena salah satu stempel waktu, semua pemrosesan berhenti dan error ditampilkan dalam respons.

Untuk mempelajari bagian-bagian JWT dan cara mengenkripsi serta menandatanganinya, lihat RFC7519.

Video

Tonton video singkat untuk mempelajari cara memverifikasi tanda tangan di JWT.

Contoh

Memverifikasi JWT yang ditandatangani dengan HS256 algoritma

Contoh kebijakan ini memverifikasi JWT yang ditandatangani dengan algoritma enkripsi HS256, HMAC menggunakan {i>checksum<i} SHA-256. JWT diteruskan dalam permintaan proxy menggunakan parameter formulir yang diberi nama jwt. Kunci ini terdapat dalam variabel bernama private.secretkey. Lihat video di atas untuk contoh lengkapnya, termasuk cara mengajukan permintaan ke kebijakan.

Konfigurasi kebijakan mencakup informasi yang diperlukan Edge untuk mendekode dan mengevaluasi JWT, seperti tempat menemukan JWT (dalam variabel flow yang ditentukan dalam elemen Source), fungsi penandatanganan, tempat menemukan kunci rahasia (disimpan dalam variabel alur Edge, yang bisa yang telah diambil dari Edge KVM, misalnya), dan serangkaian klaim yang masing-masing.

<VerifyJWT name="JWT-Verify-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey encoding="base64">
        <Value ref="private.secretkey"/>
    </SecretKey>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
</VerifyJWT>

Kebijakan menulis output-nya ke variabel konteks sehingga kebijakan atau kondisi berikutnya di proxy API yang bisa memeriksa nilai-nilai tersebut. Lihat Variabel flow untuk daftar variabel yang ditetapkan oleh kebijakan ini.

Memverifikasi JWT yang ditandatangani dengan RS256 algoritma

Contoh kebijakan ini memverifikasi JWT yang ditandatangani dengan algoritma RS256. Untuk memverifikasi, Anda perlu menyediakan kunci publik. JWT diteruskan dalam permintaan proxy menggunakan parameter formulir bernama jwt. Kunci publik terdapat dalam variabel bernama public.publickey. Lihat video di atas untuk contoh lengkapnya, termasuk cara mengajukan permintaan ke kebijakan.

Lihat referensi Elemen untuk mengetahui detail tentang persyaratan dan opsi bagi setiap elemen contoh kebijakan.

<VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>    
    </AdditionalClaims>
</VerifyJWT>

Untuk konfigurasi di atas, JWT dengan header ini ...

{
  "typ" : "JWT", 
  "alg" : "RS256"
}

Dan payload ini ...

{ 
  "sub" : "apigee-seattle-hatrack-montage",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
  "show": "And now for something completely different."
}

... akan dianggap valid, jika tanda tangan tersebut dapat diverifikasi oleh publik tombol.

JWT dengan header yang sama tetapi dengan payload ini ...

{ 
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
  "show": "And now for something completely different."
}

... akan dinyatakan tidak valid, meskipun tanda tangannya dapat diverifikasi, karena "sub" klaim yang disertakan dalam JWT tidak sesuai dengan nilai "Subjek" yang diwajibkan elemen sebagai yang ditentukan dalam konfigurasi kebijakan.

Kebijakan menulis output-nya ke variabel konteks sehingga kebijakan atau kondisi berikutnya di proxy API yang bisa memeriksa nilai-nilai tersebut. Lihat Variabel flow untuk daftar variabel yang ditetapkan oleh kebijakan ini.

Menetapkan elemen kunci

Elemen yang Anda gunakan untuk menentukan kunci yang digunakan untuk memverifikasi JWT tergantung pada algoritma yang dipilih, seperti yang ditunjukkan dalam tabel berikut:

Algoritma Elemen utama
HS*
<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.secretkey"/>
</SecretKey>
RS*, ES*, PS*
<PublicKey>
  <Value ref="rsa_public_key_or_value"/>
</PublicKey>

atau:

<PublicKey>
  <Certificate ref="signed_cert_val_ref"/>
</PublicKey>

atau:

<PublicKey>
  <JWKS ref="jwks_val_or_ref"/>
</PublicKey>
*Untuk informasi selengkapnya tentang persyaratan utama, lihat Tentang algoritma enkripsi tanda tangan.

Referensi elemen

Referensi kebijakan menjelaskan elemen dan atribut kebijakan Verifikasi JWT.

Catatan: Konfigurasi akan sedikit berbeda tergantung enkripsi algoritma yang digunakan. Lihat Contoh untuk mengetahui contoh yang menunjukkan khusus untuk kasus penggunaan tertentu.

Atribut yang berlaku untuk elemen tingkat atas

<VerifyJWT name="JWT" continueOnError="false" enabled="true" async="false">

Atribut berikut umum untuk semua elemen induk kebijakan.

Atribut Deskripsi Default Kehadiran
nama Nama internal kebijakan. Karakter yang dapat Anda gunakan dalam nama dibatasi untuk: A-Z0-9._\-$ %. Namun, UI pengelolaan Edge menerapkan tertentu, seperti menghapus karakter yang bukan alfanumerik secara otomatis.

Secara opsional, gunakan elemen <displayname></displayname> untuk melabeli kebijakan di editor proxy UI pengelolaan dengan bahasa natural nama.

T/A Wajib
continueOnError Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Diharapkan untuk sebagian besar kebijakan.

Setel ke true agar eksekusi alur dapat dilanjutkan bahkan setelah kebijakan gagal.

salah Opsional
diaktifkan Setel ke true untuk menerapkan kebijakan.

Setel ke false untuk "matikan" kebijakan tersebut. Kebijakan ini tidak akan diterapkan bahkan jika data itu tetap terlampir pada aliran.

true Opsional
asinkron Atribut ini tidak digunakan lagi. salah Tidak digunakan lagi

&lt;DisplayName&gt;

<DisplayName>Policy Display Name</DisplayName>

Gunakan selain atribut nama untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural language yang berbeda.

Default Jika Anda menghapus elemen ini, nilai atribut nama kebijakan akan digunakan.
Kehadiran Opsional
Jenis String

&lt;Algorithm&gt;

<Algorithm>HS256</Algorithm>

Menentukan algoritma enkripsi untuk menandatangani token. Algoritma RS*/PS*/ES* menggunakan pasangan kunci publik/rahasia, sedangkan algoritma HS* menggunakan rahasia bersama. Lihat juga Tentang algoritma enkripsi tanda tangan.

Anda dapat menentukan beberapa nilai yang dipisahkan dengan tanda koma. Misalnya "HS256, HS512" atau "RS256, PS256". Namun, Anda tidak dapat mengombinasikan algoritma HS* dengan algoritma lain atau algoritma ES* dengan yang lain karena algoritma ini memerlukan jenis kunci tertentu. Anda dapat menggabungkan algoritma RS* dan PS*.

Default T/A
Kehadiran Wajib
Jenis String nilai yang dipisahkan koma
Nilai yang valid HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512

&lt;Audience&gt;

<Audience>audience-here</Audience>

or:

<Audience ref='variable-name-here'/>

Kebijakan ini memverifikasi bahwa klaim audiens di JWT cocok dengan nilai yang ditentukan di konfigurasi Anda. Jika tidak ada kecocokan, kebijakan akan menampilkan error. Klaim ini mengidentifikasi penerima yang menjadi tujuan JWT. Ini adalah salah satu klaim terdaftar yang disebutkan dalam RFC7519.

Default T/A
Kehadiran Opsional
Jenis String
Nilai yang valid Variabel alur atau string yang mengidentifikasi audiens.

&lt;AdditionalClaims/Claim&gt;

<AdditionalClaims>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
 </AdditionalClaims>

or:

<AdditionalClaims ref='claim_payload'/>

Memvalidasi bahwa payload JWT berisi klaim tambahan yang ditentukan dan bahwa cocok dengan nilai klaim yang dinyatakan.

Klaim tambahan menggunakan nama yang bukan salah satu nama klaim JWT standar yang terdaftar. Nilai klaim tambahan dapat berupa string, angka, boolean, peta, atau array. Sebuah peta hanya merupakan satu set pasangan nama/nilai. Nilai untuk klaim dari salah satu jenis ini dapat ditentukan secara eksplisit dalam konfigurasi kebijakan, atau secara tidak langsung melalui referensi ke variabel alur.

Default T/A
Kehadiran Opsional
Jenis String, angka, boolean, atau peta
Array Tetapkan ke true untuk menunjukkan apakah nilai berupa array jenis. Default: salah
Nilai yang valid Nilai apa pun yang ingin Anda gunakan untuk klaim tambahan.

Elemen <Claim> menggunakan atribut berikut:

  • name - (Wajib) Nama klaim.
  • ref - (Opsional) Nama variabel flow. Jika ada, kebijakan akan menggunakan nilai variabel sebagai klaim. Jika atribut ref dan nilai klaim eksplisit ditentukan, elemen nilai eksplisit adalah default, dan digunakan jika variabel alur yang direferensikan tidak terselesaikan.
  • type - (Opsional) Salah satu dari: string (default), angka, boolean, atau peta
  • array - (Opsional) Tetapkan ke true untuk menunjukkan apakah nilai merupakan array jenis. Default: {i>false<i}.

Jika Anda menyertakan elemen <Claim>, nama klaim ditetapkan secara statis saat Anda mengonfigurasi kebijakan. Atau, Anda dapat meneruskan objek JSON untuk menentukan nama klaim. Karena objek JSON diteruskan sebagai variabel, nama klaim ditentukan saat runtime.

Contoh:

<AdditionalClaims ref='json_claims'/>

Dengan variabel json_claims berisi objek JSON dalam bentuk:

{
  "sub" : "person@example.com",
  "iss" : "urn://secure-issuer@example.com",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

&lt;AdditionalHeaders/Claim&gt;

<AdditionalHeaders>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
    <Claim name='claim4' ref='variable-name' type='string' array='true'/>
 </AdditionalHeaders>

Memvalidasi bahwa header JWT berisi pasangan nama/nilai klaim tambahan yang ditentukan dan bahwa nilai klaim yang dinyatakan cocok.

Klaim tambahan menggunakan nama yang bukan salah satu nama klaim JWT standar yang terdaftar. Nilai klaim tambahan dapat berupa string, angka, boolean, peta, atau array. Sebuah peta hanya merupakan satu set pasangan nama/nilai. Nilai untuk klaim dari salah satu jenis ini dapat ditentukan secara eksplisit dalam konfigurasi kebijakan, atau secara tidak langsung melalui referensi ke variabel alur.

Default T/A
Kehadiran Opsional
Jenis

String (default), angka, boolean, atau peta.

Jenis default ke String jika tidak ada jenis yang ditentukan.

Array Tetapkan ke true untuk menunjukkan apakah nilai berupa array jenis. Default: salah
Nilai yang valid Nilai apa pun yang ingin Anda gunakan untuk klaim tambahan.

Elemen <Claim> menggunakan atribut berikut:

  • name - (Wajib) Nama klaim.
  • ref - (Opsional) Nama variabel flow. Jika ada, kebijakan akan menggunakan nilai variabel sebagai klaim. Jika atribut ref dan nilai klaim eksplisit ditentukan, elemen nilai eksplisit adalah default, dan digunakan jika variabel alur yang direferensikan tidak terselesaikan.
  • type - (Opsional) Salah satu dari: string (default), angka, boolean, atau peta
  • array - (Opsional) Tetapkan ke true untuk menunjukkan apakah nilai merupakan array jenis. Default: {i>false<i}.

&lt;CustomClaims&gt;

Catatan: Saat ini, elemen Custom Claims disisipkan saat Anda menambahkan elemen Buat kebijakan JWT melalui UI. Elemen ini tidak berfungsi dan akan diabaikan. Pernyataan yang benar yang akan digunakan adalah &lt;AdditionalClaims&gt;. UI akan diperbarui untuk menyisipkan elemen yang benar di lain waktu.

&lt;Id&gt;

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

Memverifikasi bahwa JWT memiliki klaim jti tertentu. Kapan nilai teks dan ref keduanya kosong, kebijakan akan menghasilkan jti yang berisi UUID acak. ID JWT (jti) adalah pengidentifikasi unik untuk JWT. Untuk informasi selengkapnya tentang jti, baca RFC7519.

Default T/A
Kehadiran Opsional
Jenis String, atau referensi.
Nilai yang valid String atau nama variabel flow yang berisi ID.

&lt;IgnoreCriticalHeaders&gt;

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

Tetapkan ke false jika Anda ingin kebijakan menampilkan error saat header apa pun yang tercantum dalam crit pada JWT tidak tercantum dalam elemen <KnownHeaders>. Jika disetel ke true, kebijakan VerifyJWT mengabaikan header crit.

Salah satu alasan untuk menetapkan elemen ini ke true adalah jika Anda berada di lingkungan pengujian dan belum siap untuk menyebabkan kegagalan pada {i>header<i} yang hilang.

Default salah
Kehadiran Opsional
Jenis Boolean
Nilai yang valid benar atau salah

&lt;IgnoreIssuedAt&gt;

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

Tetapkan ke false (default) jika Anda ingin kebijakan menampilkan error saat JWT berisi atribut Klaim iat (Diterbitkan pada) yang menentukan waktu di masa mendatang. Tetapkan ke true untuk menyebabkan kebijakan mengabaikan iat selama verifikasi.

Default salah
Kehadiran Opsional
Jenis Boolean
Nilai yang valid benar atau salah

&lt;IgnoreUnresolvedVariables&gt;

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Tetapkan ke false jika Anda ingin kebijakan menampilkan error saat variabel yang direferensikan ditentukan dalam kebijakan itu tidak dapat diselesaikan. Tetapkan ke true untuk memperlakukan variabel yang tidak dapat diselesaikan sebagai string kosong (null).

Default salah
Kehadiran Opsional
Jenis Boolean
Nilai yang valid benar atau salah

&lt;Issuer&gt;

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

Kebijakan ini memverifikasi bahwa penerbit di JWT cocok dengan string yang ditentukan dalam konfigurasi tambahan. Klaim yang mengidentifikasi penerbit JWT. Ini adalah salah satu kumpulan klaim terdaftar yang disebutkan dalam RFC7519.

Default T/A
Kehadiran Opsional
Jenis String, atau referensi
Nilai yang valid Semua

&lt;KnownHeaders&gt;

<KnownHeaders>a,b,c</KnownHeaders>

or:

<KnownHeaders ref=’variable_containing_headers’/>

Kebijakan GenerateJWT menggunakan elemen <CriticalHeaders> untuk mengisi crit di JWT. Contoh:

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

Kebijakan VerifyJWT memeriksa header crit di JWT, jika ada, dan untuk setiap header yang mencantumkannya. memeriksa apakah elemen <KnownHeaders> juga mencantumkan header tersebut. Tujuan Elemen <KnownHeaders> dapat berisi superset dari item yang tercantum dalam crit. Hanya perlu semua header yang tercantum di crit dicantumkan dalam <KnownHeaders>. Header yang ditemukan kebijakan di crit yang tidak tercantum dalam <KnownHeaders> menyebabkan kebijakan VerifyJWT gagal.

Anda juga dapat mengonfigurasi kebijakan VerifyJWT untuk mengabaikan header crit dengan menyetel elemen <IgnoreCriticalHeaders> ke true.

Default T/A
Kehadiran Opsional
Jenis Array string yang dipisahkan koma
Nilai yang valid Baik array maupun nama variabel yang berisi array.

&lt;PublicKey/Certificate&gt;

<PublicKey>
   <Certificate ref="signed_public.cert"/>
</PublicKey>
-or-
<PublicKey>
    <Certificate>
    -----BEGIN CERTIFICATE-----
    cert data
    -----END CERTIFICATE-----
    </Certificate>
</PublicKey>

Menentukan sertifikat bertanda tangan yang digunakan untuk memverifikasi tanda tangan di JWT. Gunakan atribut ref untuk meneruskan sertifikat yang ditandatangani dalam variabel alur, atau menentukan sertifikat yang dienkode ke PEM secara langsung. Hanya gunakan jika algoritmanya adalah salah satu dari RS256/RS384/RS512, PS256/PS384/PS512, atau ES256/ES384/ES512.

Default T/A
Kehadiran Untuk memverifikasi JWT yang ditandatangani dengan algoritma RSA, Anda harus menggunakan Sertifikat, JWKS, atau Elemen nilai.
Jenis String
Nilai yang valid Variabel aliran atau string.

&lt;PublicKey/JWKS&gt;

<!-- Specify the JWKS. -->
<PublicKey>
   <JWKS>jwks-value-here</JWKS>
</PublicKey>

or:

<!-- Specify a variable containing the JWKS. -->
<PublicKey>
   <JWKS ref="public.jwks"/>
</PublicKey>

or:

<!-- Specify a public URL that returns the JWKS.
The URL is static, meaning you cannot set it using a variable. -->
<PublicKey>
   <JWKS uri="jwks-url"/>
</PublicKey>

Menentukan nilai dalam format JWKS (RFC 7517) yang berisi satu set kunci publik. Gunakan hanya jika algoritmanya adalah salah satu dari RS256/RS384/RS512, PS256/PS384/PS512, atau ES256/ES384/ES512.

Jika JWT masuk membawa ID kunci yang ada di rangkaian JWKS, maka kebijakan tersebut akan menggunakan kunci publik yang benar untuk memverifikasi tanda tangan JWT. Untuk detailnya tentang fitur ini, lihat Menggunakan JSON Web Key Set (JWKS) untuk memverifikasi JWT.

Jika Anda mengambil nilai dari URL publik, Edge akan meng-cache JWKS selama 300 detik. Saat cache berakhir, Edge mengambil JWKS lagi.

Default T/A
Kehadiran Untuk memverifikasi JWT menggunakan algoritma RSA, Anda harus menggunakan Sertifikat, JWKS, atau Elemen nilai.
Jenis String
Nilai yang valid Variabel alur, nilai string, atau URL.

&lt;PublicKey/Value&gt;

<PublicKey>
   <Value ref="public.publickeyorcert"/>
</PublicKey>
-or-
<PublicKey>
    <Value>
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW
    Q0UrCw5c0+Y707KX3PpXkZGbtTT4nvU1jC0d1lHV8MfUyRXmpmnNxJHAC2F73IyN
    C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n
    Xn/Bs2UbbLlKP5Q1HPxewUDEh0gVMqz9wdIGwH1pPxKvd3NltYGfPsUQovlof3l2
    ALvO7i5Yrm96kknfFEWf1EjmCCKvz2vjVbBb6mp1ZpYfc9MOTZVpQcXSbzb/BWUo
    ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx
    DQIDAQAB
    -----END PUBLIC KEY-----
    </Value>
</PublicKey>

Menentukan kunci publik atau sertifikat publik yang digunakan untuk memverifikasi tanda tangan di JWT. Gunakan atribut ref untuk meneruskan kunci/sertifikat dalam variabel flow, atau menentukan kunci yang dienkode ke PEM secara langsung. Gunakan hanya bila algoritmenya adalah salah satu dari RS256/RS384/RS512, PS256/PS384/PS512, atau ES256/ES384/ES512.

Default T/A
Kehadiran Untuk memverifikasi JWT yang ditandatangani dengan algoritma RSA, Anda harus menggunakan Sertifikat, JWKS, atau Elemen nilai.
Jenis String
Nilai yang valid Variabel aliran atau string.

&lt;SecretKey/Value&gt;

<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.your-variable-name"/>
</SecretKey>

Memberikan kunci rahasia yang digunakan untuk memverifikasi atau menandatangani token dengan algoritma HMAC. Hanya gunakan jika algoritmanya adalah salah satu dari HS256, HS384, HS512..

Default T/A
Kehadiran Diperlukan untuk algoritma HMAC.
Jenis String
Nilai yang valid

Untuk encoding, nilai yang valid adalah hex, base16, base64, atau base64url. Nilai encoding hex dan base16 adalah sinonim.

Gunakan atribut ref untuk meneruskan kunci dalam variabel flow.

Catatan: Jika variabel flow, variabel tersebut harus memiliki awalan "pribadi". Contoh, private.mysecret

&lt;Source&gt;

<Source>jwt-variable</Source>

Jika ada, tentukan variabel flow yang diharapkan oleh kebijakan untuk menemukan JWT yang memverifikasi.

Default request.header.authorization (Lihat catatan di atas untuk mengetahui informasi penting tentang {i>default<i}).
Kehadiran Opsional
Jenis String
Nilai yang valid Nama variabel aliran Edge.

&lt;Subject&gt;

<Subject>subject-string-here</Subject>

Kebijakan ini memverifikasi bahwa subjek di JWT cocok dengan string yang ditentukan dalam kebijakan konfigurasi Anda. Klaim ini mengidentifikasi atau membuat pernyataan tentang subjek JWT. Ini adalah salah satu dari kumpulan klaim standar yang disebutkan dalam RFC7519.

Default T/A
Kehadiran Opsional
Jenis String
Nilai yang valid Nilai apa pun yang mengidentifikasi subjek secara unik.

&lt;TimeAllowance&gt;

<TimeAllowance>120s</TimeAllowance>

"Masa tenggang" selama beberapa waktu. Misalnya, jika alokasi waktu dikonfigurasi menjadi 60 detik, maka JWT yang sudah tidak berlaku akan dianggap masih valid selama 60 detik setelah masa berlaku yang dinyatakan. Tujuan {i>not-before-time<i} akan dievaluasi dengan cara yang sama. Setelan defaultnya adalah 0 detik (tanpa masa tenggang).

Default 0 detik (tanpa masa tenggang)
Kehadiran Opsional
Jenis String
Nilai yang valid Nilai atau referensi ke variabel alur yang berisi nilai. Rentang waktu dapat ditentukan sebagai berikut:
  • dtk = detik
  • m = menit
  • h = jam
  • d = hari

Variabel flow

Setelah berhasil, kebijakan Verifikasi JWT dan Dekode JWT akan ditetapkan variabel konteks sesuai dengan pola ini:

jwt.{policy_name}.{variable_name}

Misalnya, jika nama kebijakan adalah jwt-parse-token , kebijakan akan menyimpan subjek yang ditentukan dalam JWT ke variabel konteks bernama jwt.jwt-parse-token.decoded.claim.sub. (Untuk kompatibilitas mundur, fitur ini juga akan tersedia di jwt.jwt-parse-token.claim.subject)

Nama variabel Deskripsi
claim.audience Klaim audiens JWT. Nilai ini dapat berupa string atau array string.
claim.expiry Tanggal/waktu habis masa berlaku, dinyatakan dalam milidetik sejak epoch.
claim.issuedat Tanggal token dikeluarkan, dinyatakan dalam milidetik sejak epoch.
claim.issuer Klaim penerbit JWT.
claim.notbefore Jika JWT menyertakan klaim {i> nbf<i}, variabel ini akan berisi nilai, yang diekspresikan dalam milidetik sejak epoch.
claim.subject Klaim subjek JWT.
claim.name Nilai klaim yang dinamai (standar atau tambahan) dalam payload. Salah satunya akan ditetapkan untuk setiap klaim dalam payload.
decoded.claim.name Nilai JSON yang dapat diuraikan dari klaim bernama (standar atau tambahan) dalam payload. Satu variabel ditetapkan untuk setiap klaim dalam payload. Misalnya, Anda dapat menggunakan decoded.claim.iat untuk mengambil waktu diterbitkan pada JWT, dinyatakan dalam detik sejak epoch. Sementara Anda dapat juga menggunakan variabel alur claim.name, ini adalah variabel yang direkomendasikan untuk digunakan mengakses klaim.
decoded.header.name Nilai header yang dapat diurai JSON dalam payload. Satu variabel ditetapkan untuk setiap {i>header<i} dalam {i>payload<i}. Meskipun Anda juga dapat menggunakan variabel flow header.name, variabel ini adalah variabel yang direkomendasikan untuk mengakses {i>header<i}.
expiry_formatted Tanggal/waktu habis masa berlaku, diformat sebagai string yang dapat dibaca manusia. Contoh: 2017-09-28T21:30:45.000+0000
header.algorithm Algoritma penandatanganan yang digunakan di JWT. Misalnya, RS256, HS384, dan sebagainya. Lihat Parameter Header(Algoritma) untuk mengetahui informasi selengkapnya.
header.kid ID Kunci, jika ditambahkan saat JWT dibuat. Lihat juga "Menggunakan Kumpulan Kunci Web JSON (JWKS)" pada JWT ringkasan kebijakan untuk memverifikasi JWT. Lihat Parameter Header(Key ID) untuk mengetahui informasi selengkapnya.
header.type Akan ditetapkan ke JWT.
header.name Nilai header bernama (standar atau tambahan). Salah satunya akan ditetapkan untuk setiap {i>header<i} tambahan di bagian {i> header<i} JWT.
header-json Header dalam format JSON.
is_expired benar atau salah
payload-claim-names Array klaim yang didukung oleh JWT.
payload-json
Payload dalam format JSON.
seconds_remaining Jumlah detik sebelum token berakhir. Jika masa berlaku token telah berakhir, angkanya akan negatif.
time_remaining_formatted Sisa waktu sebelum token akan habis masa berlakunya, diformat sebagai string yang dapat dibaca manusia. Contoh: 00:59:59.926
valid Dalam kasus VerifyJWT, variabel ini akan bernilai benar ketika tanda tangan diverifikasi, dan waktu saat ini adalah sebelum masa berlaku token habis, dan setelah nilai token {i>notBefore<i}, jika tersedia. Jika tidak, flag akan bernilai salah.

Dalam kasus DecodeJWT, variabel ini belum ditetapkan.

Referensi error

Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan dan variabel kesalahan yang disetel oleh Edge saat kebijakan ini memicu error. Informasi ini penting untuk diketahui apakah Anda mengembangkan aturan kesalahan untuk menangani kesalahan. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani kesalahan.

Error runtime

Error ini dapat terjadi saat kebijakan dieksekusi.

Kode kesalahan Status HTTP Terjadi saat
steps.jwt.AlgorithmInTokenNotPresentInConfiguration 401 Terjadi saat kebijakan verifikasi memiliki beberapa algoritma.
steps.jwt.AlgorithmMismatch 401 Algoritme yang ditentukan dalam kebijakan Buat tidak cocok dengan yang diharapkan dalam kebijakan Verifikasi. Algoritma yang ditentukan harus cocok.
steps.jwt.FailedToDecode 401 Kebijakan tidak dapat mendekode JWT. JWT mungkin rusak.
steps.jwt.GenerationFailed 401 Kebijakan tidak dapat menghasilkan JWT.
steps.jwt.InsufficientKeyLength 401 Untuk kunci yang berukuran kurang dari 32 byte untuk algoritma HS256, kurang dari 48 byte untuk algoritma HS386, dan kurang dari 64 byte untuk algoritma HS512.
steps.jwt.InvalidClaim 401 Karena klaim atau klaim tidak cocok, atau ketidakcocokan header atau header tidak ada.
steps.jwt.InvalidCurve 401 Kurva yang ditentukan oleh kunci tidak valid untuk algoritma Kurva Eliptis.
steps.jwt.InvalidJsonFormat 401 JSON yang tidak valid ditemukan di header atau payload.
steps.jwt.InvalidToken 401 Error ini terjadi saat verifikasi tanda tangan JWT gagal.
steps.jwt.JwtAudienceMismatch 401 Klaim audiens gagal pada verifikasi token.
steps.jwt.JwtIssuerMismatch 401 Klaim penerbit gagal pada verifikasi token.
steps.jwt.JwtSubjectMismatch 401 Klaim subjek gagal pada verifikasi token.
steps.jwt.KeyIdMissing 401 Kebijakan Verifikasi menggunakan JWKS sebagai sumber untuk kunci publik, tetapi JWT yang ditandatangani tidak menyertakan properti kid di header.
steps.jwt.KeyParsingFailed 401 Kunci publik tidak dapat diuraikan dari informasi kunci yang diberikan.
steps.jwt.NoAlgorithmFoundInHeader 401 Terjadi saat JWT tidak berisi header algoritma.
steps.jwt.NoMatchingPublicKey 401 Kebijakan Verifikasi menggunakan JWKS sebagai sumber untuk kunci publik, tetapi kid dalam JWT yang ditandatangani tidak tercantum di JWKS.
steps.jwt.SigningFailed 401 Dalam GenerateJWT, untuk kunci yang kurang dari ukuran minimum untuk algoritma HS384 atau HS512
steps.jwt.TokenExpired 401 Kebijakan ini akan mencoba memverifikasi token yang sudah habis masa berlakunya.
steps.jwt.TokenNotYetValid 401 Token belum valid.
steps.jwt.UnhandledCriticalHeader 401 Header yang ditemukan oleh kebijakan Verifikasi JWT di header crit tidak tercantum di KnownHeaders.
steps.jwt.UnknownException 401 Terjadi pengecualian yang tidak diketahui.
steps.jwt.WrongKeyType 401 Jenis kunci yang ditentukan salah. Misalnya, jika Anda menentukan kunci RSA untuk algoritma Kurva Elliptik, atau kunci kurva untuk algoritma RSA.

Error saat deployment

Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.

Nama error Penyebab Perbaiki
InvalidNameForAdditionalClaim Deployment akan gagal jika klaim yang digunakan dalam elemen turunan <Claim> dari elemen <AdditionalClaims> adalah salah satu nama yang terdaftar berikut: kid, iss, sub, aud, iat, exp, nbf, atau jti.
InvalidTypeForAdditionalClaim Jika klaim yang digunakan dalam elemen turunan <Claim> elemen <AdditionalClaims> bukan jenis string, number, boolean, atau map, deployment akan gagal.
MissingNameForAdditionalClaim Jika nama klaim tidak ditentukan dalam elemen turunan <Claim> dari elemen <AdditionalClaims>, deployment akan gagal.
InvalidNameForAdditionalHeader Error ini terjadi jika nama klaim yang digunakan dalam elemen turunan <Claim> dari elemen <AdditionalClaims> adalah alg atau typ.
InvalidTypeForAdditionalHeader Jika jenis klaim yang digunakan dalam elemen turunan <Claim> dari elemen <AdditionalClaims> bukan jenis string, number, boolean, atau map, deployment akan gagal.
InvalidValueOfArrayAttribute Error ini terjadi jika nilai atribut array dalam elemen turunan <Claim> dari elemen <AdditionalClaims> tidak ditetapkan ke true atau false.
InvalidValueForElement Jika nilai yang ditentukan dalam elemen <Algorithm> bukan nilai yang didukung, deployment akan gagal.
MissingConfigurationElement Error ini akan terjadi jika elemen <PrivateKey> tidak digunakan dengan algoritma kelompok RSA atau elemen <SecretKey> tidak digunakan dengan algoritma Keluarga HS.
InvalidKeyConfiguration Jika elemen turunan <Value> tidak ditetapkan dalam elemen <PrivateKey> atau <SecretKey>, deployment akan gagal.
EmptyElementForKeyConfiguration Jika atribut referensi elemen turunan <Value> dari elemen <PrivateKey> atau <SecretKey> kosong atau tidak ditentukan, deployment akan gagal.
InvalidConfigurationForVerify Error ini terjadi jika elemen <Id> ditentukan dalam elemen <SecretKey>.
InvalidEmptyElement Error ini terjadi jika elemen <Source> kebijakan Verify JWT kosong. Jika ada, elemen tersebut harus ditentukan dengan nama variabel alur Edge.
InvalidPublicKeyValue Jika nilai yang digunakan dalam elemen turunan <JWKS> elemen <PublicKey> tidak menggunakan format yang valid seperti yang ditetapkan dalam RFC 7517, deployment akan gagal.
InvalidConfigurationForActionAndAlgorithm Jika elemen <PrivateKey> digunakan dengan algoritma Keluarga HS atau elemen <SecretKey> digunakan dengan algoritma Keluarga RSA, deployment akan gagal.

Variabel kesalahan

Variabel ini ditetapkan saat terjadi error runtime. Untuk informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.

Variabel Di mana Contoh
fault.name="fault_name" fault_name adalah nama kesalahan, seperti yang tercantum dalam tabel Error runtime di atas. Nama kesalahan adalah bagian terakhir dari kode kesalahan. fault.name Matches "TokenExpired"
JWT.failed Semua kebijakan JWT menetapkan variabel yang sama jika terjadi kegagalan. JWT.failed = true

Contoh respons error

Kode Kesalahan Kebijakan JWT

Untuk penanganan error, praktik terbaiknya adalah menangkap bagian errorcode dari error yang dihasilkan. Jangan mengandalkan teks di faultstring, karena dapat berubah.

Contoh aturan kesalahan

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>