Ringkasan kebijakan JWS dan JWT

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

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

Pengantar

JWS dan JWT biasanya digunakan untuk membagikan klaim atau pernyataan antaraplikasi yang terhubung. Kebijakan JWS/JWT memungkinkan proxy API Apigee untuk:

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

Video

Tonton video singkat untuk pengantar singkat tentang JWT. Meskipun video ini khusus untuk membuat JWT, banyak konsepnya yang sama dengan JWS.

Video singkat untuk mempelajari lebih lanjut struktur JWT.

Kasus penggunaan

Anda dapat menggunakan kebijakan JWS/JWT untuk:

  • Buat JWS/JWT baru di sisi proxy atau endpoint target proxy Apigee. Misalnya, Anda dapat membuat alur permintaan proxy yang menghasilkan JWS/JWT dan menampilkannya ke klien. Atau, Anda dapat mendesain proxy sehingga menghasilkan JWS/JWT pada alur permintaan target, dan melampirkannya ke permintaan yang dikirim ke target. JWS/JWT dan klaimnya kemudian 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, dari respons kebijakan Panggilan Layanan, atau dari sumber lain. Untuk JWS/JWT yang ditandatangani, Apigee akan menggunakan salah satu algoritma RSA, ECDSA, atau HMAC untuk memverifikasi tanda tangan, baik JWS/JWT dibuat oleh Apigee maupun pihak ketiga. Untuk JWT terenkripsi, Apigee akan mendekripsi JWT, menggunakan salah satu algoritma enkripsi JWA yang didukung (lihat IETF RFC 7518).
  • Mendekode JWS/JWT. Dekode paling berguna jika digunakan bersama dengan kebijakan Verifikasi JWS/JWT, dalam kasus ketika 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 Generate JWS/JWT membuat ketiga bagian tersebut.
  • Kebijakan Verify 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 dikirim secara terpisah dari JWS. Anda menggunakan elemen <DetachedContent> dari kebijakan Verify JWS untuk menentukan payload JWS mentah yang tidak dienkode. Kebijakan Verify JWS kemudian memverifikasi JWS dengan 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 dienkode, serta ditandatangani atau dienkripsi, lihat dokumen standar yang relevan:

Perbedaan antara JWS dan JWT

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

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

Karena format JWT selalu menggunakan objek JSON untuk merepresentasikan payload, kebijakan GenerateJWT dan VerifyJWT Apigee memiliki dukungan bawaan untuk menangani Nama Klaim Terdaftar 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 memberikan variabel konteks yang merepresentasikan payload. Karena JWS dapat menggunakan representasi data apa pun untuk payload, tidak ada konsep "klaim payload" dalam 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, dengan JWS menghilangkan payload. Payload yang tidak terlampir memungkinkan Anda mengirim JWS dan payload secara terpisah. Menggunakan payload 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 bertanda tangan jika payload tidak perlu dirahasiakan, tetapi penting untuk memberikan jaminan integritas dan 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 saat payload harus rahasia. JWT terenkripsi memberikan kerahasiaan untuk payload, karena hanya pemegang kunci yang sesuai yang dapat mendekripsinya.

JWT terenkripsi dan bertanda tangan dapat digunakan bersama, terutama saat 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 yang ditandatangani dalam JWT terenkripsi menggunakan pendekatan ini memberikan jaminan anti penyangkalan dan kerahasiaan. Kebijakan Apigee dapat menghasilkan serta mendekode & memverifikasi kombinasi tersebut.

Algoritma tanda tangan

Untuk JWT yang ditandatangani, kebijakan Verifikasi JWS/JWT dan Pembuatan JWS/JWT 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 secret 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 kriptografi. Spesifikasi JWA menggunakan sebutan RS256, RS384, dan RS512 untuk merepresentasikan opsi ini. Dengan tanda tangan RSA, pihak penandatangan menggunakan kunci pribadi RSA untuk menandatangani JWS/JWT, dan pihak yang memverifikasi menggunakan kunci publik RSA yang cocok untuk memverifikasi tanda tangan pada JWS/JWT. Tidak ada persyaratan ukuran pada kunci.

Algoritma RSASSA-PSS

Algoritma RSASSA-PSS adalah update untuk algoritma RSA, dan menggunakan nama PS256, PS384, dan PS512. Seperti varian RS*, RSASSA-PSS menggunakan pasangan kunci publik/pribadi RSA untuk tanda tangan kriptografis. Format, mekanisme, dan batas ukuran kunci sama seperti untuk 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:

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

Algoritma enkripsi

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

  • 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 lainnya, menjelaskan cara menggunakan kunci kriptografis untuk menandatangani atau mengenkripsi informasi. Elemen dasar untuk setiap operasi kriptografis mencakup algoritma dan kunci. Algoritma yang berbeda memerlukan jenis kunci yang berbeda, dan dalam beberapa kasus, ukuran kunci yang berbeda.

Algoritma simetris, seperti keluarga 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 enkripsi, menggunakan 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 melakukan enkripsi, dan dekripsi menggunakan kunci pribadi untuk mendekripsi. Kunci publik, seperti namanya, dapat dibagikan secara publik, dan tidak perlu dirahasiakan.

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

Format PEM

Untuk kunci publik atau pribadi, biasanya digunakan encoding PEM, yang ditentukan dalam IETF RFC 7468. Berikut contoh kunci pribadi yang ditampilkan dalam format PEM: 

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

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

Format JWKS

JSON Web Key (JWK) adalah struktur data JSON yang merepresentasikan satu kunci kriptografi. JSON Web Key Set (JWKS) adalah struktur JSON yang merepresentasikan sekumpulan JWK. JWK dan JWKS dijelaskan dalam RFC7517. Lihat contoh JWKS di Lampiran A. Contoh JSON Web Key Sets.

JWKS dimaksudkan untuk memungkinkan pihak mana pun merepresentasikan sekumpulan kunci dalam format standar. Kasus penggunaan utama adalah berbagi kunci publik dengan cara standar, melalui endpoint HTTP yang mengirimkan data dalam format JWKS. Saat perusahaan atau sistem yang membuat JWS atau JWT bertanda tangan, seperti Penyedia Identitas, memublikasikan kunci publiknya, sistem atau aplikasi apa pun yang dapat membaca kunci publik, dapat memverifikasi tanda tangan yang dibuat oleh pihak penandatangan. Sebaliknya, sistem atau aplikasi apa pun yang ingin mengenkripsi data yang hanya boleh dibaca oleh pihak atau perusahaan tertentu, dapat mengambil kunci publik milik pihak atau perusahaan tersebut, dan membuat JWT terenkripsi untuk tujuan tersebut.

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

  • kty - Jenis kunci, seperti RSA atau EC.
  • kid - ID kunci. Nilai ini dapat berupa nilai string unik arbitrer apa pun; tidak boleh ada duplikat dalam satu set kunci. Jika JWT masuk memiliki ID kunci yang ada dalam set 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: Algoritma kunci. Algoritma ini harus cocok dengan algoritma penandatanganan di JWS/JWT.
  • use: Penggunaan kunci yang dimaksudkan. Nilai umum 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 sekarang sudah tidak berlaku) mencakup elemen dan nilai yang diperlukan, dan 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 untuk kebijakan JWS dan JWT

Baik saat membuat atau memverifikasi JWS atau JWT, Anda harus memberikan kunci untuk digunakan dalam operasi kriptografi.

Saat membuat JWT yang ditandatangani, Anda harus memberikan kunci yang dapat menghasilkan tanda tangan.

  • Dalam kasus algoritma penandatanganan RS*, PS*, atau ES*, yang semuanya menggunakan kunci asimetris, Anda harus memberikan kunci pribadi untuk membuat tanda tangan.
  • Dalam kasus algoritma HS*, Anda harus 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 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 yang digunakan untuk menandatangani JWS atau JWT.

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

  • Berikan nilai kunci secara langsung (biasanya melalui variabel konteks), atau
  • Memberikan 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 menggambarkan cara Anda dapat menyediakan kunci secara langsung dalam berbagai skenario.

  • Buat JWT yang ditandatangani dengan algoritma HS256. Kunci yang diperlukan 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>

  • Memverifikasi JWT yang ditandatangani dengan algoritma HS256. Kunci yang diperlukan dalam hal ini adalah kunci simetris. Seperti pada contoh di atas, kebijakan ini menyediakan 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 kunci publik yang dienkode PEM.

    <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 hal ini adalah kunci RSA pribadi. Kebijakan ini menyediakan variabel konteks yang berisi kunci pribadi yang dienkode 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 bertanda tangan

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

Misalnya, 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 terkenal, seperti endpoint Google Identity atau endpoint Firebase Authentication. Penyedia lain akan memiliki endpoint publik sendiri yang memublikasikan kunci dalam format JWKS.

Saat menggunakan Apigee untuk memverifikasi JWS atau JWT bertanda tangan dengan kunci publik yang dibagikan melalui endpoint 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 header JWS/JWT untuk menemukan algoritma penandatanganan (alg), seperti RS256, dan tolak JWT masuk jika algoritma tersebut tidak cocok 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 (kid). Jika JWT masuk tidak menyertakan ID kunci (kid) di header, pemetaan kid ke kunci verifikasi tidak dapat dilakukan, dan Apigee akan menampilkan error.
    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. Tolak verifikasi dan tampilkan kesalahan jika algoritma tidak cocok.
    6. Gunakan kunci publik tersebut untuk memverifikasi tanda tangan pada JWS/JWT. Tolak verifikasi dan tampilkan kesalahan jika tanda tangan tidak diverifikasi.

  • 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-langkah yang sama seperti di atas, kecuali Apigee akan mengambil JWKS bukan dari URI hardcode, tetapi dari URI yang ditentukan dalam variabel yang dirujuk oleh atribut uriRef. Penyimpanan dalam cache tetap berlaku.

  • Opsi 3: Dalam konfigurasi kebijakan, tentukan variabel yang menyimpan data JWKS hard-coded 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-langkah yang sama seperti di atas, kecuali Apigee akan mengambil JWKS bukan dari URI, tetapi dari variabel konteks yang Anda tentukan di atribut ref. Biasanya, Anda akan memuat variabel konteks ini dari ServiceCallout, KVM, atau file properti yang terkait dengan proxy.

JWKS sebagai sumber kunci saat membuat JWT terenkripsi

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

Pendekatan umum adalah menentukan URI endpoint JWKS dalam konfigurasi kebijakan 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. Kumpulkan header dan payload 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 dicatat 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, gabungkan semua bagian menjadi JWT terenkripsi yang diserialisasi.

Alternatifnya adalah menggunakan atribut uriRef untuk menentukan variabel yang berisi 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-langkah yang sama seperti di atas, kecuali Apigee akan mengambil JWKS dari URI yang ditentukan dalam variabel yang dirujuk oleh atribut uriRef, bukan URI hard-code. Apigee akan membaca JWKS dari cache internal jika endpoint JWKS ini telah digunakan sebelumnya.