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 antara aplikasi 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 mengakibatkan kondisi error. Demikian pula, saat menggunakan kebijakan DecodeJWS atau DecodeJWT, JWS/JWT yang salah format akan menyebabkan kondisi error.

Video

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

Tonton video singkat untuk mempelajari struktur JWT lebih lanjut.

Kasus penggunaan

Anda dapat menggunakan kebijakan JWS/JWT untuk:

  • Buat JWS/JWT baru di sisi endpoint proxy atau target 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 melampirkan JWS/JWT tersebut ke permintaan yang dikirim ke target. JWS/JWT dan klaimnya kemudian akan tersedia untuk memungkinkan layanan backend menerapkan pemrosesan keamanan lebih lanjut.
  • Memverifikasi dan mengekstrak klaim dari JWS/JWT yang diperoleh dari permintaan klien masuk, dari respons layanan target, dari respons kebijakan Service Callout, 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 Verify 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 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 formulir terpisah yang menghilangkan payload dari JWS:

Header..Signature

Dengan JWS yang terpisah, payload dikirim secara terpisah dari JWS. Anda menggunakan elemen <DetachedContent> dari kebijakan Verifikasi JWS untuk menentukan payload JWS mentah yang 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 token lebih lanjut 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 antara aplikasi 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 octet, 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 Apigee GenerateJWT dan VerifyJWT 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 Registered Claim Names 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" 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 menghapus payload. Payload terpisah memungkinkan Anda mengirim JWS dan payload secara terpisah. Penggunaan payload terpisah dapat lebih hemat 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 jika payload tidak perlu bersifat rahasia, tetapi penting untuk memberikan jaminan integritas dan non-penolakan 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 bersifat rahasia. JWT terenkripsi memberikan kerahasiaan untuk payload, karena hanya pemegang kunci yang sesuai yang dapat mendekripsinya.

Anda dapat menggunakan JWT terenkripsi dan ditandatangani secara bersamaan, terutama jika JWT terenkripsi menggunakan algoritma kriptografi asimetris (RSA, ECDSA). Dalam hal ini, identitas pembuat 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 secret, untuk membuat tanda tangan (juga dikenal sebagai menandatangani 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. Spesifikasi JWA menggunakan moniker RS256, RS384, dan RS512 untuk merepresentasikan opsi ini. Dengan tanda tangan RSA, pihak penanda tangan menggunakan kunci pribadi RSA untuk menandatangani JWS/JWT, dan pihak verifikasi 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 update untuk algoritma RSA, dan menggunakan moniker 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 elips dengan kurva P-256, P-384, atau P-521. Saat Anda menggunakan algoritma ECDSA, algoritma tersebut akan menentukan jenis kunci publik dan pribadi yang harus Anda tentukan:

Algoritme Kurva 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 ini 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 operasi kriptografis apa pun 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, enkriptor menggunakan kunci publik untuk mengenkripsi, dan dekriptor 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 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 berenkode base64.

Format PEM

Untuk kunci publik atau pribadi, biasanya menggunakan encoding PEM, yang ditentukan dalam IETF RFC 7468. Berikut adalah 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 serupa untuk kunci publik, atau kunci pribadi terenkripsi.

Format JWKS

JSON Web Key (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 JSON Web Key Set.

JWKS dimaksudkan untuk memungkinkan pihak mana pun merepresentasikan kumpulan kunci dalam format standar. Kasus penggunaan utama adalah membagikan kunci publik dengan cara 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, sistem atau aplikasi apa pun yang dapat membaca kunci publik, dapat memverifikasi tanda tangan yang dihasilkan oleh pihak penanda tangan. 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. Ini dapat berupa nilai string unik arbitrer; tidak boleh ada duplikat dalam satu kumpulan kunci. Jika JWT masuk memiliki ID kunci yang ada 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: Algoritma kunci. Nilai ini harus cocok dengan algoritma penandatanganan di JWS/JWT.
  • use: Penggunaan kunci yang dimaksudkan. Nilai standarnya 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) menyertakan 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 memberikan kunci untuk digunakan dalam operasi kriptografi.

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

  • Untuk algoritma penandatanganan RS*, PS*, atau ES*, yang semuanya menggunakan kunci asimetris, Anda harus memberikan kunci pribadi untuk membuat tanda tangan.
  • Untuk 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.

  • Untuk algoritma penandatanganan RS*, PS*, atau ES*, Anda harus memberikan kunci publik yang terkait dengan kunci pribadi yang awalnya digunakan untuk menandatangani token.
  • Untuk algoritma HS*, Anda harus memberikan kunci simetris yang sama dengan 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
  • 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 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 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>

  • 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 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 hal 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 yang ditandatangani

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

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 mereka 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 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 dicatat di header JWS/JWT. Menampilkan error jika kunci dengan ID kunci tersebut tidak ada.
    5. Pastikan algoritma untuk JWK cocok dengan algoritma yang ditentukan dalam konfigurasi kebijakan. Tolak verifikasi dan tampilkan error jika algoritma tidak cocok.
    6. Gunakan kunci publik tersebut untuk memverifikasi tanda tangan di JWS/JWT. Tolak verifikasi dan tampilkan error 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-langkah yang sama seperti di atas, kecuali bahwa 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 code 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 ref="variable-that-holds-a-jwks"/>
  </PublicKey>
  . . .
</VerifyJWT>

    Dalam hal ini, Apigee akan melakukan langkah-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 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 yang 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. Gabungkan 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 dicatat dalam elemen PublicKey/Id dari JWKS. Menampilkan error jika kunci dengan ID kunci tersebut tidak ada.
  4. Pastikan algoritma untuk JWK cocok dengan algoritma yang ditentukan dalam konfigurasi kebijakan. Menampilkan error jika algoritma tidak cocok.
  5. Buat urutan acak yang akan 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 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-langkah yang sama seperti di atas, kecuali bahwa Apigee akan mengambil JWKS dari URI yang ditentukan dalam variabel yang dirujuk oleh atribut uriRef, bukan URI yang di-hardcode. Apigee akan membaca JWKS dari cache internal jika endpoint JWKS ini telah digunakan sebelumnya.