Kebijakan VerifyJWT

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

Apa

Memverifikasi tanda tangan pada JWT yang diterima dari klien atau sistem lain. Kebijakan ini juga mengekstraksi 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, Edge akan memverifikasi tanda tangan JWT, dan 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.

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

Video

Tonton video pendek untuk mempelajari cara memverifikasi tanda tangan pada JWT.

Contoh

• Memverifikasi JWT yang ditandatangani dengan algoritma HS256
• Memverifikasi JWT yang ditandatangani dengan algoritma RS256

Memverifikasi JWT yang ditandatangani dengan 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 mengajukan permintaan ke kebijakan.

Konfigurasi kebijakan mencakup informasi yang diperlukan Edge untuk mendekode dan mengevaluasi JWT, seperti tempat menemukan JWT (dalam flow variable yang ditentukan dalam elemen Sumber), algoritma penandatanganan yang diperlukan, tempat menemukan kunci rahasia (disimpan dalam flow variable Edge, yang mungkin telah diambil dari KVM Edge, 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.

Memverifikasi JWT yang ditandatangani dengan 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 mengajukan permintaan ke kebijakan.

Lihat Referensi elemen untuk mengetahui detail 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.

Menetapkan elemen utama

Elemen yang Anda gunakan untuk menentukan kunci yang digunakan untuk memverifikasi JWT 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>

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 bersifat umum untuk semua elemen induk kebijakan.

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

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

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

<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 flow variable.

Elemen <Claim> menggunakan atribut berikut:

• name - (Wajib) Nama klaim.
• ref - (Opsional) Nama flow variable. 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 flow variable 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 flow variable.

Elemen <Claim> menggunakan atribut berikut:

• name - (Wajib) Nama klaim.
• ref - (Opsional) Nama flow variable. 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 flow variable 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.

<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 menyebabkan kegagalan pada header yang tidak ada.

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

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

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

<Issuer>

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

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

<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> juga akan menyebabkan kebijakan VerifyJWT gagal.

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

<PublicKey/Certificate>

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

Menentukan sertifikat bertanda tangan yang digunakan untuk memverifikasi tanda tangan pada JWT. Gunakan atribut ref untuk meneruskan sertifikat yang ditandatangani dalam flow variable, atau tentukan sertifikat berenkode PEM secara langsung. Gunakan hanya jika algoritma adalah salah satu dari RS256/RS384/RS512, PS256/PS384/PS512, atau ES256/ES384/ES512.

<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 serangkaian kunci publik. Gunakan hanya jika algoritma adalah salah satu dari RS256/RS384/RS512, PS256/PS384/PS512, atau ES256/ES384/ES512.

Jika JWT masuk memiliki ID kunci yang ada dalam set 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, Edge akan meng-cache JWKS selama 300 detik. Saat masa berlaku cache berakhir, Edge akan mengambil JWKS lagi.

<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 pada JWT. Gunakan atribut ref untuk meneruskan kunci/sertifikat dalam flow variable, atau tentukan kunci berenkode PEM secara langsung. Gunakan hanya jika algoritmanya adalah salah satu dari RS256/RS384/RS512, PS256/PS384/PS512, atau ES256/ES384/ES512.

<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 algoritma adalah salah satu dari HS256, HS384, HS512..

<Source>

<Source>jwt-variable</Source>

Jika ada, menentukan flow variable tempat kebijakan mengharapkan untuk menemukan JWT yang akan diverifikasi.

<Subject>

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

Kebijakan ini 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 set standar klaim yang disebutkan dalam RFC7519.

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

"Masa tenggang" untuk waktu. Misalnya, jika alokasi waktu dikonfigurasi menjadi 60 detik, maka JWT yang sudah habis masa berlakunya akan dianggap masih valid, selama 60 detik setelah masa berlaku yang dinyatakan habis. The not-before-time akan dievaluasi dengan cara yang sama. Defaultnya adalah 0 detik (tidak ada masa tenggang).

Variabel flow

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

jwt.{policy_name}.{variable_name}

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

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.

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 menangkap bagian errorcode dari error yang dihasilkan. Jangan mengandalkan teks di faultstring, karena dapat berubah.

Contoh aturan kesalahan

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