Ringkasan kebijakan JWS dan JWT

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat Dokumentasi Apigee Edge.

Topik ini memberikan informasi umum tentang JWT (Token Web JSON) dan JWS (Tanda Tangan Web JSON) dan kebijakan JWS/JWT Apigee yang mungkin menarik bagi developer proxy Apigee.

Pengantar

JWS dan JWT umumnya digunakan untuk berbagi klaim atau pernyataan antara menggunakan berbagai aplikasi obrolan. Kebijakan JWS/JWT memungkinkan proxy Apigee API untuk:

Dalam dua kasus terakhir, kebijakan ini juga menetapkan variabel flow. Hal ini memungkinkan kebijakan berikutnya dalam alur Apigee untuk memeriksa klaim di JWT atau JWS, dan membuat keputusan berdasarkan klaim tersebut, atau menyebarkan informasi tersebut ke layanan backend.

Saat menggunakan kebijakan VerifyJWS atau VerifyJWT, JWS/JWT yang tidak valid akan ditolak dan akan menyebabkan error . Demikian pula, saat menggunakan kebijakan DecodeJWS atau DecodeJWT, format JWS/JWT yang salah akan menyebabkan error .

Video

Tonton video singkat untuk pengenalan singkat tentang JWT. Meskipun video ini khusus untuk menghasilkan JWT, banyak konsep yang sama untuk JWS.

Video singkat untuk mempelajari lebih lanjut struktur JWT.

Kasus penggunaan

Anda dapat menggunakan kebijakan JWS/JWT untuk:

  • Buat JWS/JWT baru di sisi endpoint proxy atau target proxy Apigee. Sebagai misalnya, Anda dapat membuat alur permintaan proxy yang menghasilkan JWS/JWT dan mengembalikannya ke klien. Atau, Anda dapat mendesain {i>proxy<i} sehingga menghasilkan JWS/JWT pada alur permintaan target, dan melampirkannya ke permintaan yang dikirim ke target. JWS/JWT dan klaimnya kemudian tersedia untuk mengaktifkan layanan backend untuk menerapkan pemrosesan keamanan lebih lanjut.
  • Memverifikasi dan mengekstrak klaim dari JWS/JWT yang diperoleh dari permintaan klien masuk, dari target respons layanan, dari respons kebijakan Info Layanan, atau dari sumber lain. Untuk JWS/JWT, Apigee akan menggunakan salah satu algoritma RSA, ECDSA, atau HMAC untuk memverifikasi tanda tangan, apakah JWS/JWT dibuat oleh Apigee atau pihak ketiga. Untuk JWT terenkripsi, Apigee akan mendekripsi JWT, menggunakan salah satu algoritma enkripsi JWA yang didukung (lihat IETF RFC 7518).
  • Mendekode JWS/JWT. Decoding paling berguna bila digunakan bersama dengan Verifikasi JWS/JWT , jika nilai klaim (JWT) atau header (JWS/JWT) dalam JWS/JWT harus diketahui sebelum memverifikasi JWS/JWT yang ditandatangani atau mendekripsi JWT yang dienkripsi.

Bagian dari JWS/JWT

JWS/JWT bertanda tangan mengenkode informasi dalam tiga bagian yang dipisahkan oleh titik:

Header.Payload.Signature
  • Kebijakan Buat JWS/JWT membuat ketiga bagian tersebut.
  • Kebijakan Verifikasi JWS/JWT memeriksa ketiga bagian tersebut.
  • Kebijakan DecodeJWS hanya memeriksa header. Kebijakan DecodeJWT hanya memeriksa header dan payload.

JWS juga mendukung bentuk terpisah yang menghilangkan payload dari JWS:

Header..Signature

Dengan JWS yang terpisah, payload akan dikirim secara terpisah dari JWS. Anda menggunakan Elemen <DetachedContent> kebijakan Verifikasi JWS untuk menentukan payload JWS mentah dan tidak dienkode. Verifikasi kebijakan JWS kemudian memverifikasi JWS menggunakan header dan tanda tangan di JWS serta payload yang ditentukan oleh elemen <DetachedContent>.

JWT terenkripsi mengenkode informasi dalam lima bagian yang dipisahkan oleh titik:

Header.Key.InitializationVector.Payload.AuthenticationTag

Kebijakan GenerateJWT dan VerifyJWT akan membuat atau memeriksa semua bagian tersebut. DecodeJWT hanya dapat memeriksa header yang tidak dienkripsi.

Untuk mempelajari lebih lanjut tentang token dan cara mengenkode, serta ditandatangani atau dienkripsi, lihat standar dokumen:

Perbedaan antara JWS dan JWT

Anda dapat menggunakan JWT atau JWS untuk berbagi klaim atau pernyataan di antara aplikasi yang terhubung. Perbedaan utama antara keduanya adalah representasi payload:

  • JWT
    • Payload selalu berupa objek JSON.
    • Payload selalu melekat ke JWT.
    • Header typ token selalu ditetapkan ke JWT.
    • Payload mungkin ditandatangani atau dienkripsi.
  • JWS
    • Payload dapat direpresentasikan oleh format apa pun, seperti objek JSON, stream byte, stream octet, dan lain-lain.
    • Payload tidak harus dipasang ke JWS.
    • {i>Header<i} dan {i>payload<i} selalu ditandatangani. JWS tidak mendukung enkripsi.

Karena format JWT selalu menggunakan objek JSON untuk mewakili payload, Apigee Kebijakan GenerateJWT dan VerifyJWT memiliki dukungan bawaan untuk menangani Klaim Terdaftar umum Nama, seperti aud, iss, sub, dan lainnya. Artinya, Anda dapat menggunakan elemen kebijakan GenerateJWT untuk menetapkan klaim ini di {i>payload<i}, dan elemen kebijakan VerifyJWT untuk memverifikasi nilainya. Lihat Klaim Terdaftar Nama dari spesifikasi JWT untuk mengetahui informasi selengkapnya.

Bersama dengan mendukung Nama Klaim Terdaftar tertentu, kebijakan GenerateJWT secara langsung mendukung penambahan klaim dengan nama arbitrer ke payload atau header JWT. Setiap klaim pasangan nama/nilai sederhana, dengan nilai dapat berjenis number, boolean, string, map, atau array.

Saat menggunakan GenerateJWS, Anda menyediakan variabel konteks yang mewakili payload. Karena seorang JWS dapat menggunakan representasi data apa pun untuk payload, tidak ada konsep "klaim payload" inci JWS, dan kebijakan GenerateJWS tidak mendukung penambahan klaim dengan nama acak ke payload. Kebijakan GenerateJWS dapat digunakan untuk menambahkan klaim dengan nama acak untuk header JWS. Selain itu, kebijakan JWS mendukung {i>payload<i} terpisah, di mana JWS menghilangkan payload. Payload yang terpisah memungkinkan Anda mengirim JWS dan payload secara terpisah. Menggunakan payload yang terpisah dapat lebih menghemat ruang terutama untuk payload besar, dan diperlukan oleh beberapa standar keamanan.

Penandatanganan versus Enkripsi

Apigee dapat membuat JWT yang ditandatangani atau dienkripsi. Pilih JWT yang ditandatangani ketika payload tidak perlu rahasia, tetapi penting untuk memberikan jaminan integritas dan non-penyangkalan kepada pembaca. JWT yang ditandatangani meyakinkan pembaca bahwa {i>payload<i} tidak berubah sejak JWT ditandatangani dan bahwa JWT ditandatangani oleh pemegang kunci pribadi. Pilih JWT terenkripsi saat payload seharusnya rahasia. JWT terenkripsi menyediakan kerahasiaan untuk {i>payload<i}, karena hanya kunci yang tepat dapat membongkar enkripsinya.

Anda dapat menggunakan JWT yang dienkripsi dan ditandai secara bersamaan, terutama ketika JWT menggunakan algoritma kriptografi asimetris (RSA, ECDSA). Dalam hal ini, identitas pembuat JWT tersebut tidak dapat ditentukan, karena kunci enkripsinya bersifat publik. Untuk mengatasi masalah tersebut, gabungkan penandatanganan dengan enkripsi. Pola umumnya adalah sebagai berikut:

  • Tanda tangani payload untuk menghasilkan JWS atau JWT yang ditandatangani.
  • Enkripsi hasil bertanda tangan untuk menghasilkan JWT terenkripsi.

Menyematkan {i>payload<i} bertanda tangan dalam JWT terenkripsi menggunakan pendekatan ini memberikan anti penyangkalan dan jaminan kerahasiaan. Kebijakan Apigee dapat menghasilkan dan mendekode & memverifikasi kombinasi tersebut.

Algoritma tanda tangan

Untuk JWT yang ditandatangani, kebijakan Verifikasi JWS/JWT dan Pembuatan JWS/JWT mendukung RSA, Algoritma RSASSA-PSS, ECDSA, dan HMAC, menggunakan checksum SHA2 dengan kekuatan bit 256, 384, atau 512. Kebijakan DecodeJWS dan DecodeJWT berfungsi terlepas dari algoritma yang digunakan untuk menandatangani JWS/JWT.

Algoritma HMAC

Algoritma HMAC bergantung pada rahasia bersama, yang dikenal sebagai kunci rahasia, untuk membuat tanda tangan (juga dikenal sebagai penandatanganan JWS/JWT) dan untuk memverifikasi tanda tangan.

Panjang minimum kunci rahasia bergantung pada kekuatan bit algoritma:

  • HS256: Panjang kunci minimum 32 byte
  • HS384: Panjang kunci minimum 48 byte
  • HS512: panjang kunci minimum 64 byte

Algoritma RSA

Algoritma RSA menggunakan pasangan kunci publik/pribadi untuk tanda tangan kriptografis tersebut. JWA menggunakan monikers RS256, RS384, dan RS512 untuk merepresentasikan pilihan-pilihan ini. Dengan RSA tanda tangan, pihak yang menandatangani menggunakan kunci pribadi RSA untuk menandatangani JWS/JWT, menggunakan kunci publik RSA yang cocok untuk memverifikasi tanda tangan di JWS/JWT. Tidak ada persyaratan ukuran pada kunci.

Algoritma RSASSA-PSS

Algoritma RSASSA-PSS adalah pembaruan algoritma RSA, dan menggunakan {i>monikers PS256<i}, PS384, dan PS512. Seperti varian RS*, RSASSA-PSS menggunakan pasangan kunci publik/pribadi RSA untuk tanda tangan kriptografis tersebut. Format, mekanisme, dan batas ukuran kunci sama dengan untuk algoritma RS*.

Algoritma ECDSA

Sekumpulan algoritma Elliptic Curve Digital Signature Algorithm (ECDSA) adalah algoritma kriptografi kurva eliptik dengan kurva P-256, P-384, atau P-521. Saat Anda menggunakan ECDSA algoritma akan menentukan jenis kunci publik dan pribadi yang harus Anda tentukan:

Algoritme Lengkung Persyaratan kunci
ES256 P-256 Kunci yang dihasilkan dari kurva P-256 (juga dikenal sebagai secp256r1 atau prime256v1)
ES384 P-384 Kunci yang dihasilkan dari kurva P-384 (juga dikenal sebagai secp384r1)
ES512 P-521 Kunci yang dihasilkan dari kurva P-521 (juga dikenal sebagai secp521r1)

Algoritma enkripsi

Saat menggunakan GenerateJWT dan VerifyJWT untuk menangani JWT terenkripsi, kebijakan mendukung tindakan ini algoritma:

  • dir
  • RSA-OAEP-256
  • A128KW, A192KW, A256KW
  • A128GCMKW, A192GCMKW, A256GCMKW
  • PBES2-HS256+A128KW, PBES2-HS384+A192KW, PBES2-HS512+A256KW
  • ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW

Kunci dan Representasi Kunci

Standar JOSE, yang mencakup JWS, JWT yang ditandatangani dan dienkripsi, dan banyak lagi, menjelaskan cara kunci kriptografis untuk menandatangani atau mengenkripsi informasi. Elemen dasar untuk setiap operasi kriptografis menyertakan algoritma, dan kuncinya. Algoritma yang berbeda memerlukan jenis kunci yang berbeda, dan dalam beberapa kasus, ukuran kunci berbeda.

Algoritma simetris, seperti keluarga HS* untuk penandatanganan, atau algoritma A128KW untuk enkripsi, memerlukan kunci simetris atau bersama: kunci yang sama digunakan untuk menandatangani dan memverifikasi, atau kunci yang sama digunakan untuk mengenkripsi dan mendekripsi. Algoritma Asimetris{i>,<i} seperti algoritma RS*, PS*, dan ES* untuk penandatanganan, atau algoritma ECDH* untuk mengenkripsi, gunakan pasangan kunci - ada kunci publik dan kunci pribadi, dan keduanya cocok. Dalam penandatanganan, penanda tangan menggunakan kunci pribadi untuk menandatangani, dan pihak mana pun dapat menggunakan kunci publik untuk memverifikasi tanda tangan. Dalam mengenkripsi, pengenkripsi menggunakan kunci publik untuk mengenkripsi, dan pendekripsi menggunakan kunci pribadi untuk mendekripsinya. Kunci publik, sebagai namanya dapat dibagikan secara publik, dan tidak perlu dirahasiakan.

Ada berbagai cara untuk melakukan serialisasi kunci kriptografis ke dalam format teks. Kebijakan Apigee menerima kunci yang diserialisasi dalam berbagai bentuk: bentuk yang dienkode PEM, bentuk JWKS, atau untuk kunci bersama, Berenkode UTF-8 atau berenkode base64.

Format PEM

Untuk kunci publik atau pribadi, encoding PEM umumnya digunakan, yang didefinisikan dalam IETF RFC 7468. Berikut contohnya kunci pribadi yang direpresentasikan dalam format PEM: 

-----BEGIN PRIVATE KEY-----
MIGEAgEAMBAGByqGSM49AgEGBSuBBAAKBG0wawIBAQQgVcB/UNPxalR9zDYAjQIf
jojUDiQuGnSJrFEEzZPT/92hRANCAASc7UJtgnF/abqWM60T3XNJEzBv5ez9TdwK
H0M6xpM2q+53wmsN/eYLdgtjgBd3DBmHtPilCkiFICXyaA8z9LkJ
-----END PRIVATE KEY-----

Ada format PEM yang serupa untuk kunci publik, atau kunci pribadi terenkripsi.

Format JWKS

Kunci Web JSON (JWK) adalah struktur data JSON yang mewakili satu kunci kriptografis. J JSON Web Key Set (JWKS) adalah struktur JSON yang mewakili serangkaian JWK. JWK dan JWKS adalah yang dijelaskan dalam RFC7517. Lihat Contoh JWKS di Lampiran A. Contoh Kunci Web JSON Kumpulan.

JWKS dimaksudkan untuk memungkinkan pihak mana pun untuk mewakili serangkaian kunci dalam format standar. Kunci kasus penggunaan adalah berbagi kunci publik dengan cara standar, melalui endpoint HTTP yang mengirimkan data dalam format JWKS. Ketika perusahaan atau sistem yang menghasilkan JWS atau JWT yang ditandatangani, seperti Penyedia Identitas, menerbitkan kunci publik mereka, sistem atau aplikasi apa pun yang dapat membaca kunci publik, dapat memverifikasi tanda tangan yang dibuat oleh pihak yang menandatangani. Sebaliknya, setiap sistem atau yang ingin mengenkripsi data yang seharusnya hanya dibaca oleh pihak atau perusahaan tertentu, dapat mengambil kunci publik milik pihak atau perusahaan itu, dan membuat JWT.

RFC7517 mendeskripsikan JWKS elemen kunci untuk setiap jenis kunci, seperti RSA atau EC. Elemen-elemen ini harus selalu ada:

  • kty - Jenis kunci, seperti RSA atau EC.
  • kid - ID kunci. Nilai ini dapat berupa nilai string unik arbitrer; di sana seharusnya tidak ada duplikasi dalam satu kumpulan kunci. Jika JWT masuk memakai ID kunci yang ada di kumpulan JWKS, kebijakan VerifyJWS atau VerifyJWT akan menggunakan untuk memverifikasi tanda tangan JWS/JWT.

Berikut adalah contoh elemen opsional dan nilainya:

  • alg: Algoritma kunci. Ini harus sesuai dengan algoritma penandatanganan dalam JWS/JWT.
  • use: Tujuan penggunaan kunci. Nilai standar adalah "sig" untuk penandatanganan dan verifikasi, atau "enc" untuk enkripsi dan dekripsi.

JWKS berikut (awalnya diambil dari https://www.googleapis.com/oauth2/v3/certs, tetapi sudah tidak berlaku sekarang) mencakup elemen dan nilai yang diperlukan, dan akan dapat digunakan oleh Apigee:

{
     "keys":[
        {
           "kty":"RSA",
           "alg":"RS256",
           "use":"sig",
           "kid":"ca04df587b5a7cead80abee9ea8dcf7586a78e01",
           "n":"iXn-WmrwLLBa-QDiToBozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt7-V7KDjCq0_Nkd-X9rMRV5LKgCa0_F8YgI30QS3bUm9orFryrdOc65PUIVFVxIwMZuGDY1hj6HEJVWIr0CZdcgNIll06BasclckkUK4O-Eh7MaQrqb646ghFlG3zlgk9b2duHbDOq3s39ICPinRQWC6NqTYfqg7E8GN_NLY9srUCc_MswuUfMJ2cKT6edrhLuIwIj_74YGkpOwilr2VswKsvJ7dcoiJxheKYvKDKtZFkbKrWETTJSGX2Xeh0DFB0lqbKLVvqkM2lFU2Qx1OgtTnrw",
           "e":"AQAB"
        },
        {
            "kty":"EC",
            "alg":"ES256",
            "use":"enc",
            "kid":"k05TUSt7-V7KDjCq0_N"
            "crv":"P-256",
            "x":"Xej56MungXuFZwmk_xccvsMpCtXmqhvEEMCmHyAmKF0",
            "y":"Bozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt",
        }
     ]
  }

Menentukan kunci ke kebijakan JWS dan JWT

Baik Anda membuat atau memverifikasi JWS atau JWT, Anda harus menyediakan kunci untuk digunakan di dalam terkait operasi kriptografi.

Saat membuat JWT yang ditandatangani, Anda perlu menyediakan kunci yang dapat menghasilkan tanda tangan.

  • Dalam kasus algoritma penandatanganan RS*, PS*, atau ES*, yang semuanya menggunakan kunci asimetris, Anda harus menyediakan kunci pribadi untuk menghasilkan tanda tangan.
  • Dalam kasus algoritma HS*, Anda perlu memberikan kunci simetris yang akan digunakan saat membuat tanda tangan.

Saat memverifikasi JWS/JWT yang ditandatangani, Anda harus memberikan kunci yang dapat memverifikasi tanda tangan.

  • Dalam kasus algoritma penandatanganan RS*, PS*, atau ES*, Anda harus menyediakan kunci publik yang terkait dengan kunci pribadi yang awalnya digunakan untuk menandatangani token tersebut.
  • Dalam kasus algoritma HS*, Anda perlu menyediakan kunci simetris yang sama dengan yang digunakan untuk menandatangani JWS atau JWT.

Anda memiliki dua opsi untuk yang menyediakan kunci ke kebijakan JWS dan JWT:

  • Berikan nilai kunci secara langsung (biasanya melalui variabel konteks), atau
  • Berikan kunci secara tidak langsung, melalui kid dan JWKS. Anda dapat menentukan JWKS secara langsung, atau tidak langsung melalui URL http tempat Apigee dapat mengambil JWKS.

Opsi URL JWKS biasanya hanya digunakan sebagai sumber kunci publik yang dapat digunakan dengan algoritma asimetris, karena URL JWKS biasanya bersifat publik.

Contoh berikut mengilustrasikan cara menyediakan kunci secara langsung dalam berbagai skenario.

  • Buat JWT yang ditandatangani dengan algoritma HS256. Diperlukan kunci dalam hal ini adalah kunci simetris. Kebijakan ini menyediakan variabel konteks yang berisi kunci rahasia berenkode base64url.

    <GenerateJWT name='gen-138'>
  <Algorithm>HS256</Algorithm>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <SecretKey encoding='base64url'>
    <Value ref='private.secretkey'/>
    <Id ref='variable-containing-desired-keyid'/>
  </SecretKey>
  . . .
  <OutputVariable>output_variable_name</OutputVariable>
</GenerateJWT>

  • Verifikasi JWT yang ditandatangani dengan algoritma HS256. Kunci yang diperlukan dalam kasus ini adalah kunci simetris tombol. Seperti dalam contoh di atas, kebijakan ini memberikan variabel konteks yang berisi kunci rahasia berenkode base64url.

    <VerifyJWT name='verify-138'>
  <Algorithm>HS256</Algorithm>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <SecretKey encoding='base64url'>
    <Value ref='private.secretkey'/>
  </SecretKey>
  . . .
  <OutputVariable>output_variable_name</OutputVariable>
</VerifyJWT>

  • Verifikasi JWT yang telah ditandatangani dengan algoritma PS256. Kunci yang diperlukan dalam kasus ini adalah kunci RSA publik. Kebijakan ini menyediakan variabel konteks yang berisi variabel berenkode PEM kunci publik tertentu.

    <VerifyJWT name='JWT-001'>
  <Algorithm>PS256</Algorithm>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <PublicKey>
    <Value ref='variable-containing-pem-encoded-public-key'/>
  </PublicKey>
  . . .
</VerifyJWT>

  • Buat JWT yang ditandatangani dengan algoritma PS256. Kunci yang diperlukan dalam kasus ini adalah kunci pribadi Kunci RSA. Kebijakan ini menyediakan variabel konteks yang berisi kunci pribadi berenkode PEM. 

    <GenerateJWT name='JWT-002'>
  <Algorithm>PS256</Algorithm>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <PrivateKey>
    <Value ref='private.variable-containing-pem-encoded-private-key'/>
  </PrivateKey>
   . . .
</GenerateJWT>

JWKS sebagai sumber utama saat memverifikasi JWS atau JWT yang ditandatangani

Saat sistem atau aplikasi menghasilkan JWS/JWT, biasanya sistem atau aplikasi akan memasukkan Kunci ID (klaim kid) ke dalam header JWS/JWT. Kunci tersebut memberi tahu setiap pembaca pada JWS/JWT, kunci mana yang diperlukan untuk memverifikasi tanda tangan pada JWS/JWT yang ditandatangani, JWT yang terenkripsi.

Sebagai contoh, anggaplah penerbit menandatangani JWT dengan kunci pribadi. "ID Kunci" mengidentifikasi kunci publik yang cocok, yang harus digunakan untuk memverifikasi JWT. Daftar kunci publik biasanya tersedia di beberapa endpoint yang dikenal luas, seperti Endpoint Google Identity atau endpoint Firebase Authentication. Penyedia lain akan memiliki endpoint publiknya sendiri yang memublikasikan kunci dalam format JWKS.

Saat menggunakan Apigee untuk memverifikasi JWS atau JWT yang ditandatangani dengan kunci publik yang dibagikan melalui JWKS Anda memiliki beberapa opsi:

  • Opsi 1: Dalam konfigurasi kebijakan, tentukan URI endpoint JWKS di elemen <PublicKey/JWKS>. Misalnya, untuk kebijakan VerifyJWT:

    <VerifyJWT name="JWT-Verify-RS256">
  <Algorithm>RS256</Algorithm>
  <Source>json.jwt</Source>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <PublicKey>
      <JWKS uri="https://www.googleapis.com/oauth2/v3/certs"/>
  </PublicKey>
  . . .
</VerifyJWT>

    Dalam hal ini, Apigee akan:

    1. Periksa {i>header <i}JWS/JWT untuk menemukan algoritma penandatanganan (alg), seperti RS256, dan menolak JWT masuk jika algoritma tersebut tidak sesuai dengan algoritma yang dikonfigurasi di kebijakan tersebut.
    2. Ambil daftar kunci dengan ID-nya dari endpoint JWKS yang ditentukan, atau dari cache internal jika endpoint JWKS ini pernah digunakan sebelumnya.
    3. Periksa {i>header<i} JWS/JWT untuk menemukan ID Kunci (anak). Jika JWT masuk tidak menyertakan ID kunci (anak) di header, maka pemetaan anak ke kunci verifikasi tidak mungkin dilakukan, dan Apigee akan menampilkan error.
    4. Ekstrak dari JWKS, JWK dengan ID kunci yang tercantum di header JWS/JWT. Tampilkan fault jika kunci dengan ID kunci tersebut tidak ada.
    5. Periksa apakah algoritma untuk JWK cocok dengan algoritma yang ditentukan dalam kebijakan konfigurasi Anda. Tolak verifikasi dan tampilkan kesalahan jika algoritma tidak cocok.
    6. Gunakan kunci publik tersebut untuk memverifikasi tanda tangan di JWS/JWT. Tolak verifikasi dan memberikan kesalahan jika tanda tangan tidak diverifikasi.

  • Opsi 2: Dalam konfigurasi kebijakan, tentukan variabel yang menyimpan URI endpoint JWKS di elemen <PublicKey/JWKS>.

    Misalnya, untuk kebijakan VerifyJWT:

    <VerifyJWT name="JWT-Verify-RS256">
  <Algorithm>RS256</Algorithm>
  <Source>json.jwt</Source>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <PublicKey>
    <JWKS uriRef="variable-containing-a-uri"/>
  </PublicKey>
  . . .
</VerifyJWT>

    Dalam hal ini, Apigee akan melakukan langkah yang sama seperti di atas, hanya saja Apigee akan mengambil JWKS bukan dari URI hard code, tetapi dari uri yang ditentukan dalam variabel yang direferensikan oleh atribut uriRef. Penyimpanan dalam cache masih berlaku.

  • Opsi 3: Dalam konfigurasi kebijakan, tentukan variabel yang menyimpan data JWKS hard code dalam elemen <PublicKey/JWKS>.

    Misalnya, untuk kebijakan VerifyJWT:

    <VerifyJWT name="JWT-Verify-RS256">
  <Algorithm>RS256</Algorithm>
  <Source>json.jwt</Source>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <PublicKey>
    <JWKS ref="variable-that-holds-a-jwks"/>
  </PublicKey>
  . . .
</VerifyJWT>

    Dalam hal ini, Apigee akan melakukan langkah yang sama seperti di atas, hanya saja Apigee akan mengambil JWKS bukan dari URI, tetapi dari variabel konteks yang Anda tentukan dalam atribut ref. Biasanya Anda akan memuat variabel konteks ini dari ServiceKeterangan, KVM, atau file properti yang terkait dengan proxy.

JWKS sebagai sumber kunci saat membuat JWT terenkripsi

Saat Anda menghasilkan JWT terenkripsi melalui algoritma asimetris (RSA-OAEP-256 atau varian ECDH-*), Anda menggunakan kunci publik untuk mengenkripsi. Anda memiliki opsi untuk dengan menyediakan kunci ke kebijakan GenerateJWT

Pendekatan umumnya adalah menentukan dalam konfigurasi kebijakan, URI endpoint JWKS di Elemen <PublicKey/JWKS>. Contoh:

<GenerateJWT name="GJWT-1">
  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <PublicKey>
    <JWKS uri='https://www.example.com/.well-known/jwks.json'/>
    <Id ref='variable-containing-desired-keyid'/>
  </PublicKey>
    . . .
</GenerateJWT>

Dalam hal ini, Apigee akan:

  1. Susun payload dan header yang tidak dienkode untuk JWT berdasarkan konfigurasi kebijakan.
  2. Ambil daftar kunci dengan ID-nya dari endpoint JWKS yang ditentukan, atau dari endpoint cache jika endpoint JWKS ini pernah digunakan sebelumnya. Saat ini TTL cache adalah 5 menit.
  3. Ekstrak JWK dengan ID kunci yang tercantum dalam PublicKey/Id dari JWKS. Tampilkan fault jika kunci dengan ID kunci tersebut tidak ada.
  4. Periksa apakah algoritma untuk JWK cocok dengan algoritma yang ditentukan dalam kebijakan konfigurasi Anda. Berikan kesalahan jika algoritma tidak cocok.
  5. Buat urutan acak untuk digunakan sebagai kunci enkripsi konten.
  6. Gunakan kunci publik yang dipilih untuk mengenkripsi kunci enkripsi konten.
  7. Gunakan kunci enkripsi konten untuk mengenkripsi payload.
  8. Terakhir, kumpulkan semua bagian menjadi sebuah JWT terenkripsi yang diserialisasi.

Alternatifnya adalah dengan menggunakan atribut uriRef untuk menentukan variabel yang menyimpan URI titik akhir JWKS. Contoh:

<GenerateJWT name="GJWT-1">
  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <PublicKey>
    <JWKS uriRef='variable-containing-jwks-uri'/>
    <Id ref='variable-containing-desired-keyid'/>
  </PublicKey>
  . . .
</GenerateJWT>

Dalam hal ini, Apigee akan melakukan langkah yang sama seperti di atas, bedanya Apigee akan mengambil JWKS dari URI yang ditentukan dalam variabel yang direferensikan oleh atribut uriRef, bukannya URI hard code. Apigee akan membaca JWKS dari cache jika endpoint JWKS ini pernah digunakan sebelumnya.