Ringkasan kebijakan JWS dan JWT

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Baca dokumentasi Apigee Edge.

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

Pengantar

JWS dan JWT biasanya digunakan untuk berbagi klaim atau pernyataan antara aplikasi yang terhubung. Kebijakan JWS/JWT memungkinkan proxy API Apigee untuk:

Dalam dua kasus terakhir, kebijakan juga menetapkan variabel flow. Hal ini memungkinkan kebijakan berikutnya dalam alur Apigee untuk memeriksa klaim di JWT atau JWS, serta 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 menghasilkan kondisi error. Demikian pula, saat menggunakan kebijakan DecodeJWS atau DecodeJWT, JWS/JWT dengan format yang salah akan menghasilkan kondisi error.

Video

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

Apa video singkat untuk mempelajari lebih lanjut tentang struktur JWT.

Kasus penggunaan

Anda dapat menggunakan kebijakan JWS/JWT untuk:

  • Buat JWS/JWT baru di sisi proxy atau endpoint target dari proxy Apigee. Misalnya, Anda dapat membuat alur permintaan proxy yang menghasilkan JWS/JWT dan menampilkannya ke klien. Atau, Anda dapat mendesain proxy agar menghasilkan JWS/JWT pada alur permintaan target, dan melampirkannya ke permintaan yang dikirim ke target. JWS/JWT dan klaimnya nantinya akan tersedia untuk memungkinkan layanan backend menerapkan pemrosesan keamanan lebih lanjut.
  • Verifikasi dan ekstrak klaim dari JWS/JWT yang diperoleh dari permintaan klien masuk, dari respons layanan target, respons kebijakan Panggilan Layanan, atau dari sumber lainnya. Untuk JWS/JWT yang ditandatangani, Apigee akan menggunakan salah satu algoritma RSA, ECDSA, atau HMAC untuk memverifikasi tanda tangan, baik JWS/JWT dihasilkan 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 sangat berguna saat digunakan bersama dengan kebijakan 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 terenkripsi.

Bagian dari JWS/JWT

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

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

JWS juga mendukung bentuk detached yang menghilangkan payload dari JWS:

Header..Signature

Dengan JWS terpisah, payload dikirim secara terpisah dari JWS. Anda menggunakan elemen <DetachedContent> dalam kebijakan Verify JWS untuk menetapkan payload JWS mentah dan tidak dienkode. Kebijakan Verifikasi 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 token dan cara token tersebut dienkode, serta ditandatangani atau dienkripsi, lihat dokumen standar yang relevan:

Perbedaan antara JWS dan JWT

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

  • JWT
    • Payload selalu berupa objek JSON.
    • Payload selalu terpasang ke JWT.
    • Header typ token selalu ditetapkan ke JWT.
    • Payload dapat ditandatangani atau dienkripsi.
  • JWS
    • Payload dapat diwakili oleh format apa pun, seperti objek JSON, aliran byte, aliran octet, dan lainnya.
    • Payload tidak harus dipasang ke JWS.
    • Header dan payload selalu ditandatangani. JWS tidak mendukung enkripsi.

Karena format JWT selalu menggunakan objek JSON untuk mewakili payload, kebijakan Apigee GenerateJWT dan VerifyJWT telah dilengkapi dengan dukungan untuk menangani Nama Klaim Terdaftar yang umum, seperti aud, iss, sub, dan lainnya. Artinya, Anda dapat menggunakan elemen kebijakan GenerateJWT untuk menetapkan klaim ini dalam payload, dan elemen kebijakan VerifyJWT untuk memverifikasi nilainya. Lihat bagian Nama Klaim Terdaftar dalam spesifikasi JWT untuk mengetahui informasi selengkapnya.

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

Saat menggunakan GenerateJWS, Anda menyediakan variabel konteks yang mewakili payload. Karena JWS dapat menggunakan representasi data apa pun untuk payload, tidak ada konsep "klaim payload" di JWS, dan kebijakan GenerateJWS tidak mendukung penambahan klaim dengan nama arbitrer ke payload. Anda dapat menggunakan kebijakan GenerateJWS untuk menambahkan klaim dengan nama arbitrer ke header JWS. Selain itu, kebijakan JWS mendukung payload terpisah, di mana JWS menghilangkan payload. Payload yang terpisah memungkinkan Anda mengirim JWS dan payload secara terpisah. Menggunakan payload yang terpisah bisa menghemat ruang, terutama untuk payload besar, dan diwajibkan oleh beberapa standar keamanan.

Penandatanganan versus Enkripsi

Apigee dapat menghasilkan JWT yang ditandatangani atau dienkripsi. Pilih JWT yang ditandatangani jika payload tidak harus bersifat rahasia, tetapi penting untuk memberikan jaminan integritas dan anti-penyangkalan kepada pembaca. JWT yang ditandatangani meyakinkan pembaca bahwa payload tidak berubah sejak JWT ditandatangani dan bahwa JWT ditandatangani oleh pemegang kunci pribadi. Pilih JWT terenkripsi jika payload harus rahasia. JWT terenkripsi memberikan kerahasiaan untuk payload, karena hanya pemegang kunci yang sesuai yang dapat mendekripsinya.

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

  • Menandatangani payload untuk menghasilkan JWS atau JWT yang ditandatangani.
  • Enkripsi hasil yang ditandatangani untuk menghasilkan JWT terenkripsi.

Menyematkan payload bertanda dalam JWT terenkripsi menggunakan pendekatan ini memberikan jaminan kerahasiaan dan anti-penyangkalan. Kebijakan Apigee dapat menghasilkan dan mendekode & memverifikasi kombinasi tersebut.

Algoritma tanda tangan

Untuk JWT yang ditandatangani, kebijakan JWS/JWT Verification dan JWS/JWT Generation mendukung algoritma RSA, 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 mengandalkan rahasia bersama, yang dikenal sebagai kunci rahasia, untuk membuat tanda tangan (juga dikenal sebagai penandatanganan JWS/JWT) dan 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 kriptografi. Spesifikasi JWA menggunakan moniker RS256, RS384, dan RS512 untuk merepresentasikan opsi ini. Dengan tanda tangan RSA, pihak yang menandatangani menggunakan kunci pribadi RSA untuk menandatangani JWS/JWT, sedangkan pihak yang melakukan verifikasi menggunakan kunci publik RSA yang cocok untuk memverifikasi tanda tangan tersebut di JWS/JWT. Tidak ada persyaratan ukuran pada kunci.

Algoritma RSASSA-PSS

Algoritma RSASSA-PSS adalah update untuk algoritma RSA, dan menggunakan monikers PS256, PS384, dan PS512. Seperti varian RS*, RSASSA-PSS menggunakan pasangan kunci publik/pribadi RSA untuk tanda tangan kriptografis. Batas format, mekanisme, dan ukuran kunci sama dengan algoritma RS*.

Algoritma ECDSA

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

Algoritma Lengkung Persyaratan utama
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 algoritma berikut:

  • {i>dir<i}
  • 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 Pernyataan Utama

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

Algoritma simetris, seperti kelompok HS* untuk penandatanganan, atau algoritma A128KW untuk enkripsi, memerlukan kunci simetris atau bersama: kunci yang sama digunakan untuk penandatanganan dan verifikasi, atau kunci yang sama digunakan untuk mengenkripsi dan mendekripsi. Algoritma asimetris, seperti algoritma RS*, PS*, dan ES* untuk penandatanganan, atau algoritma ECDH* untuk mengenkripsi, menggunakan pasangan kunci - terdapat kunci publik dan kunci pribadi, yang kemudian cocok. Dalam penandatanganan, penanda tangan menggunakan kunci pribadi untuk menandatangani, dan pihak mana pun dapat menggunakan kunci publik untuk memverifikasi tanda tangan. Dalam proses enkripsi, encoder menggunakan kunci publik untuk mengenkripsi, sedangkan pendekripsi menggunakan kunci pribadi untuk mendekripsi. Kunci publik, seperti namanya, dapat dibagikan secara publik, dan tidak perlu dirahasiakan.

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

Format PEM

Untuk kunci publik atau pribadi, encoding PEM digunakan secara umum yang didefinisikan dalam IETF RFC 7468. Berikut ini contoh 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. JSON Web Key Set (JWKS) adalah struktur JSON yang mewakili kumpulan JWK. JWK dan JWKS dijelaskan dalam RFC7517. Lihat contoh JWKS di Lampiran A. Contoh Set Kunci Web JSON.

JWKS dimaksudkan untuk memungkinkan pihak mana pun mewakili kumpulan kunci dalam format standar. Kasus penggunaan utamanya adalah berbagi kunci publik secara standar, melalui endpoint HTTP yang mengirimkan data dalam format JWKS. Saat perusahaan atau sistem yang menghasilkan JWS atau JWT yang ditandatangani, seperti Penyedia Identitas, memublikasikan kunci publiknya, semua sistem atau aplikasi yang dapat membaca kunci publik tersebut dapat memverifikasi tanda tangan yang dibuat oleh pihak yang menandatangani. Sebaliknya, semua sistem atau aplikasi yang ingin mengenkripsi data yang hanya boleh dibaca oleh pihak atau perusahaan tertentu, dapat mengambil kunci publik milik pihak atau perusahaan tersebut, dan menghasilkan JWT terenkripsi untuk tujuan tersebut.

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

  • kty - Jenis kunci, seperti RSA atau EC.
  • kid - ID kunci. Ini dapat berupa nilai string unik yang arbitrer; tidak boleh ada duplikat dalam satu kumpulan kunci. Jika JWT masuk memiliki ID kunci yang terdapat di dalam kumpulan JWKS, kebijakan VerifyJWS atau VerifyJWT akan menggunakan kunci publik yang benar untuk memverifikasi tanda tangan JWS/JWT.

Berikut adalah contoh elemen opsional dan nilainya:

  • alg: Algoritme kunci. Algoritme ini harus sesuai dengan algoritma penandatanganan di JWS/JWT.
  • penggunaan: 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 saat ini) 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 membuat atau memverifikasi JWS atau JWT, Anda harus menyediakan kunci untuk digunakan dalam operasi kriptografi.

Saat membuat JWT bertanda tangan, Anda harus 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 membuat tanda tangan.
  • Dalam kasus algoritma HS*, Anda harus menyediakan kunci simetris yang akan digunakan saat membuat tanda tangan.

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

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

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

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

  • Hasilkan JWT yang ditandatangani dengan algoritma HS256. Kunci yang diperlukan dalam kasus ini adalah kunci simetris. Kebijakan ini menyediakan variabel konteks yang berisi kunci rahasia yang dienkode 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. Seperti dalam contoh di atas, kebijakan ini menyediakan variabel konteks yang berisi kunci rahasia yang dienkode 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 kunci publik berenkode PEM.

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

  • Hasilkan JWT yang ditandatangani dengan algoritma PS256. Kunci yang diperlukan dalam kasus ini adalah kunci RSA pribadi. 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 kunci saat memverifikasi JWS atau JWT yang ditandatangani

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

Sebagai contoh, misalkan penerbit menandatangani JWT dengan kunci pribadi. "Key ID" mengidentifikasi kunci publik yang cocok yang harus digunakan untuk memverifikasi JWT. Daftar kunci publik biasanya tersedia di beberapa endpoint yang dikenal, 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 endpoint JWKS, Anda memiliki beberapa opsi:

  • Opsi 1: Dalam konfigurasi kebijakan, tentukan uri endpoint JWKS 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 uri="https://www.googleapis.com/oauth2/v3/certs"/>
  </PublicKey>
  . . .
</VerifyJWT>

    Dalam hal ini, Apigee akan:

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

  • Opsi 2: Dalam konfigurasi kebijakan, tentukan variabel yang menyimpan uri endpoint JWKS 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 uriRef="variable-containing-a-uri"/>
  </PublicKey>
  . . .
</VerifyJWT>

    Dalam hal ini, Apigee akan melakukan langkah yang sama seperti di atas, kecuali bahwa Apigee akan mengambil JWKS bukan dari URI hard code, tetapi dari uri yang ditentukan dalam variabel yang direferensikan oleh atribut uriRef. Caching 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, kecuali bahwa 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 ServiceCallout, KVM, atau file properti yang terkait dengan proxy.

JWKS sebagai sumber kunci saat menghasilkan JWT terenkripsi

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

Pendekatan umumnya adalah menentukan uri endpoint JWKS dalam konfigurasi kebijakan dalam 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. Rangkai 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 cache internal jika endpoint JWKS ini telah digunakan sebelumnya. Saat ini, TTL cache adalah 5 menit.
  3. Ekstrak JWK dengan ID kunci yang tercantum dalam elemen PublicKey/Id dari JWKS. Menampilkan kesalahan jika kunci dengan ID kunci tersebut tidak ada.
  4. Periksa apakah algoritma untuk JWK cocok dengan algoritma yang ditentukan dalam konfigurasi kebijakan. Menampilkan 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, susun semua bagian menjadi JWT terenkripsi serial.

Alternatifnya, Anda dapat menggunakan atribut uriRef untuk menentukan variabel yang menyimpan URI endpoint 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, kecuali bahwa Apigee akan mengambil JWKS dari URI yang ditentukan dalam variabel yang direferensikan oleh atribut uriRef, bukan URI hard code. Apigee akan membaca JWKS dari cache internal jika endpoint JWKS ini telah digunakan sebelumnya.