Kebijakan GenerateJWT

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

Apa

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

Video

Tonton video pendek untuk mempelajari cara membuat JWT bertanda tangan.

Contoh

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

Buat JWT yang ditandatangani dengan algoritma HS256

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

Saat tindakan kebijakan ini dipicu, Edge akan mengenkode header dan payload JWT, lalu menandatangani JWT secara digital. Tonton video di atas untuk melihat contoh lengkap, termasuk cara mengajukan permintaan ke kebijakan.

Konfigurasi kebijakan di sini akan membuat JWT dengan serangkaian klaim standar seperti yang ditentukan oleh spesifikasi JWT, termasuk masa berlaku 1 jam, serta klaim tambahan. Anda dapat menyertakan klaim tambahan sebanyak yang Anda inginkan. 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>
    <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-edge-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 konten seperti ini:

{ 
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "show",
  "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.

Buat JWT yang ditandatangani dengan algoritma RS256

Contoh kebijakan ini membuat JWT baru dan menandatanganinya menggunakan algoritma RS256. Pembuatan tanda tangan RS256 bergantung pada kunci pribadi RSA, yang harus diberikan dalam bentuk yang dienkode PEM. Tonton video di atas untuk melihat contoh lengkap, termasuk cara mengajukan permintaan ke kebijakan.

Saat tindakan kebijakan ini dipicu, Edge akan mengenkode dan menandatangani JWT secara digital, termasuk klaim. Untuk mempelajari bagian-bagian JWT dan cara dienkripsi dan ditandatangani, lihat RFC7519.

<GenerateJWT name="JWT-Generate-RS256">
    <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-edge-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>

Menetapkan elemen utama

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

Referensi kebijakan menjelaskan elemen dan atribut kebijakan Buat 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 diterapkan ke elemen tingkat teratas

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

Menentukan algoritma enkripsi untuk menandatangani token.

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

Kebijakan ini menghasilkan JWT yang berisi klaim aud yang ditetapkan ke nilai yang ditentukan. 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'/>

Memungkinkan Anda menentukan pasangan nilai/nama klaim tambahan dalam payload JWT. Anda dapat menentukan klaim secara eksplisit sebagai string, angka, boolean, peta, atau array. Peta hanyalah sekumpulan pasangan nama/nilai.

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 di JWT yang dihasilkan 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 }
  }
}

JWT yang dihasilkan mencakup semua klaim dalam objek JSON.

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

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.

<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” ],
}

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

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

<ExpiresIn>

<ExpiresIn>time-value-here</ExpiresIn>

Menentukan masa berlaku JWT dalam milidetik, detik, menit, jam, atau hari.

<Id>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

Membuat JWT dengan klaim jti tertentu. Jika nilai teks dan atribut ref keduanya kosong, kebijakan akan menghasilkan jti yang berisi UUID acak. Klaim ID JWT (jti) adalah ID unik untuk JWT. Untuk mengetahui informasi selengkapnya tentang jti, lihat RFC7519.

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

<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 saat token dibuat.

Nilai waktu yang valid untuk elemen NotBefore untuk nilai waktu absolut

Untuk nilai waktu relatif, tentukan bilangan bulat dan jangka waktu, misalnya:

• 10 dtk
• 60m
• 12 j

<OutputVariable>

<OutputVariable>jwt-variable</OutputVariable>

Menentukan tempat untuk menempatkan JWT yang dihasilkan oleh kebijakan ini. Secara default, nilai ini ditempatkan ke dalam variabel alur jwt.POLICYNAME.generated_jwt.

<PrivateKey/Id>

<PrivateKey>
  <Id ref="flow-variable-name-here"/>
</PrivateKey>

or

<PrivateKey>
  <Id>your-id-value-here</Id>
</PrivateKey>

Menentukan ID kunci (kid) yang akan disertakan dalam header JWT. 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-password"/>
</PrivateKey>

Tentukan sandi yang harus digunakan kebijakan untuk mendekripsi kunci pribadi, jika perlu. Gunakan atribut ref untuk meneruskan kunci dalam flow variable. 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-here"/>
</PrivateKey>

Menentukan kunci pribadi berenkode PEM yang digunakan untuk menandatangani JWT. Gunakan atribut ref untuk meneruskan kunci dalam flow variable. 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-here"/>
</SecretKey>

or

<SecretKey>
  <Id>your-id-value-here</Id>
</SecretKey>

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

<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 algoritma adalah salah satu dari HS256/HS384/HS512. Gunakan atribut ref untuk meneruskan kunci dalam flow variable.

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.

<Subject>

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

<Subject ref="flow_variable" />

Contoh:

<Subject ref="apigee.developer.email"/>

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

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