Halaman ini berlaku untuk Apigee dan Apigee Hybrid.
Baca dokumentasi Apigee Edge.
Apa
Menghasilkan JWT bertanda tangan atau JWT terenkripsi, dengan sekumpulan klaim yang dapat dikonfigurasi. JWT kemudian dapat ditampilkan ke klien, dikirim ke target backend, atau digunakan dengan cara lain. Lihat ringkasan kebijakan JWS dan JWT untuk pengantar mendetail.
Kebijakan ini merupakan Kebijakan yang dapat diperluas, dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau pemanfaatan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaan, lihat Jenis kebijakan.
Bagaimana/Berapa
Apakah kebijakan menghasilkan JWT yang ditandatangani atau dienkripsi bergantung pada elemen yang Anda gunakan untuk menentukan algoritma yang menghasilkan JWT:
- Jika Anda menggunakan elemen
<Algorithm>
, kebijakan ini akan menghasilkan JWT yang ditandatangani. - Jika Anda menggunakan elemen
<Algorithms>
, kebijakan ini akan menghasilkan JWT terenkripsi.
Video
Tonton video singkat untuk mempelajari cara menghasilkan JWT yang ditandatangani.
Membuat JWT Bertanda Tangan
Bagian ini menjelaskan cara menghasilkan JWT yang ditandatangani. Untuk JWT yang ditandatangani, gunakan elemen <Algorithm>
untuk menentukan algoritma penandatanganan kunci.
Contoh untuk JWT yang ditandatangani
Contoh berikut mengilustrasikan cara menghasilkan JWT yang ditandatangani.
Algoritma HS256
Contoh kebijakan ini menghasilkan JWT baru dan menandatanganinya menggunakan algoritma HS256. HS256 bergantung pada rahasia bersama untuk menandatangani dan memverifikasi tanda tangan.
Saat tindakan kebijakan ini dipicu, Apigee akan mengenkode header dan payload JWT, lalu menandatangani JWT secara digital. Lihat video di atas untuk mengetahui contoh lengkapnya, termasuk cara mengajukan permintaan ke kebijakan.
Konfigurasi kebijakan di sini akan membuat JWT dengan serangkaian klaim standar seperti yang ditetapkan oleh spesifikasi JWT, termasuk masa berlaku 1 jam, serta klaim tambahan. Anda dapat menyertakan klaim tambahan sebanyak yang diinginkan. Lihat referensi Elemen untuk mengetahui detail tentang persyaratan dan opsi untuk setiap elemen dalam contoh kebijakan ini.
<GenerateJWT name="JWT-Generate-HS256"> <DisplayName>JWT Generate HS256</DisplayName> <Type>Signed</Type> <Algorithm>HS256</Algorithm> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <SecretKey> <Value ref="private.secretkey"/> <Id>1918290</Id> </SecretKey> <ExpiresIn>1h</ExpiresIn> <Subject>monty-pythons-flying-circus</Subject> <Issuer>urn://apigee-JWT-policy-test</Issuer> <Audience>fans</Audience> <Id/> <AdditionalClaims> <Claim name="show">And now for something completely different.</Claim> </AdditionalClaims> <OutputVariable>jwt-variable</OutputVariable> </GenerateJWT>
JWT yang dihasilkan akan memiliki header ini ...
{ "typ" : "JWT", "alg" : "HS256", "kid" : "1918290" }
... dan akan memiliki payload dengan isi seperti ini:
{ "sub" : "monty-pythons-flying-circus", "iss" : "urn://apigee-JWT-policy-test", "aud" : "fans", "iat" : 1506553019, "exp" : 1506556619, "jti" : "BD1FF263-3D25-4593-A685-5EC1326E1F37", "show": "And now for something completely different." }
Nilai klaim iat, exp, dan jti akan bervariasi.
Algoritma RS256
Kebijakan contoh ini menghasilkan JWT baru dan menandatanganinya menggunakan algoritma RS256. Pembuatan tanda tangan RS256 bergantung pada kunci pribadi RSA, yang harus disediakan dalam bentuk berenkode PEM, dan yang mungkin dienkripsi sandi. Lihat video di atas untuk mengetahui contoh lengkapnya, termasuk cara mengajukan permintaan ke kebijakan.
Saat tindakan kebijakan ini dipicu, Apigee akan mengenkode dan menandatangani JWT secara digital, termasuk klaim tersebut. Untuk mempelajari bagian-bagian JWT dan cara JWT dienkripsi dan ditandatangani, lihat RFC7519.
<GenerateJWT name="JWT-Generate-RS256"> <Type>Signed</Type> <Algorithm>RS256</Algorithm> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <PrivateKey> <Value ref="private.privatekey"/> <Password ref="private.privatekey-password"/> <Id ref="private.privatekey-id"/> </PrivateKey> <Subject>apigee-seattle-hatrack-montage</Subject> <Issuer>urn://apigee-JWT-policy-test</Issuer> <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience> <ExpiresIn>60m</ExpiresIn> <Id/> <AdditionalClaims> <Claim name="show">And now for something completely different.</Claim> </AdditionalClaims> <OutputVariable>jwt-variable</OutputVariable> </GenerateJWT>
Contoh di atas menggunakan elemen <Algorithm>
sehingga menghasilkan JWT yang ditandatangani. Elemen <PrivateKey>
menentukan kunci kriptografis yang digunakan
untuk menandatangani JWT. Ada juga
elemen penting lainnya. Mana yang Anda gunakan bergantung pada algoritma yang ditentukan oleh
nilai <Algorithm>
, seperti yang dijelaskan di bagian berikutnya.
Menetapkan elemen kunci untuk JWT yang ditandatangani
Gunakan persis salah satu elemen berikut untuk menentukan kunci yang digunakan untuk menghasilkan JWT yang ditandatangani:
Elemen yang Anda gunakan bergantung pada algoritma yang dipilih, seperti yang ditunjukkan dalam tabel berikut:
Algoritma | Elemen utama |
---|---|
HS{256/384/512}* | <SecretKey> <Value ref="private.secretkey"/> <Id ref="secretkey-id">key-1918290</Id> </SecretKey> |
RS/PS/ES{256/384/512}* | <PrivateKey> <Value ref="private.privatekey"/> <Password ref="private.privatekey-password"/> <Id ref="privatekey-id">key-1918290</Id> </PrivateKey> |
Pada contoh di atas, elemen <Password>
dan <Id>
bersifat opsional.
Untuk mengetahui persyaratan kunci selengkapnya, lihat Tentang algoritma enkripsi tanda tangan.
Membuat JWT terenkripsi
Bagian ini menjelaskan cara menghasilkan JWT terenkripsi. Untuk JWT terenkripsi,
gunakan elemen <Algorithms>
guna menentukan algoritma yang digunakan untuk menandatangani kunci dan konten.
Contoh untuk JWT terenkripsi
Contoh berikut menunjukkan cara membuat JWT terenkripsi.
Contoh ini menggunakan elemen <Algorithms>
sehingga menghasilkan JWT terenkripsi.
RSA-OAEP-256
Dalam contoh di bawah ini:
- Kunci tersebut dienkripsi dengan algoritma RSA-OAEP-256.
- Konten dienkripsi dengan algoritma A128GCM.
Elemen <PublicKey>
menentukan kunci yang digunakan untuk enkripsi kunci.
<GenerateJWT name="gjwt-1"> <Type>Encrypted</Type> <Algorithms> <Key>RSA-OAEP-256</Key> <Content>A128GCM</Content> </Algorithms> <PublicKey> <Value ref="rsa_publickey"/> </PublicKey> <Subject>subject@example.com</Subject> <Issuer>urn://apigee</Issuer> <ExpiresIn>1h</ExpiresIn> <AdditionalHeaders> <Claim name="moniker">Harvey</Claim> </AdditionalHeaders> <OutputVariable>output_var</OutputVariable> </GenerateJWT>
A128KW
Dalam contoh di bawah ini:
- Kunci tersebut dienkripsi dengan algoritma A128KW.
- Konten dienkripsi dengan algoritma A128GCM.
Elemen <SecretKey>
menentukan kunci yang digunakan untuk enkripsi kunci.
<GenerateJWT name='gjwt-2'> <Algorithms> <Key>A128KW</Key> <Content>A128GCM</Content> </Algorithms> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <SecretKey> <Value ref='private.secretkey'/> </SecretKey> <Subject>subject@example.com</Subject> <Issuer>urn://apigee</Issuer> <ExpiresIn>1h</ExpiresIn> <OutputVariable>output_var</OutputVariable> </GenerateJWT>
Menetapkan elemen kunci untuk JWT terenkripsi
Gunakan hanya salah satu elemen berikut untuk menentukan kunci enkripsi bagi GenerateJWT, saat Anda ingin membuat JWT terenkripsi:
Elemen yang Anda gunakan bergantung pada algoritma enkripsi kunci yang dipilih, seperti yang ditunjukkan dalam tabel berikut:
Algoritma enkripsi kunci | Elemen utama |
---|---|
RSA-OAEP-256 | <PublicKey> <Value ref="rsa_publickey"/> </PublicKey> Catatan: Kunci harus di-resolve ke kunci publik RSA. |
|
<PublicKey> <Value ref="ec_publickey"/> </PublicKey> Catatan: Kunci harus di-resolve menjadi kunci publik kurva eliptis. |
|
<SecretKey> <Id>optional key identifier here</Id> <Value ref="private.secretkey"/> </SecretKey> |
|
<PasswordKey> <Id>optional key identifier here</Id> <Value ref="private.passwordkey"/> <SaltLength> <PBKDF2Iterations> </PasswordKey> |
{i>dir<i} | <DirectKey> <Id>optional key identifier here</Id> <Value encoding="base16|hex|base64|base64url" ref="private.directkey"/> </DirectKey> |
Untuk mengetahui persyaratan kunci selengkapnya, lihat Tentang algoritma enkripsi tanda tangan.
Referensi elemen untuk Membuat JWT
Referensi kebijakan menjelaskan elemen dan atribut kebijakan Generate JWT.
Catatan: Konfigurasi akan sedikit berbeda, bergantung pada algoritma enkripsi yang Anda gunakan. Lihat Contoh JWT yang ditandatangani atau Contoh JWT terenkripsi untuk mengetahui contoh yang menunjukkan konfigurasi untuk kasus penggunaan tertentu.
Atribut yang berlaku untuk elemen level atas
<GenerateJWT name="JWT" 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 Anda gunakan dalam nama dibatasi untuk:
A-Z0-9._\-$ % . Namun, UI Apigee menerapkan pembatasan tambahan, misalnya penghapusan otomatis karakter yang bukan alfanumerik.
Atau, gunakan elemen |
T/A | Diperlukan |
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 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 Apigee dengan nama natural-language yang berbeda.
Default | Jika Anda menghapus elemen ini, nilai atribut nama kebijakan akan digunakan. |
Kehadiran | Opsional |
Type | String |
<Algorithm>
<Algorithm>algorithm-here</Algorithm>
Menentukan algoritma kriptografi yang digunakan untuk menandatangani token. Gunakan elemen <Algorithm>
untuk menghasilkan JWT yang ditandatangani.
Default | T/A |
Kehadiran | Opsional. Salah satu dari <Algorithm>
atau <Algorithms> harus ada. |
Type | String |
Nilai yang valid | HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 |
<Algorithms>
<Algorithms> <Key>key-algorithm</Key> <Content>content-algorithm</Content> </Algorithm>
Menentukan algoritma kriptografi untuk enkripsi kunci dan konten. Gunakan elemen
<Algorithms>
untuk menghasilkan JWT terenkripsi.
Default | T/A |
Opsional. Salah satu dari <Algorithm>
atau <Algorithms> harus ada. |
Diperlukan |
Type | String |
Elemen turunan dari <Algorithms>
Tabel berikut memberikan deskripsi tingkat tinggi dari elemen turunan <Algorithms>
:
Elemen Turunan | Wajib? | Deskripsi |
---|---|---|
<Key> |
Diperlukan | Menentukan algoritma enkripsi untuk kunci. |
<Content> |
Diperlukan | Menentukan algoritma enkripsi untuk konten. |
Algoritma enkripsi utama
Tabel berikut ini mencantumkan algoritma yang tersedia untuk enkripsi kunci.
Nilai <Key> (algoritma enkripsi kunci) |
Elemen kunci wajib diisi |
---|---|
{i>dir<i} | <DirectKey> |
RSA-OAEP-256 | <PublicKey> (yang harus di-resolve ke kunci publik RSA) |
|
<SecretKey> |
|
<PasswordKey> |
|
<PublicKey> (yang harus di-resolve menjadi kunci publik kurva eliptis) |
Lihat Membuat JWT terenkripsi untuk contoh yang
algoritma enkripsi kuncinya adalah RSA-OAEP-256
, jadi Anda menggunakan
elemen <PublicKey>
dengan nilai
yang me-resolve ke kunci Publik RSA.
Algoritma enkripsi konten
Algoritma berikut (simetris, berbasis AES) tersedia untuk enkripsi konten:
- A128CBC-HS256
- A192CBC-HS384
- A256CBC-HS512
- A128GCM
- A192GCM
- A256GCM
Untuk informasi selengkapnya tentang semua algoritma ini, lihat RFC7518.
<Audience>
<Audience>audience-here</Audience> or: <Audience ref='variable_containing_audience'/>
Kebijakan ini menghasilkan JWT yang berisi klaim aud yang disetel ke nilai yang ditentukan. Klaim ini mengidentifikasi penerima yang menjadi tujuan JWT. Ini adalah salah satu klaim terdaftar yang disebutkan dalam RFC7519.
Default | T/A |
Kehadiran | Opsional |
Type | Array (daftar nilai yang dipisahkan koma) |
Nilai yang valid | Apa pun yang mengidentifikasi audiens. |
<Klaim Tambahan/Klaim>
<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'/>
Memungkinkan Anda menentukan pasangan nama/nilai klaim tambahan dalam payload JWT. Anda dapat menentukan klaim secara eksplisit sebagai string, angka, boolean, peta, atau array. Peta hanyalah kumpulan pasangan nama/nilai.
Default | T/A |
Kehadiran | Opsional |
Nilai yang valid | Nilai apa pun yang ingin Anda gunakan untuk klaim tambahan. Anda dapat menentukan klaim secara eksplisit sebagai string, angka, boolean, peta, atau array. |
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 eksplisitnya 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 adalah array jenis. Default: false.
Jika Anda menyertakan elemen <Claim>
, nama klaim akan 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 dalam JWT yang dihasilkan 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 } } }
JWT yang dihasilkan mencakup semua klaim dalam objek JSON.
<AdditionalHeader/Klaim>
<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 JWT.
Default | T/A |
Kehadiran | Opsional |
Nilai yang valid | Nilai apa pun yang ingin Anda gunakan untuk klaim tambahan. Anda dapat menentukan klaim secara eksplisit sebagai string, angka, boolean, peta, atau array. |
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 eksplisitnya 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 adalah array jenis. Default: false.
<Compress>
<Compress>true</Compress>
Menentukan apakah teks dikompresi sebelum dienkripsi. Elemen ini hanya valid saat menghasilkan JWT terenkripsi.
<CriticalHeaders>
<CriticalHeaders>a,b,c</CriticalHeaders> or: <CriticalHeaders ref=’variable_containing_headers’/>
Menambahkan header penting, crit, ke header JWT. Header crit adalah array nama header yang harus diketahui dan dikenali oleh penerima JWT. Contoh:
{ "typ": "...", "alg" : "...", "crit" : [ "a", "b", "c" ], }
Sesuai dengan spesifikasi, pihak verifikasi harus memeriksa header crit dan memverifikasi bahwa setiap header tersebut dipahami. Misalnya, kebijakan VerifyJWT memeriksa header crit.
Untuk setiap item yang tercantum dalam header crit, kode akan memeriksa apakah elemen <KnownHeaders>
dalam kebijakan VerifyJWT juga mencantumkan header tersebut. Header apa pun yang ditemukan oleh kebijakan VerifyJWT dalam crit
yang tidak tercantum dalam <KnownHeaders>
akan menyebabkan kebijakan VerifyJWT gagal.
Default | T/A |
Kehadiran | Opsional |
Type | Array string yang dipisahkan koma |
Nilai yang valid | Array atau nama variabel yang berisi array. |
<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 adalah <AdditionalClaims>. UI akan diupdate untuk menyisipkan elemen yang benar di lain waktu.
<DirectKey>
<DirectKey> <Id>A12345</Id> <Value encoding="base16|hex|base64|base64url" ref="private.directkey"/> </DirectKey>
Menentukan kunci langsung untuk mengenkripsi JWT jika algoritma enkripsinya adalah dir
("enkripsi langsung").
Elemen turunan dari <DirectKey>
Tabel berikut memberikan deskripsi tingkat tinggi dari elemen turunan <DirectKey>
:
Elemen Turunan | Wajib? | Deskripsi |
---|---|---|
ID | Opsional | ID kunci |
Nilai | Diperlukan | Tentukan referensi ke variabel dengan atribut ref . Konten
variabel yang direferensikan harus berupa encoding string array byte,
yang dienkode melalui salah satu hex (base16), base64, atau base64url. |
Dengan enkripsi kunci langsung, Anda dapat langsung menyediakan serangkaian byte yang akan bertindak sebagai kunci enkripsi konten (CEK). Anda harus menentukan array byte sebagai string yang dienkode. Panjang array byte yang diperlukan bergantung pada kekuatan algoritma enkripsi konten yang dipilih. Misalnya, untuk A256CBC-HS512, Anda harus memberikan kunci tepat 512 bit, atau 64 byte.
Konten variabel private.directkey
harus berupa string yang dienkode,
melalui hex (base16), base64, atau base64url. Misalnya, berikut adalah kunci 32 byte yang dienkode dengan heksadesimal:
96 4b e1 71 15 71 5f 87 11 0e 13 52 4c ec 1e ba df 47 62 1a 9d 3b f5 ad d2 7b b2 35 e7 d6 17 11
Untuk encoding hex, spasi kosong diterima, tetapi tidak diwajibkan, dan huruf besar atau kecil diterima (B7 sama dengan b7).
Padanan berenkode base64url di atas adalah:
lkvhcRVxX4cRDhNSTOweut9HYhqdO/Wt0nuyNefWFxE
Untuk varian base64*, spasi kosong tidak diterima, dan kapitalisasinya penting. Jika Anda tidak menentukan encoding, kebijakan tersebut menganggap encoding tersebut adalah base64.
Berikut penjelasan tentang panjang kunci yang diperlukan:
Algoritma Enkripsi Konten | Persyaratan panjang kunci |
---|---|
A128CBC-HS256 | 256 bit (32 byte) |
A192CBC-HS384 | 384 (48) |
A256CBC-HS512 | 512 (64) |
A128GCM | 128 (16) |
A192GCM | 192 (24) |
A256GCM | 256 (32) |
Catatan: Kunci enkripsi konten yang disediakan melalui elemen <DirectKey>
harus memiliki panjang yang tepat untuk algoritme enkripsi konten yang ditentukan. Untuk algoritma enkripsi kunci selain dir
, kebijakan akan menghasilkan CEK acak dengan panjang yang tepat. Namun, untuk dir
, konfigurasi harus menyediakan kunci dengan ukuran yang tepat secara eksplisit.
<ExpiresIn>
<ExpiresIn>time-value-here</ExpiresIn> or: <ExpiresIn ref='time-value-here'/>
Menentukan masa aktif JWT dalam milidetik, detik, menit, jam, atau hari. Tentukan masa berlaku menggunakan elemen XML atau atribut ref, tetapi jangan keduanya.
Default | N/A |
Kehadiran | Opsional |
Type | Bilangan bulat |
Nilai yang valid |
Nilai atau referensi ke variabel flow yang berisi nilai. Satuan waktu dapat ditentukan sebagai berikut:
Misalnya, |
<ID>
<Id>explicit-jti-value-here</Id> -or- <Id ref='variable-name-here'/> -or- <Id/>
Menghasilkan JWT dengan klaim jti tertentu. Jika nilai teks dan atribut referensi 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.
Default | T/A |
Kehadiran | Opsional |
Type | String, atau referensi. |
Nilai yang valid | String atau nama variabel flow yang berisi ID. |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
Tetapkan ke false jika Anda ingin kebijakan menampilkan error saat variabel direferensikan yang ditentukan dalam kebijakan tidak dapat diselesaikan. Tetapkan ke true untuk memperlakukan variabel yang tidak dapat di-resolve sebagai string kosong (null).
Default | Salah |
Kehadiran | Opsional |
Type | Boolean |
Nilai yang valid | benar atau salah |
<Issuer>
<Issuer ref='variable-name-here'/> <Issuer>issuer-string-here</Issuer>
Kebijakan ini akan menghasilkan JWT yang berisi klaim dengan nama iss, dengan nilai yang ditetapkan ke nilai yang ditentukan. Klaim yang mengidentifikasi penerbit JWT. Ini adalah salah satu kumpulan klaim terdaftar yang disebutkan dalam RFC7519.
Default | T/A |
Kehadiran | Opsional |
Type | String, atau referensi |
Nilai yang valid | Any |
<NotBefore>
<!-- Specify an absolute time. --> <NotBefore>2017-08-14T11:00:21-07:00</NotBefore> -or- <!-- Specify a time relative to when the token is generated. --> <NotBefore>6h</NotBefore>
Menentukan waktu saat token menjadi valid. Token tidak valid hingga waktu yang ditentukan. Anda dapat menentukan nilai waktu absolut, atau waktu yang relatif terhadap waktu pembuatan token.
Default | T/A |
Kehadiran | Opsional |
Type | String |
Nilai yang valid | Lihat di bawah. |
Nilai waktu yang valid untuk elemen NotBefore untuk nilai waktu absolut
Nama | Format | Contoh |
dapat diurutkan | yyyy-MM-dd'T'HH:mm:ss.SSSZ |
2017-08-14T11:00:21.269-0700 |
RFC 1123 | EEE, dd MMM yyyy HH:mm:ss zzz |
Sen, 14 Agu 2017 11.00.21 PDT |
RFC 850 | EEEE, dd-MMM-yy HH:mm:ss zzz |
Senin, 14-Agustus-17 11:00:21 PDT |
ANCI-C | EEE MMM d HH:mm:ss yyyy |
14 Agustus 11:00:21 2017 |
Untuk nilai waktu relatif, tentukan bilangan bulat dan jangka waktu, misalnya:
- 10 dtk
- 60 mnt
- 12 j
<OutputVariable>
<OutputVariable>jwt-variable</OutputVariable>
Menentukan lokasi penempatan JWT yang dihasilkan oleh kebijakan ini. Secara default, kolom ini ditempatkan ke dalam variabel alur jwt.POLICYNAME.generated_jwt
.
Default | jwt.POLICYNAME.generated_jwt |
Kehadiran | Opsional |
Type | String (nama variabel flow) |
<PasswordKey>
<PasswordKey> <Id>abcdefg</Id> <Value ref="private.password"/> <SaltLength>8</SaltLength> <PBKDF2Iterations>10000</PBKDF2> </PasswordKey>
Menentukan kunci untuk mengenkripsi JWT jika algoritma enkripsi adalah salah satu dari berikut ini:
- PBES2-HS256+A128KW
- PBES2-HS384+A192KW
- PBES2-HS512+A256KW
Untuk setiap algoritma kunci ini, Anda harus memberikan sandi yang digunakan untuk memperoleh kunci enkripsi, melalui variabel private.password
dalam elemen <Value ref="private.password"/>
.
Elemen turunan dari <PasswordKey>
Tabel berikut memberikan deskripsi tingkat tinggi dari elemen turunan <PasswordKey>
:
Elemen Turunan | Kehadiran | Deskripsi |
---|---|---|
ID | Opsional | ID kunci |
Nilai | Diperlukan | Menentukan sandi yang digunakan untuk membuat kunci enkripsi kunci. Gunakan atribut ref
dan tentukan variabel, seperti private.password . |
SaltLength | Opsional | Panjang garam. Default: 8 byte. |
PBKDF2Iterations | Opsional | Jumlah iterasi PBKDF2: Default: 10000. |
<PrivateKey>
<PrivateKey> <Id ref="privatekey-id"/> <Value ref="private.pem-encoded-privatekey"/> <Password ref="private.privatekey-password"/> </PrivateKey>
Menentukan kunci pribadi yang akan digunakan saat membuat JWT bertanda tangan,
dan Algorithm
adalah varian RSA atau elliptic curve (EC) - salah satu dari RS256/RS384/RS512,
PS256/PS384/PS512, atau ES256/ES384/ES512.
Elemen turunan dari <PrivateKey>
Tabel berikut memberikan deskripsi elemen turunan <PrivateKey>
:
Elemen Turunan | Kehadiran | Deskripsi |
---|---|---|
ID | Opsional | ID kunci. Nilainya dapat berupa string apa pun. Anda dapat menentukan nilai sebagai nilai teks literal, atau secara tidak langsung, melalui referensi variabel, dengan atribut Kebijakan ini akan menyertakan ID kunci ini sebagai klaim |
Nilai | Diperlukan | Kunci pribadi berenkode PEM. Menentukan kunci pribadi yang digunakan untuk menandatangani payload.
Gunakan atribut Jika elemen |
Sandi | Opsional | Sandi yang harus digunakan kebijakan untuk mendekripsi kunci pribadi, jika diperlukan. Gunakan
atribut Catatan: Anda harus menentukan variabel alur. Apigee akan menolak karena konfigurasi kebijakan yang tidak valid yang sandinya ditentukan dalam teks biasa. Variabel flow
harus memiliki awalan "private". Misalnya, |
<PublicKey>
<PublicKey> <!-- specify exactly one of the following --> <Value ref="variable-containing-encoded-publickey"/> <Value>PEM encoded public key</Value> <Certificate ref="variable-containing-encoded-x509-certificate"/> <Certificate>PEM encoded X509 certificate</Certificate> <JWKS>jwks-content</JWKS> <JWKS ref="variable-containing-jwks-content"/> <JWKS uri="variable-containing-jwks-content"/> <JWKS uriRef="variable-containing-uri"/> </PublicKey>
Menentukan kunci publik yang akan digunakan saat membuat JWT terenkripsi,
dan algoritma Key
adalah varian RSA atau elliptic curve (EC) - RSA-OAEP-256,
ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, atau ECDH-ES+A256KW.
Elemen turunan dari <PublicKey>
Berikan salah satu dari Value
, Certificate
, atau JWKS
.
Jika menentukan JWKS
, Anda juga harus menentukan Id
. Tabel berikut memberikan deskripsi elemen turunan <PublicKey>
ini:
Elemen Turunan | Deskripsi |
---|---|
Nilai | Kunci publik berenkode PEM. Menentukan kunci publik yang harus digunakan kebijakan untuk mengenkripsi kunci enkripsi konten. Anda dapat menentukan kunci secara harfiah atau tidak langsung melalui referensi variabel. <PublicKey> <Value ref="public.publickey"/> </PublicKey> atau <PublicKey> <Value> -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW 2F73IyN....your key will vary....1jC0dwUD1lHV8MfUyRXmpmnNxJHACof C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx DQIDAQAB -----END PUBLIC KEY----- </Value> </PublicKey> Kunci publik yang dienkode harus menunjukkan kunci RSA jika Anda menggunakan algoritma RSA-OAEP-256, atau kunci EC dari kurva yang sesuai jika Anda menggunakan algoritma EC. |
Certificate | Sertifikat X.509 berenkode PEM, yang menggabungkan kunci publik. Apigee akan mengekstrak kunci publik dari sertifikat, lalu menggunakan kunci tersebut untuk mengenkripsi kunci enkripsi konten. Anda dapat menentukan sertifikat secara harfiah, atau tidak langsung melalui referensi variabel. <PublicKey> <Certificate ref="public.pem-encoded-certificate"/> </PublicKey> atau <PublicKey> <Certificate> -----BEGIN CERTIFICATE----- MIIDqDCCApACCQCG/xVb7Yzw3zANBgkqhkiG9w0BAQUFADCBlTELMAkGA1UEBhMC 2F73IyN....your certificate data will vary....1jC0dwUD1lHV8MfUyR VQQKDAZHb29nbGUxDzANBgNVBAsMBkFwaWdlZTEaMBgGA1UEAwwRYXBpZ2VlLmdv ... YjBaZuNUDVLGvbTSRgWG5lwm85Jar2zeCBcxFDwqyZFvVNV9SfoWF/LgVVpK54n8 rknZ17USb0ob51ckxPTENmF2DUHBzgptiw10Yw== -----END CERTIFICATE----- </Certificate> </PublicKey> Kunci publik yang dienkode harus menunjukkan kunci RSA jika Anda menggunakan algoritma RSA-OAEP-256, atau kunci EC dari kurva yang sesuai jika Anda menggunakan algoritma EC. |
JWKS | Sumber JWKS kunci publik. Daftar ini akan berupa daftar kunci dengan format yang dijelaskan dalam IETF RFC 7517 - JSON Web Key (JWK). Anda dapat menentukan JWKS dengan salah satu dari empat cara:
Dalam semua kasus, saat menentukan elemen <PublicKey> <JWKS uri="uri-that-returns-a-jwks"/> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> |
ID | String yang mewakili ID kunci. Saat runtime, Apigee mengambil kunci dari
JWKS yang memiliki kolom |
<SecretKey>
<SecretKey encoding="base16|hex|base64|base64url" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.variable-here"/> </SecretKey>
Elemen SecretKey bersifat opsional. Layanan ini menentukan kunci rahasia yang akan digunakan saat menghasilkan JWT bertanda tangan yang menggunakan algoritma simetris (HS*) atau saat menghasilkan JWT terenkripsi yang menggunakan algoritma simetris (AES) untuk enkripsi kunci.
Anak dari <SecretKey>
Tabel berikut memberikan deskripsi elemen dan atribut turunan <SecretKey>
:
Anak | Kehadiran | Deskripsi |
---|---|---|
encoding (atribut) | Opsional | Menentukan cara kunci dienkode dalam variabel yang direferensikan. Secara default, jika tidak ada
atribut <SecretKey encoding="VALUE_HERE" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.secretkey"/> </SecretKey> Pada contoh di atas, jika atribut encoding adalah |
ID (elemen) | Opsional | ID kunci. Nilainya dapat berupa string apa pun. Anda dapat menentukan nilai tersebut sebagai nilai teks literal, atau secara tidak langsung, melalui referensi variabel, dengan atribut <SecretKey> <Id ref="flow-variable-name-here"/> <Value ref="private.variable-here"/> </SecretKey> or <SecretKey> <Id>your-id-value-here</Id> <Value ref="private.variable-here"/> </SecretKey> Kebijakan ini akan menyertakan ID kunci ini sebagai klaim |
Nilai (elemen) | Diperlukan | Kunci rahasia yang dienkode. Menentukan kunci rahasia yang digunakan untuk menandatangani payload.
Gunakan atribut <SecretKey> <Id ref="flow-variable-name-here"/> <Value ref="private.my-secret-variable"/> </SecretKey> Apigee 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. |
<Subject>
<Subject>subject-string-here</Subject>atau
<Subject ref="flow_variable" />
Contoh:
<Subject ref="apigee.developer.email"/>
Kebijakan ini akan menghasilkan JWT yang berisi klaim sub, yang ditetapkan ke nilai yang ditentukan.Klaim ini mengidentifikasi atau membuat pernyataan tentang subjek JWT. Ini adalah salah satu dari serangkaian klaim standar yang disebutkan dalam IETF RFC 7519.
Default | T/A |
Kehadiran | Opsional |
Type | String |
Nilai yang valid | Nilai apa pun yang secara unik mengidentifikasi subjek atau variabel alur yang merujuk pada nilai. |
<Jenis>
<Type>type-string-here</Type>
Menjelaskan apakah kebijakan tersebut menghasilkan JWT bertanda tangan atau JWT terenkripsi. Elemen
<Type>
bersifat opsional. Anda dapat menggunakannya untuk memberi tahu pembaca tentang
konfigurasi apakah kebijakan menghasilkan JWT bertanda tangan atau terenkripsi.
- Jika elemen
<Type>
ada:- Jika
<Type>
adalahSigned
, kebijakan akan menghasilkan JWT yang ditandatangani, dan elemen<Algorithm>
harus ada. - Jika
<Type>
adalahEncrypted
, kebijakan akan menghasilkan JWT terenkripsi, dan elemen<Algorithms>
harus ada.
- Jika
- Jika elemen
<Type>
tidak ada:- Jika elemen
<Algorithm>
ada, kebijakan menganggap<Type>
sebagaiSigned
. - Jika elemen
<Algorithms>
ada, kebijakan menganggap<Type>
adalahEncrypted
.
- Jika elemen
- Jika
<Algorithm>
atau<Algorithms>
tidak ada, konfigurasi tidak valid.
Default | T/A |
Kehadiran | Opsional |
Type | String |
Nilai yang valid | Berupa Signed atau Encrypted |
Variabel alur
Kebijakan Generate JWT tidak menetapkan variabel alur.
Referensi error
Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan dan 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 dieksekusi.
Kode kesalahan | Status HTTP | Terjadi saat |
---|---|---|
steps.jwt.AlgorithmInTokenNotPresentInConfiguration |
401 |
Terjadi saat kebijakan verifikasi memiliki beberapa algoritma. |
steps.jwt.AlgorithmMismatch |
401 |
Algoritme yang ditentukan dalam kebijakan Buat tidak cocok dengan yang diharapkan dalam kebijakan Verifikasi. Algoritma yang ditentukan harus cocok. |
steps.jwt.EncryptionFailed |
401 |
Pembuatan JWT terenkripsi gagal karena alasan yang tidak spesifik |
steps.jwt.FailedToDecode |
401 |
Kebijakan tidak dapat mendekode JWT. JWT mungkin rusak. |
steps.jwt.GenerationFailed |
401 |
Kebijakan tidak dapat menghasilkan JWT. |
steps.jwt.InsufficientKeyLength |
401 |
Untuk kunci yang berukuran kurang dari 32 byte untuk algoritma HS256, kurang dari 48 byte untuk algoritma HS386, dan kurang dari 64 byte untuk algoritma HS512. |
steps.jwt.InvalidClaim |
401 |
Karena klaim atau klaim tidak cocok, atau ketidakcocokan header atau header tidak ada. |
steps.jwt.InvalidConfiguration |
401 |
Elemen <Algorithm> dan <Algorithms>
ada. |
steps.jwt.InvalidCurve |
401 |
Kurva yang ditentukan oleh kunci tidak valid untuk algoritma Kurva Eliptis. |
steps.jwt.InvalidJsonFormat |
401 |
JSON yang tidak valid ditemukan di header atau payload. |
steps.jwt.InvalidPasswordKey |
401 |
Kunci yang ditentukan tidak memenuhi persyaratan. |
steps.jwt.InvalidPrivateKey |
401 |
Kunci yang ditentukan tidak memenuhi persyaratan. |
steps.jwt.InvalidPublicKey |
401 |
Kunci yang ditentukan tidak memenuhi persyaratan. |
steps.jwt.InvalidSecretKey |
401 |
Kunci yang ditentukan tidak memenuhi persyaratan. |
steps.jwt.InvalidToken |
401 |
Error ini terjadi saat verifikasi tanda tangan JWT gagal. |
steps.jwt.JwtAudienceMismatch |
401 |
Klaim audiens gagal pada verifikasi token. |
steps.jwt.JwtIssuerMismatch |
401 |
Klaim penerbit gagal pada verifikasi token. |
steps.jwt.JwtSubjectMismatch |
401 |
Klaim subjek gagal pada verifikasi token. |
steps.jwt.KeyIdMissing |
401 |
Kebijakan Verifikasi menggunakan JWKS sebagai sumber untuk kunci publik, tetapi JWT yang ditandatangani tidak menyertakan properti kid di header. |
steps.jwt.KeyParsingFailed |
401 |
Kunci publik tidak dapat diuraikan dari informasi kunci yang diberikan. |
steps.jwt.NoAlgorithmFoundInHeader |
401 |
Terjadi saat JWT tidak berisi header algoritma. |
steps.jwt.NoMatchingPublicKey |
401 |
Kebijakan Verifikasi menggunakan JWKS sebagai sumber untuk kunci publik, tetapi kid dalam JWT yang ditandatangani tidak tercantum di JWKS. |
steps.jwt.SigningFailed |
401 |
Di GenerateJWT , untuk kunci yang kurang dari ukuran minimum untuk algoritma HS384 atau HS512 |
steps.jwt.TokenExpired |
401 |
Kebijakan ini akan mencoba memverifikasi token yang sudah habis masa berlakunya. |
steps.jwt.TokenNotYetValid |
401 |
Token belum valid. |
steps.jwt.UnhandledCriticalHeader |
401 |
Header yang ditemukan oleh kebijakan Verifikasi JWT di header crit tidak tercantum di KnownHeaders . |
steps.jwt.UnknownException |
401 |
Terjadi pengecualian yang tidak diketahui. |
steps.jwt.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 | Penyebab | Perbaikan |
---|---|---|
InvalidNameForAdditionalClaim |
Deployment akan gagal jika klaim yang digunakan dalam elemen turunan <Claim> dari elemen <AdditionalClaims> adalah salah satu nama yang terdaftar berikut: kid , iss , sub , aud , iat , exp , nbf , atau jti .
|
build |
InvalidTypeForAdditionalClaim |
Jika klaim yang digunakan dalam elemen turunan <Claim> elemen <AdditionalClaims> bukan jenis string , number , boolean , atau map , deployment akan gagal.
|
build |
MissingNameForAdditionalClaim |
Jika nama klaim tidak ditentukan dalam elemen turunan <Claim> dari elemen <AdditionalClaims> , deployment akan gagal.
|
build |
InvalidNameForAdditionalHeader |
Error ini terjadi jika nama klaim yang digunakan dalam elemen turunan <Claim> dari elemen <AdditionalClaims> adalah alg atau typ .
|
build |
InvalidTypeForAdditionalHeader |
Jika jenis klaim yang digunakan dalam elemen turunan <Claim> dari elemen <AdditionalClaims> bukan jenis string , number , boolean , atau map , deployment akan gagal.
|
build |
InvalidValueOfArrayAttribute |
Error ini terjadi jika nilai atribut array dalam elemen turunan <Claim> dari elemen <AdditionalClaims> tidak ditetapkan ke true atau false .
|
build |
InvalidConfigurationForActionAndAlgorithm |
Jika elemen <PrivateKey> digunakan dengan algoritma Keluarga HS atau elemen <SecretKey> digunakan dengan algoritma Keluarga RSA, deployment akan gagal.
|
build |
InvalidValueForElement |
Jika nilai yang ditentukan dalam elemen <Algorithm> bukan nilai yang didukung, deployment akan gagal.
|
build |
MissingConfigurationElement |
Error ini akan terjadi jika elemen <PrivateKey> tidak digunakan dengan
algoritma kelompok RSA atau elemen <SecretKey> tidak digunakan dengan
algoritma Keluarga HS.
|
build |
InvalidKeyConfiguration |
Jika elemen turunan <Value> tidak ditetapkan dalam elemen <PrivateKey> atau <SecretKey> , deployment akan gagal.
|
build |
EmptyElementForKeyConfiguration |
Jika atribut referensi elemen turunan <Value> dari elemen <PrivateKey> atau <SecretKey> kosong atau tidak ditentukan, deployment akan gagal.
|
build |
InvalidVariableNameForSecret |
Error ini terjadi jika nama variabel flow yang ditentukan dalam atribut ref elemen
turunan <Value> dari elemen <PrivateKey>
atau <SecretKey> tidak berisi awalan pribadi (private.) .
|
build |
InvalidSecretInConfig |
Error ini terjadi jika elemen turunan <Value> dari elemen <PrivateKey> atau <SecretKey> tidak berisi awalan pribadi (private.) .
|
build |
InvalidTimeFormat |
Jika nilai yang ditentukan dalam elemen <NotBefore> tidak menggunakan format yang didukung, deployment akan gagal.
|
build |
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 kesalahannya, seperti yang tercantum dalam tabel Error runtime di atas. Nama kesalahan adalah bagian terakhir dari kode kesalahan. | fault.name Matches "InvalidToken" |
JWT.failed |
Semua kebijakan JWT menetapkan variabel yang sama jika terjadi kegagalan. | JWT.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="JWT Policy Errors"> <Step> <Name>JavaScript-1</Name> <Condition>(fault.name Matches "InvalidToken")</Condition> </Step> <Condition>JWT.failed=true</Condition> </FaultRule> </FaultRules>