kebijakan VerifyJWT

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat Dokumentasi Apigee Edge.

Apa

Memverifikasi JWT yang ditandatangani 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 diperiksa nilai-nilai tersebut untuk membuat keputusan otorisasi atau {i>routing<i}. Lihat ringkasan kebijakan JWS dan JWT untuk pengantar mendetail.

Kebijakan ini merupakan Kebijakan standar dan dapat di-deploy ke jenis lingkungan apa pun. Tidak semua perlu diketahui pengguna tentang jenis kebijakan dan lingkungan. Sebagai informasi tentang jenis kebijakan dan ketersediaan untuk setiap jenis lingkungan, lihat Jenis kebijakan.

Saat kebijakan ini dijalankan, untuk JWT yang ditandatangani, Apigee akan memverifikasi tanda tangan JWT menggunakan kunci verifikasi yang diberikan. Pada kasus JWT terenkripsi, Apigee akan mendekripsi JWT menggunakan kunci dekripsi. Dalam kedua kasus tersebut, Apigee kemudian 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 tentang bagian-bagian JWT dan cara JWT dienkripsi dan ditandatangani, lihat RFC7519.

Solusi

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

• Jika Anda menggunakan elemen <Algorithm>, kebijakan memverifikasi JWT yang ditandatangani.
• Jika Anda menggunakan <Algorithms> , kebijakan tersebut memverifikasi JWT terenkripsi.

Video

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

Memverifikasi JWT yang Ditandatangani

Bagian ini menjelaskan cara memverifikasi JWT yang ditandatangani. Untuk JWT yang ditandatangani, menggunakan <Algorithm> untuk menentukan algoritma untuk menandatangani kunci.

Sampel untuk JWT yang ditandatangani

Contoh berikut mengilustrasikan cara memverifikasi JWT yang ditandatangani.

<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>

<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>

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

{
  "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."
}

{
  "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."
}

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

Menyetel elemen kunci untuk memverifikasi JWT yang ditandatangani

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

• <SecretKey>
• <PublicKey>

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

<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.secretkey"/>
</SecretKey>

<PublicKey>
  <Value ref="rsa_public_key_or_value"/>
</PublicKey>

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

<PublicKey>
  <JWKS ref="jwks_val_or_ref"/>
</PublicKey>

Memverifikasi JWT terenkripsi

Bagian ini menjelaskan cara memverifikasi JWT yang dienkripsi. Untuk JWT terenkripsi, gunakan metode <Algorithms> untuk menentukan algoritma untuk menandatangani kunci dan isi.

Contoh JWT terenkripsi

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

• 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 elemen JWT. Elemen <PrivateKey> menentukan kunci yang akan digunakan untuk mendekripsi JWT. Ada juga merupakan elemen kunci lainnya. Yang Anda gunakan tergantung pada algoritma yang ditentukan oleh <Algorithms>, seperti yang dijelaskan di bagian berikutnya.

Menyetel elemen kunci untuk memverifikasi JWT terenkripsi

Elemen berikut menentukan kunci yang digunakan untuk memverifikasi JWT terenkripsi:

• <PrivateKey>
• <SecretKey>
• <PasswordKey>
• <DirectKey>

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

<PrivateKey>
  <Value ref="private.rsa_privatekey"/>
</PrivateKey>

<PrivateKey>
  <Value ref="private.ec_privatekey"/>
</PrivateKey>

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

<PasswordKey>
  <Value ref="private.password-key"/>
  <SaltLength>
  <PBKDF2Iterations>
</PasswordKey>

<DirectKey>
  <Value encoding="base16|hex|base64|base64url" ref="private.directkey"/>
</DirectKey>

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

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.

&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.

&lt;Algorithm&gt;

<Algorithm>HS256</Algorithm>

Menentukan algoritma kriptografi yang digunakan untuk memverifikasi token. Gunakan <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 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*.

&lt;Algorithms&gt;

<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 telah dibuat. Ini juga secara opsional menentukan algoritma untuk enkripsi konten.

Elemen turunan <Algorithms>

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

Verifikasi akan gagal jika:

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

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

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

Sebaliknya, untuk memverifikasi JWT terenkripsi dan memeriksa apakah algoritma kunci telah RSA-OAEP-256, dan tidak menerapkan batasan pada algoritme 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.

Baca artikel Memverifikasi JWT terenkripsi untuk mengetahui contohnya algoritma enkripsi kunci adalah RSA-OAEP-256, jadi Anda menggunakan elemen <PrivateKey>.

Algoritma enkripsi konten

Kebijakan VerifyJWT tidak mengharuskan Anda menentukan algoritma untuk konten enkripsi. Jika Anda ingin menentukan algoritma yang digunakan untuk enkripsi konten, lakukanlah dengan <Content> turunan dari Elemen &lt;Algorithms&gt;.

Terlepas dari algoritma enkripsi kunci, algoritma berikut ini - 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 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.

&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 tertentu 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.

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.

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.

&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 menangani kegagalan pada {i>header<i} yang hilang.

&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.

&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).

&lt;Issuer&gt;

<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 klaim yang disebutkan dalam IETF RFC 7519.

&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.

&lt;MaxLifespan&gt;

  <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 Verifikasi kebijakan JWT untuk memeriksa bahwa masa aktif token tidak melebihi nilai minimum yang ditentukan. Anda dapat menentukan ambang batas dengan menggunakan angka yang diikuti dengan karakter, yang menunjukkan jumlah detik, menit, jam, hari, atau minggu. Karakter-karakter berikut valid:

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

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

Kebijakan ini menghitung waktu masa aktif token dengan mengurangi nilai sebelum (nbf) dari nilai masa berlaku (exp). Jika exp atau nbf tidak ada, kebijakan akan menampilkan kesalahan. Jika masa aktif token melebihi rentang waktu yang ditentukan, kebijakan akan menampilkan kesalahan.

Anda dapat menyetel atribut opsional useIssueTime ke true yang akan digunakan nilai iat, bukan nilai nbf saat menghitung token masa hidup Anda.

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

&lt;PrivateKey&gt;

Gunakan elemen ini untuk menentukan kunci pribadi yang dapat digunakan untuk memverifikasi JWT dienkripsi dengan algoritma asimetris. Berikut deskripsi tentang elemen turunan yang mungkin.

&lt;Password&gt;

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

Turunan elemen <PrivateKey>. Menentukan sandi harus digunakan untuk membongkar enkripsi kunci pribadi, jika perlu, saat memverifikasi JWT terenkripsi. Gunakan atribut ref untuk meneruskan {i>password<i} dalam variabel {i>flow<i}.

&lt;Value&gt;

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

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

&lt;PublicKey&gt;

Menentukan sumber kunci publik yang digunakan untuk memverifikasi tanda tangan JWT dengan algoritma asimetris. Algoritma dukungan mencakup RS256/RS384/RS512, PS256/PS384/PS512, atau ES256/ES384/ES512. Berikut adalah deskripsi elemen turunan yang mungkin.

&lt;Certificate&gt;

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

-or-

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

Turunan elemen <PublicKey>. Menentukan sertifikat yang ditandatangani digunakan sebagai sumber dari kunci publik. Menggunakan ref untuk meneruskan sertifikat yang ditandatangani dalam variabel flow, atau menentukan variabel yang dienkode ke PEM sertifikat secara langsung.

&lt;JWKS&gt;

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

Turunan elemen <PublicKey>. Menentukan JWKS sebagai sumber publik tombol. Ini akan menjadi daftar kunci mengikuti format yang dijelaskan di IETF RFC 7517 - Kunci Web JSON (JWK).

Jika JWT masuk membawa ID kunci yang ada di 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, Apigee akan menyimpan JWKS dalam cache selama 300 detik. Saat cache berakhir, Apigee mengambil JWKS lagi.

&lt;Value&gt;

<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 elemen <PublicKey>. Menentukan kunci publik yang akan digunakan memverifikasi tanda tangan pada JWT yang ditandatangani. Gunakan atribut ref untuk meneruskan kunci dalam variabel flow, atau menentukan kunci berenkode PEM secara langsung.

&lt;RequiredClaims&gt;

<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. Ini menentukan daftar yang dipisahkan koma nama klaim yang harus ada dalam payload JWT, saat memverifikasi JWT. Elemen memastikan bahwa JWT yang ditampilkan berisi klaim yang diperlukan tetapi tidak memvalidasi kontennya klaim tersebut. Jika salah satu klaim yang tercantum tidak ada, kebijakan VerifyJWT akan menampilkan pada waktu proses.

&lt;SecretKey&gt;

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

Elemen SecretKey bersifat opsional. Ini menentukan kunci rahasia yang akan digunakan ketika memverifikasi JWT yang ditandatangani yang menggunakan algoritma simetris (HS*) atau ketika memverifikasi JWT terenkripsi yang menggunakan algoritma simetris (AES) untuk kunci enkripsi.

Anak-anak dari <SecretKey>

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

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

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

&lt;Source&gt;

<Source>jwt-variable</Source>

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

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

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

curl -v https://api-endpoint/proxy1_basepath/api1 -H "Authorization: Bearer eyJhbGciOiJ..."

&lt;Subject&gt;

<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 di JWT (klaim sub) cocok dengan string yang ditentukan dalam konfigurasi kebijakan. Klaim sub adalah salah satu klaim klaim yang dijelaskan dalam RFC7519.

&lt;TimeAllowance&gt;

<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" selama waktu, untuk memperhitungkan penyimpangan waktu antara penerbit dan pemverifikasi suatu JWT. Hal ini akan berlaku untuk masa berlaku (klaim exp) serta bukan sebelum waktunya (klaim nbf). Misalnya, jika kuota waktu dikonfigurasi menjadi 30s, JWT yang sudah tidak berlaku akan dianggap masih valid selama 30 detik setelah masa berlaku habis yang dinyatakan. Waktu sebelum waktunya akan dievaluasi dengan cara yang sama.

&lt;Type&gt;

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

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

• Jika elemen <Type> ada:
  • Jika nilai <Type> adalah Signed, kebijakan memverifikasi JWT yang ditandatangani, dan Elemen <Algorithm> harus ada.
  • Jika nilai <Type> adalah Encrypted, kebijakan akan 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 akan mengasumsikan <Type> adalah Encrypted.
• Jika <Algorithm> atau <Algorithms> tidak ada, konfigurasinya tidak valid.

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)

Referensi error

Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan, serta variabel kesalahan yang disetel oleh Apigee 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 dijalankan.

Error saat deployment

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

Variabel kesalahan

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

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 "InvalidToken")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>