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 akan mengekstrak klaim ke dalam variabel konteks sehingga kebijakan atau kondisi berikutnya dapat memeriksa nilai tersebut untuk membuat keputusan otorisasi atau pemilihan rute. Lihat ringkasan kebijakan JWS dan JWT untuk pengantar yang mendetail.
Saat kebijakan ini dijalankan, Edge akan memverifikasi tanda tangan JWT, dan memverifikasi bahwa JWT valid sesuai dengan masa berlaku dan bukan waktu sebelumnya jika ada. Secara opsional, kebijakan ini juga dapat memverifikasi nilai klaim spesifik pada JWT, seperti subjek, penerbit, audiens, atau nilai klaim tambahan.
Jika JWT terverifikasi dan valid, semua klaim yang ada di dalam JWT diekstrak ke variabel konteks untuk digunakan oleh kebijakan atau kondisi berikutnya, dan permintaan tersebut diizinkan untuk dilanjutkan. Jika tanda tangan JWT tidak dapat diverifikasi atau jika JWT tidak valid karena salah satu stempel waktu, semua pemrosesan akan berhenti dan error akan ditampilkan dalam respons.
Untuk mempelajari bagian-bagian JWT dan caranya dienkripsi dan ditandatangani, lihat RFC7519.
Video
Tonton video singkat untuk mempelajari cara memverifikasi tanda tangan di JWT.
Contoh
- Memverifikasi JWT yang ditandatangani dengan algoritma HS256
- Memverifikasi JWT yang ditandatangani dengan algoritma RS256
Verifikasi JWT yang ditandatangani dengan algoritma HS256
Kebijakan contoh ini memverifikasi JWT yang ditandatangani dengan algoritma enkripsi HS256, HMAC menggunakan checksum SHA-256. JWT diteruskan dalam permintaan proxy menggunakan parameter formulir bernama jwt
. Kunci tersebut terdapat dalam variabel bernama private.secretkey
.
Lihat video di atas untuk mengetahui contoh lengkap, termasuk cara mengajukan permintaan terkait kebijakan.
Konfigurasi kebijakan mencakup informasi yang dibutuhkan Edge untuk mendekode dan mengevaluasi JWT, seperti tempat menemukan JWT (dalam variabel flow yang ditentukan dalam elemen Source), algoritma penandatanganan yang diperlukan, tempat menemukan kunci rahasia (disimpan dalam variabel flow Edge, yang dapat diambil dari Edge KVM, misalnya), dan serangkaian klaim yang diperlukan beserta nilainya.
<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 ini menulis output-nya ke variabel konteks sehingga kebijakan atau kondisi berikutnya dalam proxy API dapat memeriksa nilai tersebut. Lihat Variabel flow untuk mengetahui daftar variabel yang ditetapkan oleh kebijakan ini.
Memverifikasi JWT yang ditandatangani dengan algoritma RS256
Kebijakan contoh ini memverifikasi JWT yang ditandatangani dengan algoritma RS256. Untuk memverifikasi, Anda harus 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 mengetahui contoh lengkap, termasuk cara mengajukan permintaan terkait kebijakan.
Lihat referensi Elemen untuk mengetahui detail tentang persyaratan dan opsi untuk setiap elemen dalam contoh kebijakan ini.
<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 dengan kunci publik yang disediakan.
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 dianggap tidak valid, meskipun tanda tangan dapat diverifikasi, karena klaim "sub" yang disertakan dalam JWT tidak cocok dengan nilai yang diperlukan dari elemen "Subjek" sebagaimana yang ditetapkan dalam konfigurasi kebijakan.
Kebijakan ini menulis output-nya ke variabel konteks sehingga kebijakan atau kondisi berikutnya dalam proxy API dapat memeriksa nilai tersebut. Lihat Variabel flow untuk mengetahui daftar variabel yang ditetapkan oleh kebijakan ini.
Menetapkan elemen utama
Elemen yang Anda gunakan untuk menentukan kunci yang digunakan untuk memverifikasi JWT bergantung pada algoritme yang dipilih, seperti yang ditunjukkan pada tabel berikut:
Algorithm | 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 mengetahui informasi selengkapnya tentang persyaratan utama, lihat Tentang algoritma enkripsi tanda tangan. |
Referensi elemen
Referensi kebijakan menjelaskan elemen dan atribut kebijakan Verify JWT.
Catatan: Konfigurasi akan sedikit berbeda, tergantung algoritma enkripsi yang Anda gunakan. Lihat Contoh untuk mengetahui contoh yang menunjukkan konfigurasi untuk kasus penggunaan tertentu.
Atribut yang berlaku untuk elemen tingkat atas
<VerifyJWT name="JWT" continueOnError="false" enabled="true" async="false">
Atribut berikut bersifat umum untuk semua elemen induk kebijakan.
Atribut | Deskripsi | Default | Kehadiran |
---|---|---|---|
name |
Nama internal kebijakan. Karakter yang dapat digunakan dalam nama dibatasi untuk:
A-Z0-9._\-$ % . Namun, UI pengelolaan Edge menerapkan pembatasan
tambahan, seperti otomatis menghapus karakter yang bukan alfanumerik.
Atau, gunakan elemen |
T/A | Wajib |
continueOnError |
Setel ke false untuk menampilkan error jika kebijakan gagal. Ini adalah perilaku
yang wajar untuk sebagian besar kebijakan.
Setel ke |
false | Opsional |
diaktifkan |
Setel ke true untuk menerapkan kebijakan.
Setel ke |
true | Opsional |
async | Atribut ini sudah tidak digunakan lagi. | false | Tidak digunakan lagi |
<DisplayName>
<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 menghilangkan elemen ini, nilai atribut nama kebijakan akan digunakan. |
Kehadiran | Opsional |
Jenis | String |
<Algorithm>
<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 koma. Misalnya "HS256, HS512" atau "RS256, PS256". Namun, Anda tidak dapat menggabungkan algoritme HS* dengan algoritme lain atau algoritma ES* dengan yang lain karena 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 |
<Audience>
<Audience>audience-here</Audience> or: <Audience ref='variable-name-here'/>
Kebijakan ini akan memverifikasi bahwa klaim audience di JWT cocok dengan nilai yang ditentukan dalam konfigurasi. 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 | String atau variabel alur yang mengidentifikasi audiens. |
<Klaim/Klaim Tambahan>
<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 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. Peta hanyalah sekumpulan pasangan nama/nilai. Nilai untuk klaim jenis ini dapat ditentukan secara eksplisit dalam konfigurasi kebijakan, atau secara tidak langsung melalui referensi ke variabel flow.
Default | T/A |
Kehadiran | Opsional |
Jenis | String, angka, boolean, atau peta |
Array | Tetapkan ke true untuk menunjukkan apakah nilainya adalah array jenis. Default: false |
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 ini sebagai klaim. Jika atribut ref dan nilai klaim eksplisit ditentukan, nilai eksplisitnya adalah nilai 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: false.
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 } } }
<Header/Klaim Tambahan>
<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 nilai/nama klaim tambahan yang ditentukan dan 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. Peta hanyalah sekumpulan pasangan nama/nilai. Nilai untuk klaim jenis ini dapat ditentukan secara eksplisit dalam konfigurasi kebijakan, atau secara tidak langsung melalui referensi ke variabel flow.
Default | T/A |
Kehadiran | Opsional |
Jenis |
String (default), angka, boolean, atau peta. Jenis akan ditetapkan secara default ke String jika tidak ada jenis yang ditentukan. |
Array | Tetapkan ke true untuk menunjukkan apakah nilainya adalah array jenis. Default: false |
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 ini sebagai klaim. Jika atribut ref dan nilai klaim eksplisit ditentukan, nilai eksplisitnya adalah nilai 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: false.
<CustomClaims>
Catatan: Saat ini, elemen CustomClaims disisipkan saat Anda menambahkan kebijakan GenerateJWT baru melalui UI. Elemen ini tidak berfungsi dan diabaikan. Elemen yang benar untuk digunakan adalah <AdditionalClaims>. UI akan diupdate untuk menyisipkan elemen yang benar di lain waktu.
<ID>
<Id>explicit-jti-value-here</Id> -or- <Id ref='variable-name-here'/> -or- <Id/>
Memverifikasi bahwa JWT memiliki klaim jti spesifik. Jika nilai teks dan atribut referensi kosong, kebijakan akan membuat jti yang berisi UUID acak. Klaim ID JWT (jti) adalah ID unik untuk JWT. Untuk mengetahui informasi selengkapnya tentang jti, lihat RFC7519.
Default | T/A |
Kehadiran | Opsional |
Jenis | String, atau referensi. |
Nilai yang valid | String atau nama variabel flow yang berisi ID. |
<IgnoreCriticalHeaders>
<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>
Tetapkan ke false jika Anda ingin kebijakan menampilkan error saat header apa pun yang tercantum dalam header crit JWT tidak tercantum dalam elemen <KnownHeaders>
.
Setel ke true agar 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 mengalami kegagalan pada header yang hilang.
Default | false |
Kehadiran | Opsional |
Jenis | Boolean |
Nilai yang valid | benar atau salah |
<IgnoreIssuedAt>
<IgnoreIssuedAt>true|false</IgnoreIssuedAt>
Tetapkan ke false (salah) jika Anda ingin kebijakan menampilkan error saat JWT berisi klaim iat
(Diterbitkan pada) yang menentukan waktu di masa mendatang.
Setel ke true agar kebijakan mengabaikan iat
selama verifikasi.
Default | false |
Kehadiran | Opsional |
Jenis | Boolean |
Nilai yang valid | benar atau salah |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
Tetapkan ke false jika Anda ingin kebijakan menampilkan error saat variabel yang direferensikan dan ditentukan dalam kebijakan tidak dapat diselesaikan. Tetapkan ke true untuk memperlakukan variabel yang tidak dapat di-resolve sebagai string kosong (null).
Default | false |
Kehadiran | Opsional |
Jenis | Boolean |
Nilai yang valid | benar atau salah |
<Issuer>
<Issuer ref='variable-name-here'/> <Issuer>issuer-string-here</Issuer>
Kebijakan ini akan memverifikasi bahwa penerbit di JWT cocok dengan string yang ditentukan dalam elemen konfigurasi. Klaim yang mengidentifikasi penerbit JWT. Ini adalah salah satu dari serangkaian klaim terdaftar yang disebutkan dalam RFC7519.
Default | T/A |
Kehadiran | Opsional |
Jenis | String, atau referensi |
Nilai yang valid | Mana saja |
<KnownHeaders>
<KnownHeaders>a,b,c</KnownHeaders> or: <KnownHeaders ref=’variable_containing_headers’/>
Kebijakan GenerateJWT menggunakan elemen <CriticalHeaders>
untuk mengisi header crit di JWT. Contoh:
{ “typ: “...”, “alg” : “...”, “crit” : [ “a”, “b”, “c” ], }
Kebijakan VerifyJWT memeriksa header crit di JWT, jika ada, dan untuk setiap header yang tercantum, kebijakan ini akan memeriksa apakah elemen <KnownHeaders>
juga mencantumkan header tersebut. Elemen
<KnownHeaders>
dapat berisi superset item yang tercantum dalam crit.
Hanya perlu bahwa semua header yang tercantum dalam crit dicantumkan dalam elemen <KnownHeaders>
. Header apa pun yang ditemukan kebijakan di crit
yang tidak tercantum di <KnownHeaders>
akan menyebabkan kebijakan VerifyJWT gagal.
Secara opsional, Anda dapat mengonfigurasi kebijakan VerifyJWT untuk mengabaikan header crit dengan menetapkan elemen <IgnoreCriticalHeaders>
ke true
.
Default | T/A |
Kehadiran | Opsional |
Jenis | Array string yang dipisahkan koma |
Nilai yang valid | Baik array atau nama variabel yang berisi array. |
<Kunci Publik/Sertifikat>
<PublicKey> <Certificate ref="signed_public.cert"/> </PublicKey> -or- <PublicKey> <Certificate> -----BEGIN CERTIFICATE----- cert data -----END CERTIFICATE----- </Certificate> </PublicKey>
Menentukan sertifikat yang ditandatangani yang digunakan untuk memverifikasi tanda tangan di JWT. Gunakan atribut ref untuk meneruskan sertifikat yang ditandatangani dalam variabel flow, atau tentukan sertifikat yang dienkode ke PEM secara langsung. Gunakan hanya jika 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 Elemen Sertifikat, JWKS, atau Nilai. |
Jenis | String |
Nilai yang valid | String atau variabel flow. |
<PublicKey/JWKS>
<!-- 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 kumpulan kunci publik. Gunakan hanya jika algoritmenya adalah salah satu dari RS256/RS384/RS512, PS256/PS384/PS512, atau ES256/ES384/ES512.
Jika JWT masuk memiliki ID kunci yang ada dalam kumpulan JWKS, kebijakan akan menggunakan kunci publik yang benar untuk memverifikasi tanda tangan JWT. Untuk mengetahui detail tentang fitur ini, lihat Menggunakan Set Kunci Web JSON (JWKS) untuk memverifikasi JWT.
Jika Anda mengambil nilai dari URL publik, Edge akan menyimpan JWKS dalam cache selama 300 detik. Saat cache berakhir, Edge akan mengambil JWKS lagi.
Default | T/A |
Kehadiran | Untuk memverifikasi JWT menggunakan algoritma RSA, Anda harus menggunakan Elemen nilai, JWKS, atau Sertifikat. |
Jenis | String |
Nilai yang valid | Variabel flow, nilai string, atau URL. |
<PublicKey/Value>
<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 tentukan kunci yang dienkode ke PEM secara langsung. Gunakan hanya jika 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 Elemen Sertifikat, JWKS, atau Nilai. |
Jenis | String |
Nilai yang valid | String atau variabel flow. |
<SecretKey/Value>
<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. Gunakan hanya jika algoritmenya adalah salah satu dari HS256, HS384, HS512..
Default | T/A |
Kehadiran | Diperlukan untuk algoritma HMAC. |
Jenis | String |
Nilai yang valid |
Untuk Gunakan atribut ref untuk meneruskan kunci dalam variabel flow. Catatan: Variabel flow harus memiliki awalan "private". Contoh,
|
<Sumber>
<Source>jwt-variable</Source>
Jika ada, menentukan variabel flow tempat kebijakan mengharapkan JWT ditemukan untuk diverifikasi.
Default | request.header.authorization (Lihat catatan di atas untuk informasi penting
tentang default). |
Kehadiran | Opsional |
Jenis | String |
Nilai yang valid | Nama variabel alur Edge. |
<Subject>
<Subject>subject-string-here</Subject>
Kebijakan ini akan memverifikasi bahwa subjek dalam JWT cocok dengan string yang ditentukan dalam konfigurasi kebijakan. 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. |
<TimeAllowance>
<TimeAllowance>120s</TimeAllowance>
"Masa tenggang" untuk waktu. Misalnya, jika kelonggaran waktu dikonfigurasi menjadi 60 detik, maka JWT yang habis masa berlakunya akan dianggap masih valid, selama 60 detik setelah masa berlaku yang dinyatakan habis. Waktu belum sebelum waktunya akan dievaluasi dengan cara serupa. 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 flow yang berisi nilai. Span waktu dapat ditentukan sebagai berikut:
|
Variabel alur
Setelah berhasil, kebijakan Verify JWT dan Decode JWT menetapkan 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 dalam jwt.jwt-parse-token.claim.subject
)
Nama variabel | Deskripsi |
---|---|
claim.audience |
Klaim audiens JWT. Nilai ini bisa berupa string, atau array string. |
claim.expiry |
Tanggal/waktu habis masa berlaku, yang dinyatakan dalam milidetik sejak epoch. |
claim.issuedat |
Tanggal token diterbitkan, dinyatakan dalam milidetik sejak epoch. |
claim.issuer |
Klaim penerbit JWT. |
claim.notbefore |
Jika JWT menyertakan klaim nbf, variabel ini akan berisi nilai, yang dinyatakan dalam milidetik sejak epoch. |
claim.subject |
Klaim subjek JWT. |
claim.name |
Nilai klaim yang disebutkan (standar atau tambahan) dalam payload. Salah satunya akan ditetapkan untuk setiap klaim dalam payload. |
decoded.claim.name |
Nilai yang dapat diuraikan JSON dari klaim yang disebutkan (standar atau tambahan) dalam payload. Satu variabel ditetapkan untuk setiap klaim dalam payload. Misalnya, Anda dapat menggunakan decoded.claim.iat untuk mengambil waktu penerbitan JWT, yang dinyatakan dalam detik sejak epoch. Meskipun Anda
juga dapat menggunakan variabel alur claim.name , variabel ini adalah
variabel yang direkomendasikan untuk mengakses klaim. |
decoded.header.name |
Nilai header yang dapat diuraikan JSON dalam payload. Satu variabel ditetapkan untuk setiap header dalam payload. Meskipun Anda juga dapat menggunakan variabel alur header.name ,
ini adalah variabel yang direkomendasikan untuk mengakses header. |
expiry_formatted |
Tanggal/waktu habis masa berlaku, yang diformat sebagai string yang dapat dibaca manusia. Contoh: 2017-09-28T21:30:45.000+0000 |
header.algorithm |
Algoritma penandatanganan yang digunakan pada JWT. Misalnya, RS256, HS384, dan sebagainya. Lihat Parameter Header(Algoritme) untuk mengetahui informasi selengkapnya. |
header.kid |
ID Kunci, jika ditambahkan saat JWT dibuat. Lihat juga "Menggunakan Kumpulan Kunci Web JSON (JWKS)" di ringkasan kebijakan JWT untuk memverifikasi JWT. Lihat Parameter Header(Key ID) untuk informasi selengkapnya. |
header.type |
Akan ditetapkan ke JWT . |
header.name |
Nilai header yang diberi nama (standar atau tambahan). Salah satunya akan ditetapkan untuk setiap header tambahan di bagian header 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 masa berlaku token berakhir. Jika masa berlaku token habis, angka ini akan negatif. |
time_remaining_formatted |
Waktu yang tersisa sebelum token akan berakhir, yang diformat sebagai string yang dapat dibaca manusia. Contoh: 00:59:59.926 |
valid |
Dalam kasus VerifyJWT, variabel ini akan bernilai benar (true) saat tanda tangan diverifikasi, dan waktu saat ini adalah sebelum masa berlaku token, dan setelah nilai notBefore token, jika ada. Sebaliknya, 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 .
|
build |
InvalidTypeForAdditionalClaim |
Jika klaim yang digunakan dalam elemen turunan <Claim> elemen <AdditionalClaims> bukan jenis string , number , boolean , atau map , deployment akan gagal.
|
build |
MissingNameForAdditionalClaim |
Jika nama klaim tidak ditentukan dalam elemen turunan <Claim> dari elemen <AdditionalClaims> , deployment akan gagal.
|
build |
InvalidNameForAdditionalHeader |
Error ini terjadi jika nama klaim yang digunakan dalam elemen turunan <Claim> dari elemen <AdditionalClaims> adalah alg atau typ .
|
build |
InvalidTypeForAdditionalHeader |
Jika jenis klaim yang digunakan dalam elemen turunan <Claim> dari elemen <AdditionalClaims> bukan jenis string , number , boolean , atau map , deployment akan gagal.
|
build |
InvalidValueOfArrayAttribute |
Error ini terjadi jika nilai atribut array dalam elemen turunan <Claim> dari elemen <AdditionalClaims> tidak ditetapkan ke true atau false .
|
build |
InvalidValueForElement |
Jika nilai yang ditentukan dalam elemen <Algorithm> bukan nilai yang didukung, deployment akan gagal.
|
build |
MissingConfigurationElement |
Error ini akan terjadi jika elemen <PrivateKey> tidak digunakan dengan
algoritma kelompok RSA atau elemen <SecretKey> tidak digunakan dengan
algoritma Keluarga HS.
|
build |
InvalidKeyConfiguration |
Jika elemen turunan <Value> tidak ditetapkan dalam elemen <PrivateKey> atau <SecretKey> , deployment akan gagal.
|
build |
EmptyElementForKeyConfiguration |
Jika atribut referensi elemen turunan <Value> dari elemen <PrivateKey> atau <SecretKey> kosong atau tidak ditentukan, deployment akan gagal.
|
build |
InvalidConfigurationForVerify |
Error ini terjadi jika elemen <Id> ditentukan dalam elemen
<SecretKey> .
|
build |
InvalidEmptyElement |
Error ini terjadi jika elemen <Source> kebijakan Verify JWT kosong. Jika ada, elemen tersebut harus ditentukan dengan nama variabel alur Edge.
|
build |
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.
|
build |
InvalidConfigurationForActionAndAlgorithm |
Jika elemen <PrivateKey> digunakan dengan algoritma Keluarga HS atau elemen <SecretKey> digunakan dengan algoritma Keluarga RSA, deployment akan gagal.
|
build |
Variabel kesalahan
Variabel ini ditetapkan saat terjadi error runtime. Untuk informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.
Variabel | Dari 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
Untuk penanganan error, praktik terbaiknya adalah menjebak bagian errorcode
dari respons
error. 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>