Kebijakan GenerateJWS

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

Apa

Membuat JWS bertanda tangan, dengan kumpulan klaim yang dapat dikonfigurasi. JWS kemudian dapat dikembalikan ke klien, dikirim ke target backend, atau digunakan dengan cara lain. Lihat Ringkasan kebijakan JWS dan JWT untuk pengantar mendetail.

Untuk mempelajari bagian-bagian JWS serta cara mengenkripsi dan menandatanganinya, lihat RFC7515.

Video

Tonton video singkat untuk mempelajari cara membuat JWT bertanda tangan. Meskipun video ini khusus untuk membuat JWT, banyak konsepnya sama dengan JWS.

Contoh

• Membuat JWS terlampir yang ditandatangani dengan algoritma HS256
• Buat JWS terpisah yang ditandatangani dengan algoritma RS256

Buat JWS terlampir yang ditandatangani dengan algoritma HS256

Contoh kebijakan ini membuat JWS terlampir dan menandatanganinya menggunakan algoritma HS256. HS256 mengandalkan rahasia bersama untuk menandatangani dan memverifikasi tanda tangan.

JWS terlampir berisi header, payload, dan tanda tangan yang dienkode:

header.payload.signature

Tetapkan <DetachContent> ke benar (true) untuk membuat konten yang terpisah. Lihat Bagian-bagian JWS/JWT untuk mengetahui struktur dan format JWS lebih lanjut.

Gunakan elemen <Payload> untuk menentukan payload JWS mentah yang tidak dienkode. Dalam contoh ini, variabel berisi payload. Saat tindakan kebijakan ini dipicu, Edge mengenkode header dan payload JWS, lalu menambahkan tanda tangan yang dienkode untuk menandatangani JWS secara digital.

Konfigurasi kebijakan di bawah ini membuat JWS dari payload yang ada dalam variabel private.payload.

<GenerateJWS name="JWS-Generate-HS256">
    <DisplayName>JWS Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <Payload ref="private.payload" />
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

Buat JWS terpisah yang ditandatangani dengan algoritma RS256

Contoh kebijakan ini membuat JWS terpisah dan menandatanganinya menggunakan algoritma RS256. Membuat tanda tangan RS256 bergantung pada kunci pribadi RSA, yang harus diberikan dalam bentuk yang dienkode PEM.

JWS yang terlepas menghilangkan payload dari JWS:

header..signature

Gunakan elemen <Payload> untuk menentukan payload JWS mentah yang tidak dienkode. Saat kebijakan ini dipicu, Edge mengenkode header dan payload JWS, lalu menggunakannya untuk membuat tanda tangan yang dienkode. Namun, JWS yang dihasilkan menghilangkan payload. Anda dapat meneruskan payload ke kebijakan VerifyJWS menggunakan elemen <DetachedContent> dari kebijakan VerifyJWS.

<GenerateJWS name="JWS-Generate-RS256">
    <DisplayName>JWS Generate RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Payload ref="private.payload" />
    <DetachContent>true</DetachContent>
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

Menetapkan elemen utama

Elemen yang Anda gunakan untuk menentukan kunci yang digunakan untuk membuat JWS bergantung pada algoritma yang dipilih, seperti yang ditunjukkan dalam tabel berikut:

<SecretKey>
  <Value ref="private.secretkey"/>
  <Id>1918290</Id>
</SecretKey>

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

Referensi elemen untuk Generate JWS

Referensi kebijakan menjelaskan elemen dan atribut kebijakan Generate JWS.

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 diterapkan ke elemen tingkat teratas

<GenerateJWS name="JWS" continueOnError="false" enabled="true" async="false">

Atribut berikut 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>algorithm-here</Algorithm>

Menentukan algoritma enkripsi untuk menandatangani token.

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

Menempatkan pasangan nama/nilai klaim tambahan di header untuk JWS.

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.

<CriticalHeaders>

<CriticalHeaders>a,b,c</CriticalHeaders>

or:

<CriticalHeaders ref=’variable_containing_headers’/>

Menambahkan header penting, crit, ke JWS. Header crit adalah array nama header yang harus diketahui dan dikenali oleh penerima JWS. Contoh:

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

Saat runtime, kebijakan VerifyJWS memeriksa header crit. Untuk setiap header yang tercantum di header crit, header tersebut akan memeriksa apakah elemen <KnownHeaders> kebijakan VerifyJWS juga mencantumkan header tersebut. Header apa pun yang ditemukan kebijakan VerifyJWS di crit yang tidak tercantum di <KnownHeaders> menyebabkan kebijakan VerifyJWS gagal.

<DetachContent>

<DetachContent>true|false</DetachContent>

Menentukan apakah akan membuat JWS dengan payload terpisah, <DetachContent>true</DetachContent>, atau tidak, <DetachContent>false</DetachContent>.

Jika Anda menentukan false, default, JWS yang dihasilkan akan berbentuk:

header.payload.signature

Jika Anda menentukan benar (true) untuk membuat payload yang terpisah, JWS yang dihasilkan akan menghilangkan payload dan berbentuk:

header..signature

Dengan payload yang terpisah, Anda dapat meneruskan payload asli yang tidak dienkode ke kebijakan VerifyJWS dengan menggunakan elemen <DetachedContent> dari kebijakan VerifyJWS.

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

<OutputVariable>

<OutputVariable>JWS-variable</OutputVariable>

Menentukan tempat untuk menempatkan JWS yang dihasilkan oleh kebijakan ini. Secara default, nilai ini ditempatkan ke dalam variabel alur jws.POLICYNAME.generated_jws.

<Payload>

<Payload ref="flow-variable-name-he>re&quo<t; /

o>r

Payloadpay<load-val>ue/Payload

Menentukan payload JWS mentah yang tidak dienkode. Tentukan variabel yang berisi payload, atau string.

<PrivateKey/Id>

<PrivateKey>
  <Id ref="flow-variable-name-h>e<re"/
/>Privat<eKey

or

>Pri<va>teKey
  Idyour-id-<val>u<e-here/Id
/>PrivateKey

Menentukan ID kunci (kid) yang akan disertakan dalam header JWS. Gunakan hanya jika algoritma adalah salah satu dari RS256/RS384/RS512, PS256/PS384/PS512, atau ES256/ES384/ES512.

<PrivateKey/Password>

<PrivateKey>
  <Password ref="private.privatekey-passw>o<rd"/
/>PrivateKey

Tentukan sandi yang harus digunakan kebijakan untuk mendekripsi kunci pribadi, jika perlu. Gunakan atribut ref untuk meneruskan kunci dalam variabel alur. Gunakan hanya jika algoritma adalah salah satu dari RS256/RS384/RS512, PS256/PS384/PS512, atau ES256/ES384/ES512.

<PrivateKey/Value>

<PrivateKey>
  <Value ref="private.variable-name-h>e<re"/
/>PrivateKey

Menentukan kunci pribadi berenkode PEM yang digunakan untuk menandatangani JWS. Gunakan atribut ref untuk meneruskan kunci dalam variabel alur. Gunakan hanya jika algoritma adalah salah satu dari RS256/RS384/RS512, PS256/PS384/PS512, atau ES256/ES384/ES512.

<SecretKey/Id>

<SecretKey>
  <Id ref="flow-variable-name-h>e<re"/
>/Secre<tKey

or
>
Se<cr>etKey
  Idyour-id-<val>u<e-here/Id
>/SecretKey

Menentukan ID kunci (kid) yang akan disertakan dalam header JWS dari JWS yang ditandatangani dengan algoritma HMAC. Gunakan hanya jika algoritma adalah salah satu dari HS256/HS384/HS512.

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-n>a<me"/
>/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. Gunakan atribut ref untuk meneruskan kunci dalam variabel alur.

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

Variabel alur

Kebijakan Generate JWS tidak menetapkan variabel alur.

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

Variabel ini ditetapkan saat error runtime terjadi. Untuk mengetahui 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 teks tersebut dapat berubah.

Contoh aturan error

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