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 header ke dalam variabel konteks sehingga kebijakan atau kondisi berikutnya dapat memeriksa nilai tersebut untuk membuat keputusan otorisasi atau pemilihan rute. Lihat ringkasan kebijakan JWS dan JWT untuk pengantar yang mendetail.
Jika JWS terverifikasi dan valid, permintaan diizinkan untuk melanjutkan. Jika tanda tangan JWS tidak dapat diverifikasi atau jika JWS tidak valid karena beberapa jenis error, semua pemrosesan akan berhenti dan error akan ditampilkan dalam respons.
Untuk mempelajari bagian-bagian JWS dan cara JWS 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 konsep yang sama untuk JWS.
Contoh
- Memverifikasi JWS terlampir yang ditandatangani dengan algoritma HS256
- Memverifikasi JWS terpisah yang ditandatangani dengan algoritma RS256
Verifikasi JWS terlampir yang ditandatangani dengan algoritma HS256
Kebijakan contoh ini memverifikasi JWS terlampir yang ditandatangani dengan algoritma enkripsi HS256, HMAC menggunakan checksum SHA-256. JWS diteruskan dalam permintaan proxy menggunakan parameter formulir bernama JWS
. Kunci tersebut terdapat dalam variabel bernama private.secretkey
.
JWS terlampir 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 flow Edge, yang dapat
diambil dari Edge KVM, misalnya).
<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 ini menulis output-nya ke variabel konteks sehingga kebijakan atau kondisi berikutnya dalam proxy API dapat memeriksa nilai tersebut. Lihat Variabel flow untuk mengetahui daftar variabel yang ditetapkan oleh kebijakan ini.
Memverifikasi JWS terpisah yang ditandatangani dengan algoritma RS256
Kebijakan contoh ini memverifikasi JWS terpisah yang ditandatangani dengan algoritma RS256. Untuk memverifikasi, Anda harus menyediakan kunci publik. JWS diteruskan dalam permintaan proxy menggunakan parameter formulir bernama JWS
. Kunci publik terdapat dalam variabel bernama public.publickey
.
JWS yang terlepas akan 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 dalam <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 ini menulis output-nya ke variabel konteks sehingga kebijakan atau kondisi berikutnya dalam proxy API dapat memeriksa nilai tersebut. Lihat Variabel flow untuk mengetahui daftar variabel yang ditetapkan oleh kebijakan ini.
Menetapkan elemen utama
Elemen yang Anda gunakan untuk menentukan kunci yang digunakan untuk memverifikasi JWS bergantung pada algoritme yang dipilih, seperti yang ditunjukkan pada tabel berikut:
Algorithm | 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 mengetahui informasi selengkapnya tentang persyaratan utama, lihat Tentang algoritma enkripsi tanda tangan. |
Referensi elemen
Referensi kebijakan menjelaskan elemen dan atribut kebijakan Verify JWS.
Catatan: Konfigurasi akan sedikit berbeda, tergantung algoritma enkripsi yang Anda gunakan. Lihat Contoh untuk mengetahui contoh yang menunjukkan konfigurasi untuk kasus penggunaan tertentu.
Atribut yang berlaku untuk elemen tingkat atas
<VerifyJWS name="JWS" continueOnError="false" enabled="true" async="false">
Atribut berikut bersifat umum untuk semua elemen induk kebijakan.
Atribut | Deskripsi | Default | Kehadiran |
---|---|---|---|
name |
Nama internal kebijakan. Karakter yang dapat digunakan dalam nama dibatasi untuk:
A-Z0-9._\-$ % . Namun, UI pengelolaan Edge menerapkan pembatasan
tambahan, seperti otomatis menghapus karakter yang bukan alfanumerik.
Atau, gunakan elemen |
T/A | Wajib |
continueOnError |
Setel ke false untuk menampilkan error jika kebijakan gagal. Ini adalah perilaku
yang wajar untuk sebagian besar kebijakan.
Setel ke |
false | Opsional |
diaktifkan |
Setel ke true untuk menerapkan kebijakan.
Setel ke |
true | Opsional |
async | Atribut ini sudah tidak digunakan lagi. | false | Tidak digunakan lagi |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
Gunakan selain atribut nama untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural-language yang berbeda.
Default | Jika Anda menghilangkan elemen ini, nilai atribut nama kebijakan akan digunakan. |
Kehadiran | Opsional |
Jenis | String |
<Algorithm>
<Algorithm>HS256</Algorithm>
Menentukan algoritma enkripsi untuk menandatangani token. Algoritma RS*/PS*/ES* menggunakan pasangan kunci publik/rahasia, sedangkan algoritma HS* menggunakan rahasia bersama. Lihat juga Tentang algoritma enkripsi tanda tangan.
Anda dapat menentukan beberapa nilai yang dipisahkan dengan koma. Misalnya "HS256, HS512" atau "RS256, PS256". Namun, Anda tidak dapat menggabungkan algoritme HS* dengan algoritme lain atau algoritma ES* dengan yang lain karena memerlukan jenis kunci tertentu. Anda dapat menggabungkan algoritma RS* dan PS*.
Default | T/A |
Kehadiran | Wajib |
Jenis | String nilai yang dipisahkan koma |
Nilai yang valid | HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 |
<Header/Klaim Tambahan>
<AdditionalHeaders> <Claim name='claim1'>explicit-value-of-claim-here</Claim> <Claim name='claim2' ref='variable-name-here'/> <Claim name='claim3' ref='variable-name-here' type='boolean'/> <Claim name='claim4' ref='variable-name' type='string' array='true'/> </AdditionalHeaders>
Memvalidasi bahwa header JWS berisi pasangan nama/nilai klaim tambahan yang ditentukan dan 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. Peta hanyalah sekumpulan pasangan nama/nilai. Nilai untuk klaim jenis ini dapat ditentukan secara eksplisit dalam konfigurasi kebijakan, atau secara tidak langsung melalui referensi ke variabel flow.
Default | T/A |
Kehadiran | Opsional |
Jenis |
String (default), angka, boolean, atau peta. Jenis akan ditetapkan secara default ke String jika tidak ada jenis yang ditentukan. |
Array | Tetapkan ke true untuk menunjukkan apakah nilainya adalah array jenis. Default: false |
Nilai yang valid | Nilai apa pun yang ingin Anda gunakan untuk klaim tambahan. |
Elemen <Claim>
menggunakan atribut berikut:
- name - (Wajib) Nama klaim.
- ref - (Opsional) Nama variabel flow. Jika ada, kebijakan akan menggunakan nilai variabel ini sebagai klaim. Jika atribut ref dan nilai klaim eksplisit ditentukan, nilai eksplisitnya adalah nilai default, dan digunakan jika variabel alur yang direferensikan tidak terselesaikan.
- type - (Opsional) Salah satu dari: string (default), angka, boolean, atau peta
- array - (Opsional) Tetapkan ke true untuk menunjukkan apakah nilai merupakan array jenis. Default: false.
<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 berbentuk:
header..signature
Untuk payload yang terlepas, Anda dapat meneruskan payload ke kebijakan VerifyJWS menggunakan elemen <DetachedContent>
. Payload konten yang ditentukan harus dalam
bentuk asli yang tidak dienkode seperti saat tanda tangan JWS dibuat.
Kebijakan ini menampilkan error saat:
<DetachedContent>
ditentukan saat JWS tidak berisi payload konten terpisah (kode kesalahan adalahsteps.jws.ContentIsNotDetached
).<DetachedContent>
dihilangkan dan JWS memiliki payload konten terpisah (kode kesalahan 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 header crit JWS tidak tercantum dalam elemen <KnownHeaders>
.
Setel ke true agar kebijakan VerifyJWS mengabaikan header crit.
Salah satu alasan untuk menetapkan elemen ini ke true adalah jika Anda berada di lingkungan pengujian dan tidak ingin kebijakan gagal karena header tidak ada.
Default | false |
Kehadiran | Opsional |
Jenis | Boolean |
Nilai yang valid | benar atau salah |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
Tetapkan ke false jika Anda ingin kebijakan menampilkan error saat variabel yang direferensikan dan ditentukan dalam kebijakan tidak dapat diselesaikan. Tetapkan ke true untuk memperlakukan variabel yang tidak dapat di-resolve sebagai string kosong (null).
Default | false |
Kehadiran | Opsional |
Jenis | Boolean |
Nilai yang valid | benar atau salah |
<KnownHeaders>
<KnownHeaders>a,b,c</KnownHeaders> or: <KnownHeaders ref=’variable_containing_headers’/>
Kebijakan GenerateJWS menggunakan elemen <CriticalHeaders>
untuk mengisi header crit dalam token. Contoh:
{ “typ: “...”, “alg” : “...”, “crit” : [ “a”, “b”, “c” ], }
Kebijakan VerifyJWS memeriksa header crit di JWS, jika ada, dan untuk setiap item yang tercantum, kebijakan akan memeriksa apakah elemen <KnownHeaders>
juga mencantumkan header tersebut. Elemen
<KnownHeaders>
dapat berisi superset item yang tercantum dalam crit.
Hanya perlu bahwa semua header yang tercantum dalam crit dicantumkan dalam elemen <KnownHeaders>
. Header apa pun yang ditemukan kebijakan di crit
yang tidak tercantum di <KnownHeaders>
akan menyebabkan kebijakan VerifyJWS gagal.
Secara opsional, Anda dapat mengonfigurasi kebijakan VerifyJWS untuk mengabaikan header crit dengan menetapkan elemen <IgnoreCriticalHeaders>
ke true
.
Default | T/A |
Kehadiran | Opsional |
Jenis | Array string yang dipisahkan koma |
Nilai yang valid | Baik array atau nama variabel yang berisi array. |
<PublicKey/JWKS>
<!-- Specify the JWKS. --> <PublicKey> <JWKS>jwks-value-here</JWKS> </PublicKey> or: <!-- Specify a variable containing the JWKS. --> <PublicKey> <JWKS ref="public.jwks"/> </PublicKey> or: <!-- Specify a public URL that returns the JWKS. The URL is static, meaning you cannot set it using a variable. --> <PublicKey> <JWKS uri="jwks-url"/> </PublicKey>
Menentukan nilai dalam format JWKS (RFC 7517) yang berisi kumpulan kunci publik. Gunakan hanya jika algoritmenya adalah salah satu dari RS256/RS384/RS512, PS256/PS384/PS512, atau ES256/ES384/ES512.
Jika JWS masuk memiliki ID kunci yang ada dalam kumpulan JWKS, kebijakan akan menggunakan kunci publik yang benar untuk memverifikasi tanda tangan JWS. Untuk mengetahui detail tentang fitur ini, lihat Menggunakan Set Kunci Web JSON (JWKS) untuk memverifikasi JWS.
Jika Anda mengambil nilai dari URL publik, Edge akan menyimpan JWKS dalam cache selama 300 detik. Saat cache berakhir, Edge akan mengambil JWKS lagi.
Default | T/A |
Kehadiran | Untuk memverifikasi JWS menggunakan algoritme RSA, Anda harus menggunakan JWKS atau elemen Nilai. |
Jenis | String |
Nilai yang valid | Variabel flow, 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 tentukan kunci yang dienkode ke PEM secara langsung. Gunakan hanya jika algoritmenya adalah salah satu dari RS256/RS384/RS512, PS256/PS384/PS512, atau ES256/ES384/ES512.
Default | T/A |
Kehadiran | Untuk memverifikasi JWS yang ditandatangani dengan algoritma RSA, Anda harus menggunakan elemen JWKS atau Nilai. |
Jenis | String |
Nilai yang valid | String atau variabel flow. |
<SecretKey/Value>
<SecretKey> <Value ref="private.your-variable-name"/> </SecretKey>
Memberikan kunci rahasia yang digunakan untuk memverifikasi atau menandatangani token dengan algoritma HMAC. Gunakan hanya jika algoritmenya adalah salah satu dari HS256, HS384, HS512. Gunakan atribut ref untuk meneruskan kunci dalam variabel flow.
Default | T/A |
Kehadiran | Diperlukan untuk algoritma HMAC. |
Jenis | String |
Nilai yang valid |
Variabel flow yang mengacu pada string.
Catatan: Variabel flow harus memiliki awalan "private". Contoh,
|
<Sumber>
<Source>JWS-variable</Source>
Jika ada, tentukan variabel flow tempat kebijakan mengharapkan JWS ditemukan untuk diverifikasi.
Default | request.header.authorization (Lihat catatan di atas untuk informasi penting
tentang default). |
Kehadiran | Opsional |
Jenis | String |
Nilai yang valid | Nama variabel alur Edge. |
Flow variables
Upon success, the Verify JWS and Decode JWS policies set context variables according to this pattern:
jws.{policy_name}.{variable_name}
For example, if the policy name is verify-jws
, then the policy will store
the algorithm specified in the JWS to this context variable:
jws.verify-jws.header.algorithm
Variable name | Description |
---|---|
decoded.header.name |
The JSON-parsable value of a header in the payload. One variable is set for
every header in the payload. While you can also use the header.name flow variables,
this is the recommended variable to use to access a header. |
header.algorithm |
The signing algorithm used on the JWS. For example, RS256, HS384, and so on. See (Algorithm) Header Parameter for more. |
header.kid |
The Key ID, if added when the JWS was generated. See also "Using a JSON Web Key Set (JWKS)" at JWT and JWS policies overview to verify a JWS. See (Key ID) Header Parameter for more. |
header.type |
The header type value. See (Type) Header Parameter for more. |
header.name |
The value of the named header (standard or additional). One of these will be set for every additional header in the header portion of the JWS. |
header-json |
The header in JSON format. |
payload |
The JWS payload if the JWS has an attached payload. For a detached payload, this variable is empty. |
valid |
In the case of VerifyJWS, this variable will be true when the signature is verified, and
the current time is before the token expiry, and after the token notBefore value, if they
are present. Otherwise false.
In the case of DecodeJWS, this variable is not set. |
Referensi error
This section describes the fault codes and error messages that are returned and fault variables that are set by Edge 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.jws.AlgorithmInTokenNotPresentInConfiguration |
401 | Occurs when the verification policy has multiple algorithms |
steps.jws.AlgorithmMismatch |
401 | The algorithm specified in the header by the Generate policy did not match the one expected in the Verify policy. The algorithms specified must match. |
steps.jws.ContentIsNotDetached |
401 | <DetachedContent> is specified when the JWS does not contain a
detached content payload. |
steps.jws.FailedToDecode |
401 | The policy was unable to decode the JWS. The JWS is possibly corrupted. |
steps.jws.InsufficientKeyLength |
401 | For a key less than 32 bytes for the HS256 algorithm |
steps.jws.InvalidClaim |
401 | For a missing claim or claim mismatch, or a missing header or header mismatch. |
steps.jws.InvalidCurve |
401 | The curve specified by the key is not valid for the Elliptic Curve algorithm. |
steps.jws.InvalidJsonFormat |
401 | Invalid JSON found in the JWS header. |
steps.jws.InvalidJws |
401 | This error occurs when the JWS signature verification fails. |
steps.jws.InvalidPayload |
401 | The JWS payload is invalid. |
steps.jws.InvalidSignature |
401 | <DetachedContent> is omitted and the JWS has a detached content payload. |
steps.jws.KeyIdMissing |
401 | The Verify policy uses a JWKS as a source for public keys, but the signed JWS does not
include a kid property in the header. |
steps.jws.KeyParsingFailed |
401 | The public key could not be parsed from the given key information. |
steps.jws.MissingPayload |
401 | The JWS payload is missing. |
steps.jws.NoAlgorithmFoundInHeader |
401 | Occurs when the JWS omits the algorithm header. |
steps.jws.NoMatchingPublicKey |
401 | The Verify policy uses a JWKS as a source for public keys, but the kid
in the signed JWS is not listed in the JWKS. |
steps.jws.UnhandledCriticalHeader |
401 | A header found by the Verify JWS policy in the crit header is not
listed in KnownHeaders . |
steps.jws.UnknownException |
401 | An unknown exception occurred. |
steps.jws.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 | Occurs when |
---|---|
InvalidAlgorithm |
The only valid values are: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512. |
|
Other possible deployment errors. |
Variabel kesalahan
Variabel ini ditetapkan saat terjadi error runtime. Untuk informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.
Variabel | Dari mana | Contoh |
---|---|---|
fault.name="fault_name" |
fault_name adalah nama kesalahan, seperti yang tercantum dalam tabel Error runtime di atas. Nama kesalahan adalah bagian terakhir dari kode kesalahan. | fault.name Matches "TokenExpired" |
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 menjebak bagian errorcode
dari respons
error. 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>