Anda sedang melihat dokumentasi Apigee Edge.
Buka
Dokumentasi Apigee X. info
Apa
Memverifikasi tanda tangan pada JWS yang diterima dari klien atau sistem lain. Kebijakan ini juga mengekstrak {i>header<i} 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.
Jika JWS diverifikasi dan valid, maka permintaan akan diizinkan untuk melanjutkan. Jika tanda tangan JWS tidak dapat diverifikasi atau jika JWS tidak valid karena beberapa jenis {i>error<i}, semua pemrosesan berhenti dan sebuah pesan {i>error<i} dimunculkan dalam responsnya.
Untuk mempelajari tentang bagian-bagian dari JWS dan bagaimana mereka dienkripsi dan ditandatangani, lihat RFC7515.
Video
Tonton video singkat untuk mempelajari cara memverifikasi tanda tangan di JWS. Meskipun video ini khusus untuk memverifikasi JWT, banyak konsepnya sama untuk JWS.
Contoh
- Memverifikasi JWS terlampir yang ditandatangani dengan HS256 algoritme
- Memverifikasi JWS terpisah yang ditandatangani dengan RS256 algoritme
Memverifikasi JWS terlampir yang ditandatangani dengan HS256 algoritma
Contoh kebijakan ini memverifikasi JWS terlampir yang ditandatangani dengan algoritma enkripsi HS256, HMAC
menggunakan {i>checksum<i} SHA-256. JWS diteruskan dalam permintaan proxy menggunakan parameter formulir yang diberi nama
JWS
. Kunci ini terdapat dalam variabel bernama private.secretkey
.
JWS yang dilampirkan berisi header, payload, dan tanda tangan yang dienkode:
header.payload.signature
Konfigurasi kebijakan mencakup informasi yang diperlukan Edge untuk mendekode dan mengevaluasi JWS,
seperti tempat menemukan JWS (dalam variabel flow yang ditentukan dalam elemen <Source>
),
algoritma penandatanganan yang diperlukan, dan tempat menemukan kunci rahasia (disimpan dalam variabel alur Edge, yang bisa
(misalnya, telah diambil dari Edge KVM).
<VerifyJWS name="JWS-Verify-HS256"> <DisplayName>JWS Verify HS256</DisplayName> <Algorithm>HS256</Algorithm> <Source>request.formparam.JWS</Source> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <SecretKey> <Value ref="private.secretkey"/> </SecretKey> </VerifyJWS>
Kebijakan menulis output-nya ke variabel konteks sehingga kebijakan atau kondisi berikutnya di proxy API yang bisa memeriksa nilai-nilai tersebut. Lihat Variabel flow untuk daftar variabel yang ditetapkan oleh kebijakan ini.
Memverifikasi JWS yang dilepas dan ditandatangani dengan RS256 algoritma
Contoh kebijakan ini memverifikasi JWS yang terpisah dan ditandatangani dengan algoritma RS256. Untuk memverifikasi,
Anda perlu menyediakan
kunci publik. JWS diteruskan dalam permintaan proxy dengan menggunakan parameter formulir
bernama JWS
. Kunci publik terdapat dalam variabel bernama public.publickey
.
JWS yang terpisah menghilangkan payload dari JWS:
header..signature
Anda dapat meneruskan payload ke kebijakan VerifyJWS dengan menentukan nama variabel yang berisi payload ke
Elemen <DetachedContent>
. Konten yang ditentukan di <DetachedContent>
harus dalam bentuk asli yang tidak dienkode seperti saat tanda tangan JWS dibuat.
<VerifyJWS name="JWS-Verify-RS256"> <DisplayName>JWS Verify RS256</DisplayName> <Algorithm>RS256</Algorithm> <Source>request.formparam.JWS</Source> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <PublicKey> <Value ref="public.publickey"/> </PublicKey> <DetachedContent>private.payload</DetachedContent> </VerifyJWS>
Kebijakan menulis output-nya ke variabel konteks sehingga kebijakan atau kondisi berikutnya di proxy API yang bisa memeriksa nilai-nilai tersebut. Lihat Variabel flow untuk daftar variabel yang ditetapkan oleh kebijakan ini.
Menetapkan elemen kunci
Elemen yang Anda gunakan untuk menentukan kunci yang digunakan untuk memverifikasi JWS tergantung pada algoritma yang dipilih, seperti yang ditunjukkan dalam tabel berikut:
Algoritma | elemen utama | |
---|---|---|
HS* |
<SecretKey> <Value ref="private.secretkey"/> </SecretKey> |
|
RS*, ES*, PS* | <PublicKey> <Value ref="rsa_public_key"/> </PublicKey> atau: <PublicKey> <JWKS ref="jwks_val_ref_or_url"/> </PublicKey> |
|
*Untuk informasi selengkapnya tentang persyaratan utama, lihat Tentang algoritma enkripsi tanda tangan. |
Referensi elemen
Referensi kebijakan menjelaskan elemen dan atribut kebijakan Verifikasi JWS.
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
<VerifyJWS name="JWS" continueOnError="false" enabled="true" async="false">
Atribut berikut umum untuk semua elemen induk kebijakan.
Atribut | Deskripsi | Default | Kehadiran |
---|---|---|---|
nama |
Nama internal kebijakan. Karakter yang dapat Anda gunakan dalam nama dibatasi untuk:
A-Z0-9._\-$ % . Namun, UI pengelolaan Edge menerapkan
tertentu, seperti menghapus karakter yang bukan alfanumerik secara otomatis.
Secara opsional, gunakan elemen |
T/A | Wajib |
continueOnError |
Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Diharapkan
untuk sebagian besar kebijakan.
Setel ke |
salah | Opsional |
diaktifkan |
Setel ke true untuk menerapkan kebijakan.
Setel ke |
true | Opsional |
asinkron | Atribut ini tidak digunakan lagi. | salah | Tidak digunakan lagi |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
Gunakan selain atribut nama untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural language yang berbeda.
Default | Jika Anda menghapus elemen ini, nilai atribut nama kebijakan akan digunakan. |
Kehadiran | Opsional |
Jenis | String |
<Algorithm>
<Algorithm>HS256</Algorithm>
Menentukan algoritma enkripsi untuk menandatangani token. Algoritma RS*/PS*/ES* menggunakan pasangan kunci publik/rahasia, sedangkan algoritma HS* menggunakan rahasia bersama. Lihat juga Tentang algoritma enkripsi tanda tangan.
Anda dapat menentukan beberapa nilai yang dipisahkan dengan tanda koma. Misalnya "HS256, HS512" atau "RS256, PS256". Namun, Anda tidak dapat mengombinasikan algoritma HS* dengan algoritma lain atau algoritma ES* dengan yang lain karena algoritma ini memerlukan jenis kunci tertentu. Anda dapat menggabungkan algoritma RS* dan PS*.
Default | T/A |
Kehadiran | Wajib |
Jenis | String nilai yang dipisahkan koma |
Nilai yang valid | HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 |
<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 JWS 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 JWS standar yang terdaftar. Nilai klaim tambahan dapat berupa string, angka, boolean, peta, atau array. Sebuah peta hanya merupakan satu set pasangan nama/nilai. Nilai untuk klaim dari salah satu jenis ini dapat ditentukan secara eksplisit dalam konfigurasi kebijakan, atau secara tidak langsung melalui referensi ke variabel alur.
Default | T/A |
Kehadiran | Opsional |
Jenis |
String (default), angka, boolean, atau peta. Jenis default ke String jika tidak ada jenis yang ditentukan. |
Array | Tetapkan ke true untuk menunjukkan apakah nilai berupa array jenis. Default: salah |
Nilai yang valid | Nilai apa pun yang ingin Anda gunakan untuk klaim tambahan. |
Elemen <Claim>
menggunakan atribut berikut:
- name - (Wajib) Nama klaim.
- ref - (Opsional) Nama variabel flow. Jika ada, kebijakan akan menggunakan nilai variabel sebagai klaim. Jika atribut ref dan nilai klaim eksplisit ditentukan, elemen nilai eksplisit adalah default, dan digunakan jika variabel alur yang direferensikan tidak terselesaikan.
- type - (Opsional) Salah satu dari: string (default), angka, boolean, atau peta
- array - (Opsional) Tetapkan ke true untuk menunjukkan apakah nilai merupakan array jenis. Default: {i>false<i}.
<DetachedContent>
<DetachedContent>variable-name-here</DetachedContent>
JWS yang dihasilkan dengan payload konten berbentuk:
header.payload.signature
Jika Anda menggunakan kebijakan GenerateJWS untuk membuat payload terpisah, JWS yang dihasilkan akan menghilangkan payload dan dalam bentuk:
header..signature
Untuk payload yang terlepas, Anda dapat meneruskan payload ke kebijakan VerifyJWS menggunakan metode
Elemen <DetachedContent>
. Payload konten yang ditentukan harus berada dalam
bentuk asli yang tidak dikodekan, seperti
saat tanda tangan JWS dibuat.
Kebijakan akan menampilkan error saat:
<DetachedContent>
ditentukan saat JWS tidak berisi konten yang terpisah payload (kode error adalahsteps.jws.ContentIsNotDetached
).<DetachedContent>
dihilangkan dan JWS memiliki payload konten yang terpisah (kode kesalahannya adalahsteps.jws.InvalidSignature
).
Default | N/A |
Kehadiran | Opsional |
Jenis | Referensi variabel |
<IgnoreCriticalHeaders>
<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>
Tetapkan ke false jika Anda ingin kebijakan menampilkan error saat header apa pun yang tercantum dalam
crit pada JWS tidak tercantum dalam elemen <KnownHeaders>
.
Tetapkan ke true untuk menyebabkan kebijakan VerifyJWS mengabaikan header crit.
Salah satu alasan untuk menetapkan elemen ini ke true adalah jika Anda berada di lingkungan pengujian dan Anda tidak ingin kebijakan itu gagal karena {i>header<i} yang hilang.
Default | salah |
Kehadiran | Opsional |
Jenis | Boolean |
Nilai yang valid | benar atau salah |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
Tetapkan ke false jika Anda ingin kebijakan menampilkan error saat variabel yang direferensikan ditentukan dalam kebijakan itu tidak dapat diselesaikan. Tetapkan ke true untuk memperlakukan variabel yang tidak dapat diselesaikan sebagai string kosong (null).
Default | salah |
Kehadiran | Opsional |
Jenis | Boolean |
Nilai yang valid | benar atau salah |
<KnownHeaders>
<KnownHeaders>a,b,c</KnownHeaders> or: <KnownHeaders ref=’variable_containing_headers’/>
Kebijakan GenerateJWS menggunakan elemen <CriticalHeaders>
untuk mengisi
crit dalam token. Contoh:
{ “typ: “...”, “alg” : “...”, “crit” : [ “a”, “b”, “c” ], }
Kebijakan VerifyJWS memeriksa header crit di JWS, jika ada, dan untuk setiap item 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 VerifyJWS gagal.
Secara opsional, Anda dapat mengonfigurasi kebijakan VerifyJWS untuk mengabaikan header crit dengan
menyetel elemen <IgnoreCriticalHeaders>
ke true
.
Default | T/A |
Kehadiran | Opsional |
Jenis | Array string yang dipisahkan koma |
Nilai yang valid | Baik array maupun nama variabel yang berisi array. |
<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 satu set kunci publik. Gunakan hanya jika algoritmanya adalah salah satu dari RS256/RS384/RS512, PS256/PS384/PS512, atau ES256/ES384/ES512.
Jika JWS masuk membawa ID kunci yang ada di rangkaian JWKS, maka kebijakan tersebut akan menggunakan kunci publik yang benar untuk memverifikasi tanda tangan JWS. Untuk detailnya tentang fitur ini, lihat Menggunakan JSON Web Key Set (JWKS) untuk memverifikasi JWS.
Jika Anda mengambil nilai dari URL publik, Edge akan meng-cache JWKS selama 300 detik. Saat cache berakhir, Edge mengambil JWKS lagi.
Default | T/A |
Kehadiran | Untuk memverifikasi JWS menggunakan algoritma RSA, Anda harus menggunakan JWKS atau Value . |
Jenis | String |
Nilai yang valid | Variabel alur, nilai string, atau URL. |
<PublicKey/Value>
<PublicKey> <Value ref="public.publickey"/> </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 yang digunakan untuk memverifikasi tanda tangan di JWS. Gunakan atribut ref untuk meneruskan kunci dalam variabel flow, atau menentukan kunci yang dienkode ke PEM secara langsung. Gunakan hanya bila algoritmenya adalah salah satu dari RS256/RS384/RS512, PS256/PS384/PS512, atau ES256/ES384/ES512.
Default | T/A |
Kehadiran | Untuk memverifikasi JWS yang ditandatangani dengan algoritma RSA, Anda harus menggunakan JWKS atau Elemen nilai. |
Jenis | String |
Nilai yang valid | Variabel aliran atau string. |
<SecretKey/Value>
<SecretKey> <Value ref="private.your-variable-name"/> </SecretKey>
Memberikan kunci rahasia yang digunakan untuk memverifikasi atau menandatangani token dengan algoritma HMAC. Hanya gunakan jika algoritmanya adalah salah satu dari HS256, HS384, HS512. Gunakan atribut ref untuk meneruskan kunci dalam variabel flow.
Default | T/A |
Kehadiran | Diperlukan untuk algoritma HMAC. |
Jenis | String |
Nilai yang valid |
Variabel aliran yang mengacu ke string.
Catatan: Jika variabel flow, variabel tersebut harus memiliki awalan "pribadi". Contoh,
|
<Source>
<Source>JWS-variable</Source>
Jika ada, tentukan variabel alur yang diharapkan oleh kebijakan untuk menemukan JWS memverifikasi.
Default | request.header.authorization (Lihat catatan di atas untuk mengetahui informasi penting
tentang {i>default<i}). |
Kehadiran | Opsional |
Jenis | String |
Nilai yang valid | Nama variabel aliran Edge. |
Variabel flow
Setelah berhasil, kebijakan Verifikasi JWS dan Dekode JWS akan ditetapkan variabel konteks sesuai dengan pola ini:
jws.{policy_name}.{variable_name}
Misalnya, jika nama kebijakan adalah verify-jws
, kebijakan akan menyimpan
algoritma yang ditentukan dalam JWS untuk variabel konteks ini:
jws.verify-jws.header.algorithm
Nama variabel | Deskripsi |
---|---|
decoded.header.name |
Nilai header yang dapat diurai JSON dalam payload. Satu variabel ditetapkan untuk
setiap {i>header<i} dalam {i>payload<i}. Meskipun Anda juga dapat menggunakan variabel flow header.name ,
variabel ini adalah variabel yang direkomendasikan
untuk mengakses {i>header<i}. |
header.algorithm |
Algoritma penandatanganan yang digunakan pada JWS. Misalnya, RS256, HS384, dan sebagainya. Lihat Parameter Header(Algoritma) untuk mengetahui informasi selengkapnya. |
header.kid |
ID Kunci, jika ditambahkan saat JWS dibuat. Lihat juga "Menggunakan Kumpulan Kunci Web JSON (JWKS)" di JWT dan JWS ringkasan kebijakan untuk memverifikasi JWS. Lihat Parameter Header(Key ID) untuk mengetahui informasi selengkapnya. |
header.type |
Nilai jenis header. Lihat Parameter Header(Jenis) untuk mengetahui informasi selengkapnya. |
header.name |
Nilai header bernama (standar atau tambahan). Salah satunya akan ditetapkan untuk setiap {i>header<i} tambahan di bagian {i> header<i} JWS. |
header-json |
Header dalam format JSON. |
payload |
Payload JWS jika JWS memiliki payload yang terpasang. Untuk payload yang dilepas, variabel ini kosong. |
valid |
Dalam kasus VerifyJWS, variabel ini akan bernilai benar
ketika tanda tangan diverifikasi, dan
waktu saat ini adalah sebelum masa berlaku token habis, dan setelah nilai token {i>notBefore<i}, jika
tersedia. Jika tidak, flag akan bernilai salah.
Dalam kasus DecodeJWS, variabel ini belum ditetapkan. |
Referensi error
Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan dan variabel kesalahan yang disetel oleh Edge saat kebijakan ini memicu error. Informasi ini penting untuk diketahui apakah Anda mengembangkan aturan kesalahan untuk menangani kesalahan. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani kesalahan.
Error runtime
Error ini dapat terjadi saat kebijakan dieksekusi.
Kode kesalahan | Status HTTP | Terjadi saat |
---|---|---|
steps.jws.AlgorithmInTokenNotPresentInConfiguration |
401 | Terjadi saat kebijakan verifikasi memiliki beberapa algoritma |
steps.jws.AlgorithmMismatch |
401 | Algoritme yang ditentukan dalam header oleh kebijakan Pembuatan tidak cocok dengan yang diharapkan dalam kebijakan Verifikasi. Algoritma yang ditentukan harus cocok. |
steps.jws.ContentIsNotDetached |
401 | <DetachedContent> ditentukan saat JWS tidak berisi payload konten terpisah. |
steps.jws.FailedToDecode |
401 | Kebijakan tidak dapat mendekode JWS. JWS mungkin rusak. |
steps.jws.InsufficientKeyLength |
401 | Untuk kunci kurang dari 32 byte untuk algoritma HS256 |
steps.jws.InvalidClaim |
401 | Karena klaim atau klaim tidak cocok, atau ketidakcocokan header atau header tidak ada. |
steps.jws.InvalidCurve |
401 | Kurva yang ditentukan oleh kunci tidak valid untuk algoritma Kurva Eliptis. |
steps.jws.InvalidJsonFormat |
401 | JSON yang tidak valid ditemukan di header JWS. |
steps.jws.InvalidJws |
401 | Error ini terjadi saat verifikasi tanda tangan JWS gagal. |
steps.jws.InvalidPayload |
401 | Payload JWS tidak valid. |
steps.jws.InvalidSignature |
401 | <DetachedContent> dihilangkan dan JWS memiliki payload konten terpisah. |
steps.jws.KeyIdMissing |
401 | Kebijakan Verifikasi menggunakan JWKS sebagai sumber untuk kunci publik, tetapi JWS yang ditandatangani tidak menyertakan properti kid di header. |
steps.jws.KeyParsingFailed |
401 | Kunci publik tidak dapat diuraikan dari informasi kunci yang diberikan. |
steps.jws.MissingPayload |
401 | Payload JWS tidak ada. |
steps.jws.NoAlgorithmFoundInHeader |
401 | Terjadi saat JWS menghilangkan header algoritma. |
steps.jws.NoMatchingPublicKey |
401 | Kebijakan Verifikasi menggunakan JWKS sebagai sumber untuk kunci publik, tetapi kid dalam JWS yang ditandatangani tidak tercantum di JWKS. |
steps.jws.UnhandledCriticalHeader |
401 | Header yang ditemukan oleh kebijakan Verifikasi JWS di header crit tidak tercantum di KnownHeaders . |
steps.jws.UnknownException |
401 | Terjadi pengecualian yang tidak diketahui. |
steps.jws.WrongKeyType |
401 | Jenis kunci yang ditentukan salah. Misalnya, jika Anda menentukan kunci RSA untuk algoritma Kurva Elliptik, atau kunci kurva untuk algoritma RSA. |
Error saat deployment
Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.
Nama error | Terjadi saat |
---|---|
InvalidAlgorithm |
Satu-satunya nilai yang valid adalah: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512. |
|
Kemungkinan error deployment lainnya. |
Variabel kesalahan
Variabel ini ditetapkan saat terjadi error runtime. Untuk informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.
Variabel | Di mana | Contoh |
---|---|---|
fault.name="fault_name" |
fault_name adalah nama kesalahan, seperti yang tercantum dalam tabel Error runtime di atas. Nama kesalahan adalah bagian terakhir dari kode kesalahan. | fault.name Matches "TokenExpired" |
JWS.failed |
Semua kebijakan JWS menetapkan variabel yang sama jika terjadi kegagalan. | jws.JWS-Policy.failed = true |
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="JWS Policy Errors"> <Step> <Name>JavaScript-1</Name> <Condition>(fault.name Matches "TokenExpired")</Condition> </Step> <Condition>JWS.failed=true</Condition> </FaultRule> </FaultRules>