Kebijakan VerifyJWT

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Kebijakan VerifyJWT memverifikasi JWT bertanda tangan atau mendekripsi dan memverifikasi JWT terenkripsi yang diterima dari klien atau sistem lain. Kebijakan ini juga mengekstrak klaim ke dalam variabel konteks sehingga kebijakan atau kondisi berikutnya dapat memeriksa nilai tersebut untuk membuat keputusan otorisasi atau perutean. Lihat Ringkasan kebijakan JWS dan JWT untuk pengantar mendetail.

Saat kebijakan ini dijalankan, dalam kasus JWT bertanda tangan, Apigee memverifikasi tanda tangan JWT menggunakan kunci verifikasi yang diberikan. Dalam kasus JWT terenkripsi, Apigee mendekripsi JWT menggunakan kunci dekripsi. Dalam kedua kasus tersebut, Apigee selanjutnya memverifikasi bahwa JWT valid sesuai dengan waktu habis masa berlaku dan waktu sebelum berlaku jika ada. Kebijakan ini juga dapat memverifikasi nilai klaim tertentu pada JWT, seperti subjek, penerbit, audiens, atau nilai klaim tambahan.

Jika JWT diverifikasi dan valid, semua klaim yang ada dalam JWT akan diekstrak ke dalam variabel konteks untuk digunakan oleh kebijakan atau kondisi berikutnya, dan permintaan diizinkan untuk dilanjutkan. Jika tanda tangan JWT tidak dapat diverifikasi atau jika JWT tidak valid karena salah satu stempel waktunya, semua pemrosesan akan berhenti dan error akan ditampilkan dalam respons.

Apakah kebijakan memverifikasi JWT yang ditandatangani atau dienkripsi bergantung pada elemen yang Anda gunakan untuk menentukan algoritma yang memverifikasi JWT:

Kebijakan ini adalah Kebijakan standar dan dapat di-deploy ke jenis lingkungan apa pun. Untuk mengetahui informasi tentang jenis dan ketersediaan kebijakan dengan setiap jenis lingkungan, lihat Jenis kebijakan.

Untuk mempelajari bagian-bagian JWT dan cara JWT dienkripsi dan ditandatangani, lihat RFC7519.

Memverifikasi JWT Bertanda Tangan

Bagian ini menjelaskan cara memverifikasi JWT bertanda tangan. Untuk JWT yang ditandatangani, gunakan elemen <Algorithm> untuk menentukan algoritma penandatanganan kunci.

Contoh untuk JWT yang ditandatangani

Contoh berikut menggambarkan cara memverifikasi JWT bertanda tangan.

Algoritma HS256

Contoh kebijakan 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 dimuat dalam variabel bernama private.secretkey. Tonton video di atas untuk melihat contoh lengkap, termasuk cara membuat permintaan ke kebijakan.

Konfigurasi kebijakan mencakup informasi yang diperlukan Apigee untuk mendekode dan mengevaluasi JWT, seperti tempat menemukan JWT (dalam variabel alur yang ditentukan dalam elemen Source), algoritma penandatanganan yang diperlukan, tempat menemukan kunci rahasia (disimpan dalam variabel alur Apigee, yang dapat diambil dari KVM Apigee, misalnya), dan serangkaian klaim yang diperlukan serta 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 menulis outputnya ke variabel konteks sehingga kebijakan atau kondisi berikutnya di proxy API dapat memeriksa nilai tersebut. Lihat Variabel alur untuk mengetahui daftar variabel yang ditetapkan oleh kebijakan ini.

Algoritma RS256

Contoh kebijakan ini memverifikasi JWT yang ditandatangani dengan algoritma RS256. Untuk memverifikasi, Anda harus memberikan kunci publik. JWT diteruskan dalam permintaan proxy menggunakan parameter formulir bernama jwt. Kunci publik terdapat dalam variabel bernama public.publickey. Tonton video di atas untuk melihat contoh lengkap, termasuk cara membuat permintaan ke 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 dapat diverifikasi dengan kunci publik yang diberikan.

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 tangannya dapat diverifikasi, karena klaim "sub" yang disertakan dalam JWT tidak cocok dengan nilai yang diperlukan dari elemen "Subject" seperti yang ditentukan dalam konfigurasi kebijakan.

Kebijakan menulis outputnya ke variabel konteks sehingga kebijakan atau kondisi berikutnya di proxy API dapat memeriksa nilai tersebut. Lihat Variabel alur untuk mengetahui daftar variabel yang ditetapkan oleh kebijakan ini.

Contoh di atas menggunakan elemen <Algorithm>, sehingga memverifikasi JWT yang ditandatangani. Elemen <PrivateKey> menentukan kunci yang digunakan untuk menandatangani JWT. Ada juga elemen penting lainnya. Algoritma yang Anda gunakan bergantung pada algoritma yang ditentukan oleh nilai <Algorithm>, seperti yang dijelaskan di bagian berikutnya.

Menetapkan elemen kunci untuk memverifikasi JWT yang ditandatangani

Elemen berikut menentukan kunci yang digunakan untuk memverifikasi JWT yang ditandatangani:

Elemen yang Anda gunakan bergantung 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 mengetahui informasi selengkapnya tentang persyaratan utama, lihat Tentang algoritma enkripsi tanda tangan.

Memverifikasi JWT terenkripsi

Bagian ini menjelaskan cara memverifikasi JWT terenkripsi. Untuk JWT terenkripsi, gunakan elemen <Algorithms> untuk menentukan algoritma penandatanganan kunci dan konten.

Contoh JWT terenkripsi

Contoh berikut menunjukkan cara memverifikasi JWT terenkripsi (dengan <Type> ditetapkan ke Encrypted), yang:

  • Kunci dienkripsi dengan algoritma RSA-OAEP-256.
  • Konten dienkripsi dengan algoritma A128GCM.
<VerifyJWT name="vjwt-1">
  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <Type>Encrypted</Type> 
  <PrivateKey>
    <Value ref="private.rsa_privatekey"/>
  </PrivateKey>
  <Subject>subject@example.com</Subject>
  <Issuer>urn://apigee</Issuer>
  <AdditionalHeaders>
    <Claim name="moniker">Harvey</Claim>
  </AdditionalHeaders>
  <TimeAllowance>30s</TimeAllowance>
  <Source>input_var</Source>
</VerifyJWT>

Contoh di atas menggunakan elemen <Algorithms>, sehingga memverifikasi JWT terenkripsi. Elemen <PrivateKey> menentukan kunci yang akan digunakan untuk mendekripsi JWT. Ada juga elemen penting lainnya. Algoritma yang Anda gunakan bergantung pada algoritma yang ditentukan oleh nilai <Algorithms>, seperti yang dijelaskan di bagian berikutnya.

Menetapkan elemen kunci untuk memverifikasi JWT terenkripsi

Elemen berikut menentukan kunci yang digunakan untuk memverifikasi JWT terenkripsi:

Elemen yang Anda gunakan bergantung pada algoritma enkripsi kunci yang dipilih, seperti yang ditunjukkan dalam tabel berikut:

Algoritma Elemen utama
RSA-OAEP-256 
<PrivateKey>
  <Value ref="private.rsa_privatekey"/>
</PrivateKey>

Catatan: Variabel yang Anda tentukan harus di-resolve ke kunci pribadi RSA dalam bentuk yang dienkode PEM.
  • ECDH-ES
  • ECDH-ES+A128KW
  • ECDH-ES+A192KW
  • ECDH-ES+A256KW
 
<PrivateKey>
  <Value ref="private.ec_privatekey"/>
</PrivateKey>

Catatan: Variabel yang Anda tentukan harus di-resolve ke kunci pribadi kurva elips dalam bentuk yang dienkode PEM.
  • A128KW
  • A192KW
  • A256KW
  • A128GCMKW
  • A192GCMKW
  • A256GCMKW
 
<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.flow-variable-name-here"/>
</SecretKey>
  • PBES2-HS256+A128KW
  • PBES2-HS384+A192KW
  • PBES2-HS512+A256KW
 
<PasswordKey>
  <Value ref="private.password-key"/>
  <SaltLength>
  <PBKDF2Iterations>
</PasswordKey>
dir 
<DirectKey>
  <Value encoding="base16|hex|base64|base64url" ref="private.directkey"/>
</DirectKey>

Untuk mengetahui informasi selengkapnya tentang persyaratan kunci, lihat Tentang algoritma enkripsi tanda tangan.

Referensi elemen

Referensi kebijakan menjelaskan elemen dan atribut kebijakan Verify JWT.

Catatan: Konfigurasi akan sedikit berbeda, bergantung pada algoritma enkripsi yang Anda gunakan. Lihat Contoh untuk contoh yang menunjukkan konfigurasi untuk kasus penggunaan tertentu.

Atribut yang berlaku untuk elemen tingkat teratas

<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 menjadi: A-Z0-9._\-$ %. Namun, UI Apigee menerapkan batasan tambahan, seperti menghapus karakter yang bukan alfanumerik secara otomatis.

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

 T/A Wajib
continueOnError Disetel ke false untuk menampilkan error saat kebijakan gagal. Hal ini adalah perilaku yang diharapkan untuk sebagian besar kebijakan.

Setel ke true agar eksekusi alur berlanjut meskipun setelah kebijakan gagal.

 false Opsional
diaktifkan Setel ke true untuk menerapkan kebijakan.

Setel ke false untuk "menonaktifkan" kebijakan. Kebijakan tidak akan diterapkan meskipun tetap terlampir pada alur.

 true Opsional
asinkron Atribut ini 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 bahasa alami yang berbeda.

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

<Algorithm>

<Algorithm>HS256</Algorithm>

Menentukan algoritma kriptografi yang digunakan untuk memverifikasi token. Gunakan elemen <Algorithm> untuk memverifikasi JWT yang ditandatangani.

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 algoritma HS* dengan algoritma lainnya atau algoritma ES* dengan algoritma lainnya karena algoritma tersebut 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

<Algorithms>

<Algorithms>
    <Key>key-algorithm</Key>
    <Content>content-algorithm</Content>
</Algorithm>

Gunakan elemen <Algorithms> untuk memverifikasi JWT terenkripsi. Elemen ini menentukan algoritma kriptografi untuk enkripsi kunci yang harus digunakan saat JWT terenkripsi dibuat. Secara opsional, algoritma untuk enkripsi konten juga dapat ditentukan.

Default T/A
Kehadiran Diperlukan saat memverifikasi JWT terenkripsi
Jenis Kompleks

Elemen turunan dari <Algorithms>

Tabel berikut memberikan deskripsi umum tentang elemen turunan dari <Algorithms>:

Elemen Turunan Wajib? Deskripsi
<Key> Wajib Menentukan algoritma enkripsi untuk kunci.
<Content> Opsional Menentukan algoritma enkripsi untuk konten.

Verifikasi akan gagal jika:

  • Algoritma yang ditegaskan dalam properti alg di header JWT terenkripsi berbeda dengan algoritma enkripsi kunci yang ditentukan di sini dalam elemen <Key>.
  • Kebijakan menentukan elemen <Content>, dan algoritma yang ditegaskan dalam properti enc di header JWT terenkripsi berbeda dengan yang ditentukan dalam elemen <Content>.

Misalnya, untuk memverifikasi JWT terenkripsi dan memeriksa bahwa algoritma kunci adalah RSA-OAEP-256, dan algoritma konten adalah A128GCM:

  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>

Sebaliknya, untuk memverifikasi JWT terenkripsi dan memeriksa bahwa algoritma kunci adalah RSA-OAEP-256, dan tidak menerapkan batasan pada algoritma konten:

  <Algorithms>
    <Key>RSA-OAEP-256</Key>
  </Algorithms>

Algoritma enkripsi kunci

Tabel berikut mencantumkan algoritma yang tersedia untuk enkripsi kunci, serta jenis kunci yang harus Anda tentukan untuk memverifikasi JWT menggunakan algoritma enkripsi kunci tersebut.

Nilai <Key> (algoritma enkripsi kunci) Elemen utama yang diperlukan untuk verifikasi
dir <DirectKey>
RSA-OAEP-256 <PrivateKey>
  • A128KW
  • A192KW
  • A256KW
  • A128GCMKW
  • A192GCMKW
  • A256GCMKW
 <SecretKey>
  • PBES2-HS256+A128KW
  • PBES2-HS384+A192KW
  • PBES2-HS512+A256KW
 <PasswordKey>
  • ECDH-ES
  • ECDH-ES+A128KW
  • ECDH-ES+A192KW
  • ECDH-ES+A256KW
 <PrivateKey>

Lihat Memverifikasi JWT terenkripsi untuk contoh saat algoritma enkripsi kunci adalah RSA-OAEP-256, sehingga Anda menggunakan elemen <PrivateKey>.

Algoritma enkripsi konten

Kebijakan VerifyJWT tidak mengharuskan Anda menentukan algoritma untuk enkripsi konten. Jika Anda ingin menentukan algoritma yang digunakan untuk enkripsi konten, lakukan dengan turunan<Content> dari elemen <Algorithms>.

Terlepas dari algoritma enkripsi kunci, algoritma berikut - semuanya simetris dan berbasis AES - didukung untuk enkripsi konten:

  • A128CBC-HS256
  • A192CBC-HS384
  • A256CBC-HS512
  • A128GCM
  • A192GCM
  • A256GCM

<Audience>

<Audience>audience-here</Audience>

or:

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

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

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

<AdditionalClaims/Claim>

<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 nilai klaim yang ditegaskan 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 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 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 alur. Jika ada, kebijakan akan menggunakan nilai variabel ini sebagai klaim. Jika atribut ref dan nilai klaim eksplisit ditentukan, nilai eksplisit adalah nilai default, dan digunakan jika variabel alur yang dirujuk tidak terselesaikan.
  • type - (Opsional) Salah satu dari: string (default), angka, boolean, atau peta
  • array - (Opsional) Tetapkan ke true untuk menunjukkan apakah nilai adalah array jenis. Default: false.

Saat 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 yang 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 }
  }
}

<AdditionalHeaders/Claim>

<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 nilai klaim yang ditegaskan 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 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 defaultnya adalah String jika tidak ada jenis yang ditentukan.
Array Tetapkan ke true untuk menunjukkan apakah nilai 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 alur. Jika ada, kebijakan akan menggunakan nilai variabel ini sebagai klaim. Jika atribut ref dan nilai klaim eksplisit ditentukan, nilai eksplisit adalah nilai default, dan digunakan jika variabel alur yang dirujuk tidak terselesaikan.
  • type - (Opsional) Salah satu dari: string (default), angka, boolean, atau peta
  • array - (Opsional) Tetapkan ke true untuk menunjukkan apakah nilai adalah 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 sebagai gantinya adalah <AdditionalClaims>. UI akan diperbarui 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 tertentu. Jika nilai teks dan atribut ref 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 alur yang berisi ID.

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

Setel ke salah (false) jika Anda ingin kebijakan menampilkan error saat header apa pun yang tercantum dalam header crit JWT tidak tercantum dalam elemen <KnownHeaders>. Setel ke benar (true) agar kebijakan VerifyJWT mengabaikan header crit.

Salah satu alasan untuk menyetel elemen ini ke benar (true) adalah jika Anda berada di lingkungan pengujian dan belum siap menangani kegagalan pada header yang tidak ada.

Default false
Kehadiran Opsional
Jenis Boolean
Nilai yang valid true atau false

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

Setel ke false (default) jika Anda ingin kebijakan menampilkan error saat JWT berisi klaim iat (Dikeluarkan pada) yang menentukan waktu pada masa mendatang. Setel ke benar (true) agar kebijakan mengabaikan iat selama verifikasi.

Default false
Kehadiran Opsional
Jenis Boolean
Nilai yang valid true atau false

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Setel ke salah (false) jika Anda ingin kebijakan menampilkan error saat variabel yang dirujuk yang ditentukan dalam kebijakan tidak dapat diselesaikan. Setel ke benar (true) untuk memperlakukan variabel yang tidak dapat diselesaikan sebagai string kosong (null).

Default false
Kehadiran Opsional
Jenis Boolean
Nilai yang valid true atau false

<Issuer>

<VerifyJWT name='VJWT-29'>
  ...
  <!-- verify that the iss claim matches a hard-coded value -->
  <Issuer>issuer-string-here</Issuer>

  or:

  <!-- verify that the iss claim matches the value contained in a variable -->
  <Issuer ref='variable-containing-issuer'/>

  or:

  <!-- verify via a variable; fallback to a hard-coded value if the variable is empty -->
  <Issuer ref='variable-containing-issuer'>fallback-value-here</Issuer>

Kebijakan ini memverifikasi bahwa penerbit di JWT (klaim iss) cocok dengan string yang ditentukan dalam elemen konfigurasi. Klaim iss adalah salah satu klaim terdaftar yang disebutkan dalam IETF RFC 7519.

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

<KnownHeaders>

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

or:

<KnownHeaders ref='variable_containing_headers'/>

Kebijakan GenerateJWT menggunakan elemen <CriticalHeaders> untuk mengisi header crit dalam 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 memeriksa apakah elemen <KnownHeaders> juga mencantumkan header tersebut. Elemen <KnownHeaders> dapat berisi superset item yang tercantum dalam crit. Semua header yang tercantum di crit harus tercantum dalam elemen <KnownHeaders>. Header apa pun yang ditemukan kebijakan di crit yang tidak tercantum di <KnownHeaders> akan menyebabkan kebijakan VerifyJWT gagal.

Anda dapat secara opsional 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 Array atau nama variabel yang berisi array.

<MaxLifespan>

  <VerifyJWT name='VJWT-62'>
  ...
  <!-- hard-coded lifespan of 5 minutes -->
  <MaxLifespan>5m</MaxLifespan>

  or:

  <!-- refer to a variable -->
  <MaxLifespan ref='variable-here'/>

  or:

  <!-- attribute telling the policy to use iat rather than nbf -->
  <MaxLifespan useIssueTime='true'>1h</MaxLifespan>

  or:

  <!-- useIssueTime and ref, and hard-coded fallback value. -->
  <MaxLifespan useIssueTime='true' ref='variable-here'>1h</MaxLifespan>
  ...

Mengonfigurasi kebijakan VerifyJWT untuk memeriksa bahwa masa aktif token tidak melebihi nilai minimum yang ditentukan. Anda dapat menentukan nilai minimum dengan menggunakan angka yang diikuti dengan karakter, yang menunjukkan jumlah detik, menit, jam, hari, atau minggu. Karakter berikut valid:

  • s - detik
  • m - menit
  • h - jam
  • d - hari
  • w - minggu

Misalnya, Anda dapat menentukan salah satu nilai berikut: 120s, 10m, 1h, 7d, 3w.

Kebijakan ini menghitung rentang masa berlaku token yang sebenarnya dengan mengurangi nilai not-before (nbf) dari nilai habis masa berlaku (exp). Jika exp atau nbf tidak ada, kebijakan akan menampilkan kesalahan. Jika masa berlaku token melebihi jangka waktu yang ditentukan, kebijakan akan menampilkan kesalahan.

Anda dapat menetapkan atribut opsional useIssueTime ke true untuk menggunakan nilai iat, bukan nilai nbf saat menghitung masa aktif token.

Penggunaan elemen MaxLifespan bersifat opsional. Jika menggunakan elemen ini, Anda hanya dapat menggunakannya satu kali.

<PrivateKey>

Gunakan elemen ini untuk menentukan kunci pribadi yang dapat digunakan untuk memverifikasi JWT yang dienkripsi dengan algoritma asimetris. Deskripsi kemungkinan elemen turunan akan ditampilkan.

<Password>

<PrivateKey>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

Turunan dari elemen <PrivateKey>. Menentukan sandi yang harus digunakan kebijakan untuk mendekripsi kunci pribadi, jika perlu, saat memverifikasi JWT terenkripsi. Gunakan atribut ref untuk meneruskan sandi dalam variabel alur.

Default T/A
Kehadiran Opsional
Jenis String
Nilai yang valid Referensi variabel alur.

Catatan: Anda harus menentukan variabel alur. Apigee akan menolak konfigurasi kebijakan yang tidak valid jika sandi ditentukan dalam teks biasa. Variabel alur harus memiliki awalan "private". Misalnya, private.mypassword

<Value>

<PrivateKey>
  <Value ref="private.variable-name-here"/>
</PrivateKey>

Turunan dari elemen <PrivateKey>. Menentukan kunci pribadi berenkode PEM yang akan digunakan kebijakan untuk memverifikasi JWT terenkripsi. Gunakan atribut ref untuk meneruskan kunci dalam variabel alur.

Default T/A
Kehadiran Diperlukan untuk memverifikasi JWT yang telah dienkripsi menggunakan algoritma enkripsi kunci asimetris.
Jenis String
Nilai yang valid Variabel alur yang berisi string yang merepresentasikan nilai kunci pribadi RSA berenkode PEM.

Catatan: Variabel alur harus memiliki awalan "private". Misalnya, private.mykey

<PublicKey>

Menentukan sumber untuk kunci publik yang digunakan untuk memverifikasi JWT yang ditandatangani dengan algoritma asimetris. Algoritma yang didukung mencakup RS256/RS384/RS512, PS256/PS384/PS512, atau ES256/ES384/ES512. Deskripsi kemungkinan elemen turunan akan ditampilkan.

<Certificate>

<PublicKey>
  <Certificate ref="signed_public.cert"/>
</PublicKey>

-or-

<PublicKey>
  <Certificate>
-----BEGIN CERTIFICATE-----
certificate data
-----END CERTIFICATE-----
  </Certificate>
</PublicKey>

Turunan dari elemen <PublicKey>. Menentukan sertifikat bertanda tangan yang digunakan sebagai sumber kunci publik. Gunakan atribut ref untuk meneruskan sertifikat yang ditandatangani dalam variabel alur, atau tentukan sertifikat berenkode PEM secara langsung. Pastikan untuk menyelaraskan data sertifikat di sebelah kiri seperti yang ditunjukkan dalam contoh referensi.

Default T/A
Kehadiran Opsional. Untuk memverifikasi JWT yang ditandatangani dengan algoritma asimetris, Anda harus menggunakan <Certificate>, <JWKS>, atau elemen <Value> untuk memberikan kunci publik.
Jenis String
Nilai yang valid Variabel atau string alur.

<JWKS>

  <PublicKey>
    <JWKS …  > … </JWKS>
  </PublicKey>

Turunan dari elemen <PublicKey>. Menentukan JWKS sebagai sumber kunci publik. Ini akan berupa daftar kunci yang mengikuti format yang dijelaskan dalam IETF RFC 7517 - JSON Web Key (JWK).

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

Jika Anda mengambil nilai dari URL publik, Apigee akan menyimpan JWKS dalam cache selama 300 detik. Saat masa berlaku cache berakhir, Apigee akan mengambil JWKS lagi.

Default T/A
Kehadiran Opsional. Untuk memverifikasi JWT yang ditandatangani dengan algoritma asimetris, Anda harus menggunakan <Certificate>, <JWKS>, atau elemen <Value> untuk memberikan kunci publik.
Jenis String
Nilai yang valid

Anda dapat menentukan JWKS dengan salah satu dari empat cara berikut:

  • Secara harfiah, sebagai nilai teks:

      <PublicKey>
    <JWKS>{
      "keys": [
        {"kty":"RSA","e":"AQAB","kid":"b3918c88","n":"jxdm..."},
        {"kty":"RSA","e":"AQAB","kid":"24f094d4","n":"kWRdbgMQ..."}
      ]
    }
    </JWKS>
  </PublicKey>

  • Secara tidak langsung, dengan atribut ref, yang menentukan variabel alur:

      <PublicKey>
    <JWKS ref="variable-containing-jwks-content"/>
  </PublicKey>

    Variabel yang dirujuk harus berisi string yang merepresentasikan JWKS.

  • Secara tidak langsung melalui URI statis, dengan atribut uri:

      <PublicKey>
    <JWKS uri="uri-that-returns-a-jwks"/>
  </PublicKey>

  • Secara tidak langsung melalui URI yang ditentukan secara dinamis, dengan atribut uriRef:

      <PublicKey>
    <JWKS uriRef="variable-containing-a-uri-that-returns-a-jwks"/>
  </PublicKey>

<Value>

<PublicKey>
  <Value ref="public.publickeyorcert"/>
</PublicKey>

-or-

<PublicKey>
  <Value>
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW
...YOUR PUBLIC KEY MATERIAL HERE....d1lH8MfUyRXmpmnNxJHAC2F73IyN
ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx
DQIDAQAB
-----END PUBLIC KEY-----
  </Value>
</PublicKey>

Turunan dari elemen <PublicKey>. Menentukan kunci publik yang akan digunakan untuk memverifikasi tanda tangan pada JWT yang ditandatangani. Gunakan atribut ref untuk meneruskan kunci dalam variabel alur, atau tentukan kunci berenkode PEM secara langsung. Pastikan untuk menyelaraskan kunci publik di sebelah kiri seperti yang ditunjukkan dalam contoh referensi.

Default T/A
Kehadiran Opsional. Untuk memverifikasi JWT yang ditandatangani dengan algoritma asimetris, Anda harus menggunakan <Certificate>, <JWKS>, atau elemen <Value> untuk memberikan kunci publik.
Jenis String
Nilai yang valid Variabel atau string alur.

<RequiredClaims>

<VerifyJWT name='VJWT-1'>
  ...
  <!-- Directly specify the names of the claims to require -->
  <RequiredClaims>sub,iss,exp</RequiredClaims>

  -or-

  <!-- Specify the claim names indirectly, via a context variable -->
  <RequiredClaims ref='claims_to_require'/>
  ...
</VerifyJWT>

Elemen <RequiredClaims> bersifat opsional. Menentukan daftar nama klaim yang dipisahkan koma yang harus ada di payload JWT, saat memverifikasi JWT. Elemen memastikan bahwa JWT yang ditampilkan berisi klaim yang diperlukan, tetapi tidak memvalidasi konten klaim. Jika salah satu klaim yang tercantum tidak ada, kebijakan VerifyJWT akan menampilkan kesalahan saat runtime.

Default T/A
Kehadiran Opsional
Jenis String
Nilai yang valid Daftar nama klaim yang dipisahkan koma.

<SecretKey>

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

Elemen SecretKey bersifat opsional. Menentukan kunci rahasia yang akan digunakan saat memverifikasi JWT bertanda tangan yang menggunakan algoritma simetris (HS*) atau saat memverifikasi JWT terenkripsi yang menggunakan algoritma simetris (AES) untuk enkripsi kunci.

Anak-anak <SecretKey>

Tabel berikut memberikan deskripsi elemen turunan dan atribut <SecretKey>:

Anak Kehadiran Deskripsi
encoding (atribut) Opsional

Menentukan cara kunci dienkode dalam variabel yang dirujuk. Secara default, jika tidak ada atribut encoding, encoding kunci akan diperlakukan sebagai UTF-8. Nilai yang valid untuk atribut ini adalah: hex, base16, base64, atau base64url. Nilai encoding hex dan base16 adalah sinonim.

<SecretKey encoding="hex" >
  <Value ref="private.secretkey"/>
</SecretKey>

Pada contoh di atas, karena encoding-nya adalah hex, jika konten variabel private.secretkey adalah 494c6f766541504973, kunci akan didekode sebagai set 9 byte, yang dalam hex akan menjadi 49 4c 6f 76 65 41 50 49 73.

Nilai (elemen) Wajib

Kunci rahasia yang dienkode. Menentukan kunci rahasia yang akan digunakan untuk memverifikasi payload. Gunakan atribut ref untuk memberikan kunci secara tidak langsung melalui variabel, seperti private.secret-key .

<SecretKey>
  <Value ref="private.my-secret-variable"/>
</SecretKey>

Apigee menerapkan kekuatan kunci minimum untuk algoritma HS256/HS384/HS512. Panjang kunci minimum untuk HS256 adalah 32 byte, untuk HS384 adalah 48 byte, dan untuk HS512 adalah 64 byte. Menggunakan kunci dengan kekuatan yang lebih rendah akan menyebabkan error runtime.

<Source>

<Source>jwt-variable</Source>

Jika ada, menentukan variabel alur tempat kebijakan diharapkan menemukan JWT untuk diverifikasi.

Dengan elemen ini, Anda dapat mengonfigurasi kebijakan untuk mengambil JWT dari variabel parameter kueri atau formulir atau variabel lainnya. Jika elemen ini ada, kebijakan tidak akan menghapus awalan Bearer yang mungkin ada. Jika variabel tidak ada atau jika kebijakan tidak menemukan JWT dalam variabel yang ditentukan, kebijakan akan menampilkan error.

Secara default, jika tidak ada elemen <Source>, kebijakan akan mengambil JWT dengan membaca variabel request.header.authorization dan menghapus awalan Bearer. Jika Anda meneruskan JWT di header Authorization sebagai token pemilik (dengan awalan Bearer), jangan tentukan elemen <Source> dalam konfigurasi kebijakan. Misalnya, Anda tidak akan menggunakan elemen <Source> dalam konfigurasi kebijakan jika Anda meneruskan JWT di header Otorisasi seperti ini:

curl -v https://api-endpoint/proxy1_basepath/api1 -H "Authorization: Bearer eyJhbGciOiJ..."
Default request.header.authorization (Lihat catatan di atas untuk mengetahui informasi penting tentang default).
Kehadiran Opsional
Jenis String
Nilai yang valid Nama variabel alur Apigee.

<Subject>

<VerifyJWT name='VJWT-8'>
  ...
  <!-- verify that the sub claim matches a hard-coded value -->
  <Subject>subject-string-here</Subject>

  or:

  <!-- verify that the sub claim matches the value contained in a variable -->
  <Subject ref='variable-containing-subject'/>

  or:

  <!-- verify via a variable; fallback to a hard-coded value if the variable is empty -->
  <Subject ref='variable-containing-subject'>fallback-value-here</Subject>

Kebijakan ini memverifikasi bahwa subjek dalam JWT (klaim sub) cocok dengan string yang ditentukan dalam konfigurasi kebijakan. Klaim sub adalah salah satu klaim terdaftar yang dijelaskan dalam RFC7519.

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

<TimeAllowance>

<VerifyJWT name='VJWT-23'>
  ...
  <!-- configure a hard-coded time allowance of 20 seconds -->
  <TimeAllowance>20s</TimeAllowance>

  or:

  <!-- refer to a variable containing the time allowance -->
  <TimeAllowance ref='variable-containing-time-allowance'/>

  or:

  <!-- refer to a variable; fallback to a hard-coded value if the variable is empty -->
  <TimeAllowance ref='variable-containing-allowance'>30s</TimeAllowance>

"Masa tenggang" untuk waktu, untuk memperhitungkan perbedaan waktu antara penerbit dan verifikator JWT. Hal ini akan berlaku untuk masa berlaku (klaim exp) dan waktu sebelum berlaku (klaim nbf). Misalnya, jika alokasi waktu dikonfigurasi menjadi 30s, maka JWT yang telah berakhir akan dianggap masih valid, selama 30 detik setelah masa berlakunya berakhir. Waktu tidak sebelum akan dievaluasi dengan cara yang sama.

Default 0 detik (tidak ada masa tenggang)
Kehadiran Opsional
Jenis String
Nilai yang valid Ekspresi rentang waktu, atau referensi ke variabel alur yang berisi ekspresi. Rentang waktu dapat ditentukan oleh bilangan bulat positif yang diikuti oleh satu karakter yang menunjukkan satuan waktu, sebagai berikut:
  • s = detik
  • m = menit
  • h = jam
  • d = hari

<Type>

<Type>type-string-here</Type>

Menjelaskan apakah kebijakan memverifikasi JWT bertanda tangan atau JWT terenkripsi. Elemen <Type> bersifat opsional. Anda dapat menggunakannya untuk memberi tahu pembaca tentang konfigurasi apakah kebijakan menghasilkan JWT yang ditandatangani atau dienkripsi.

  • Jika elemen <Type> ada:
    • Jika nilai <Type> adalah Signed, kebijakan memverifikasi JWT bertanda tangan, dan elemen <Algorithm> harus ada.
    • Jika nilai <Type> adalah Encrypted, kebijakan memverifikasi JWT terenkripsi, dan elemen <Algorithms> harus ada.
  • Jika elemen <Type> tidak ada:
    • Jika elemen <Algorithm> ada, kebijakan mengasumsikan <Type> adalah Signed.
    • Jika elemen <Algorithms> ada, kebijakan mengasumsikan <Type> adalah Encrypted.
  • Jika <Algorithm> maupun <Algorithms> tidak ada, konfigurasi tidak valid.
Default T/A
Kehadiran Opsional
Jenis String
Nilai yang valid Signed atau Encrypted

Variabel alur

Setelah berhasil, kebijakan Verify JWT dan Decode JWT akan 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 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 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 bernama (standar atau tambahan) dalam payload. Salah satunya akan ditetapkan untuk setiap klaim dalam payload.
decoded.claim.name Nilai klaim bernama (standar atau tambahan) yang dapat diuraikan JSON 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, ini adalah variabel yang direkomendasikan untuk digunakan guna 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, variabel ini direkomendasikan untuk digunakan guna 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 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)" di ringkasan kebijakan JWT untuk memverifikasi JWT. Lihat Parameter Header(ID Kunci) untuk mengetahui informasi selengkapnya.
header.type Akan ditetapkan ke JWT.
header.name Nilai header bernama (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 telah berakhir, angka ini akan negatif.
time_remaining_formatted Waktu yang tersisa sebelum token berakhir, diformat sebagai string yang dapat dibaca manusia. 00:59:59.926
valid Dalam kasus VerifyJWT, variabel ini akan bernilai benar saat tanda tangan diverifikasi, dan waktu saat ini sebelum masa berlaku token berakhir, dan setelah nilai notBefore token, jika ada. Jika tidak, flag akan bernilai salah.

Dalam kasus DecodeJWT, variabel ini tidak ditetapkan.

Referensi error

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Occurs when
steps.jwt.AlgorithmInTokenNotPresentInConfiguration 401 Occurs when the verification policy has multiple algorithms.
steps.jwt.AlgorithmMismatch 401 The algorithm specified in the Generate policy did not match the one expected in the Verify policy. The algorithms specified must match.
steps.jwt.FailedToDecode 401 The policy was unable to decode the JWT. The JWT is possibly corrupted.
steps.jwt.GenerationFailed 401 The policy was unable to generate the JWT.
steps.jwt.InsufficientKeyLength 401 For a key less than 32 bytes for the HS256 algorithm, less than 48 bytes for the HS386 algortithm, and less than 64 bytes for the HS512 algorithm.
steps.jwt.InvalidClaim 401 For a missing claim or claim mismatch, or a missing header or header mismatch.
steps.jwt.InvalidConfiguration 401 Both the <Algorithm> and <Algorithms> elements are present.
steps.jwt.InvalidCurve 401 The curve specified by the key is not valid for the Elliptic Curve algorithm.
steps.jwt.InvalidIterationCount 401 The iteration count that was used in the encrypted JWT is not equal to the iteration count specified in the VerifyJWT policy configuration. This applies only to JWT that use <PasswordKey>.
steps.jwt.InvalidJsonFormat 401 Invalid JSON found in the header or payload.
steps.jwt.InvalidKeyConfiguration 401 JWKS in the <PublicKey> element is invalid. The reason could be that the JWKS URI endpoint is not reachable from the Apigee instance. Test connectivity to the endpoint by creating a passthrough proxy and using the JWKS endpoint as a target.
steps.jwt.InvalidSaltLength 401 The salt length that was used in the encrypted JWT is not equal to the salt length specified in the VerifyJWT policy configuration. This applies only to JWT that use <PasswordKey>.
steps.jwt.InvalidPasswordKey 401 The specified key specified did not meet the requirements.
steps.jwt.InvalidPrivateKey 401 The specified key specified did not meet the requirements.
steps.jwt.InvalidPublicKey 401 The specified key specified did not meet the requirements.
steps.jwt.InvalidSecretKey 401 The specified key specified did not meet the requirements.
steps.jwt.InvalidToken 401 This error occurs when the JWT signature verification fails.
steps.jwt.JwtAudienceMismatch 401 The audience claim failed on token verification.
steps.jwt.JwtIssuerMismatch 401 The issuer claim failed on token verification.
steps.jwt.JwtSubjectMismatch 401 The subject claim failed on token verification.
steps.jwt.KeyIdMissing 401 The Verify policy uses a JWKS as a source for public keys, but the signed JWT does not include a kid property in the header.
steps.jwt.KeyParsingFailed 401 The public key could not be parsed from the given key information.
steps.jwt.NoAlgorithmFoundInHeader 401 Occurs when the JWT contains no algorithm header.
steps.jwt.NoMatchingPublicKey 401 The Verify policy uses a JWKS as a source for public keys, but the kid in the signed JWT is not listed in the JWKS.
steps.jwt.SigningFailed 401 In GenerateJWT, for a key less than the minimum size for the HS384 or HS512 algorithms
steps.jwt.TokenExpired 401 The policy attempts to verify an expired token.
steps.jwt.TokenNotYetValid 401 The token is not yet valid.
steps.jwt.UnhandledCriticalHeader 401 A header found by the Verify JWT policy in the crit header is not listed in KnownHeaders.
steps.jwt.UnknownException 401 An unknown exception occurred.
steps.jwt.WrongKeyType 401 Wrong type of key specified. For example, if you specify an RSA key for an Elliptic Curve algorithm, or a curve key for an RSA algorithm.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
InvalidNameForAdditionalClaim The deployment will fail if the claim used in the child element <Claim> of the <AdditionalClaims> element is one of the following registered names: kid, iss, sub, aud, iat, exp, nbf, or jti.
InvalidTypeForAdditionalClaim If the claim used in the child element <Claim> of the <AdditionalClaims> element is not of type string, number, boolean, or map, the deployment will fail.
MissingNameForAdditionalClaim If the name of the claim is not specified in the child element <Claim> of the <AdditionalClaims> element, the deployment will fail.
InvalidNameForAdditionalHeader This error ccurs when the name of the claim used in the child element <Claim> of the <AdditionalClaims> element is either alg or typ.
InvalidTypeForAdditionalHeader If the type of claim used in the child element <Claim> of the <AdditionalClaims> element is not of type string, number, boolean, or map, the deployment will fail.
InvalidValueOfArrayAttribute This error occurs when the value of the array attribute in the child element <Claim> of the <AdditionalClaims> element is not set to true or false.
InvalidValueForElement If the value specified in the <Algorithm> element is not a supported value, the deployment will fail.
MissingConfigurationElement This error will occur if the <PrivateKey> element is not used with RSA family algorithms or the <SecretKey> element is not used with HS Family algorithms.
InvalidKeyConfiguration If the child element <Value> is not defined in the <PrivateKey> or <SecretKey> elements, the deployment will fail.
EmptyElementForKeyConfiguration If the ref attribute of the child element <Value> of the <PrivateKey> or <SecretKey> elements is empty or unspecified, the deployment will fail.
InvalidConfigurationForVerify This error occurs if the <Id> element is defined within the <SecretKey> element.
InvalidEmptyElement This error occurs if the <Source> element of the Verify JWT policy is empty. If present, it must be defined with an Apigee flow variable name.
InvalidPublicKeyValue If the value used in the child element <JWKS> of the <PublicKey> element does not use a valid format as specified in RFC 7517, the deployment will fail.
InvalidConfigurationForActionAndAlgorithm If the <PrivateKey> element is used with HS Family algorithms or the <SecretKey> element is used with RSA Family algorithms, the deployment will fail.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "InvalidToken"
JWT.failed All JWT policies set the same variable in the case of a failure. JWT.failed = true

Example error response

JWT Policy Fault Codes

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

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