Ringkasan kebijakan JWS dan JWT

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

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 Edge untuk:

  • Membuat JWT atau JWS yang ditandatangani.
  • Memverifikasi JWT atau JWS yang ditandatangani dan klaim dalam JWS/JWT.
  • Mendekode JWT atau JWS yang ditandatangani tanpa memvalidasi tanda tangan.

Dalam dua kasus terakhir, kebijakan ini juga menetapkan variabel yang memungkinkan kebijakan tambahan, atau layanan backend itu sendiri, untuk memeriksa klaim yang divalidasi dan membuat keputusan berdasarkan klaim tersebut.

Saat menggunakan kebijakan Verify JWS/JWT, JWS/JWT yang tidak valid akan ditolak dan akan menghasilkan kondisi error. Demikian pula, saat menggunakan kebijakan Decode JWS/JWT, JWS/JWT yang salah format akan menghasilkan kondisi error.

Video

Tonton video pendek untuk pengantar cepat tentang JWT. Meskipun video ini khusus untuk membuat JWT, banyak konsepnya sama untuk JWS.

Tonton video pendek untuk mempelajari struktur JWT lebih lanjut.

Kasus penggunaan

Anda dapat menggunakan kebijakan JWS/JWT untuk:

  • Membuat JWS/JWT baru di sisi endpoint proxy atau target proxy Edge. 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. Klaim tersebut 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 Panggilan Layanan, atau dari sumber lain. Edge akan memverifikasi tanda tangan pada JWS/JWT, baik JWS/JWT dibuat oleh pihak ketiga, atau oleh Edge itu sendiri, menggunakan algoritma RSA atau HMAC.
  • Mendekode JWS/JWT. Dekode paling berguna jika digunakan bersama dengan kebijakan Verify JWS/JWT, saat nilai klaim (JWT) atau header (JWS/JWT) dari dalam JWS/JWT harus diketahui sebelum memverifikasi JWS/JWT.

Bagian dari JWS/JWT

JWS/JWT yang ditandatangani mengenkode informasi dalam tiga bagian yang dipisahkan oleh titik: header, payload, dan tanda tangan:

header.payload.signature
  • Kebijakan Generate JWS/JWT membuat ketiga bagian tersebut.
  • Kebijakan Verify JWS/JWT memeriksa ketiga bagian tersebut.
  • Kebijakan Decode JWS/JWT hanya memeriksa header dan payload.

JWS juga mendukung format terpisah yang menghilangkan payload dari JWS:

header..signature

Dengan JWS 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 menggunakan header dan tanda tangan di JWS serta payload yang ditentukan oleh elemen <DetachedContent>.

Untuk mempelajari token lebih lanjut dan cara token dienkode dan ditandatangani, lihat:

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
  • JWS
    • Payload dapat direpresentasikan oleh format apa pun, seperti objek JSON, aliran byte, aliran oktet, dan lainnya
    • Payload tidak harus dilampirkan ke JWS

Karena format JWT selalu menggunakan objek JSON untuk merepresentasikan payload, kebijakan Edge Generate JWT dan Verify JWT memiliki dukungan bawaan untuk menangani Nama Klaim Terdaftar umum, seperti aud, iss, sub, dan lainnya. Artinya, Anda dapat menggunakan elemen kebijakan Generate JWT untuk menetapkan klaim ini dalam payload, dan elemen kebijakan Verify JWT untuk memverifikasi nilainya. Lihat bagian Nama Klaim Terdaftar dari spesifikasi JWT untuk mengetahui informasi selengkapnya.

Selain mendukung Nama Klaim Terdaftar tertentu, kebijakan Generate JWT secara langsung mendukung penambahan klaim dengan nama arbitrer ke JWT. Setiap klaim adalah pasangan nama/nilai sederhana, dengan nilai dapat berupa jenis angka, boolean, string, peta, atau array.

Karena JWS dapat menggunakan representasi data apa pun untuk payload, Anda tidak dapat menambahkan klaim ke payload. Kebijakan Generate JWS mendukung penambahan klaim dengan nama arbitrer ke header JWS. Selain itu, kebijakan JWS mendukung payload terpisah, dengan JWS menghilangkan payload. Payload terpisah memungkinkan Anda mengirim JWS dan payload secara terpisah dan diperlukan oleh beberapa standar keamanan.

Mencegah injeksi template saat menggunakan JWS dan JWT

Untuk mencegah pengungkapan data yang tidak sah, ikuti panduan ini saat menggunakan kebijakan GenerateJWT atau GenerateJWS:

  • Hindari referensi langsung ke input pengguna: Jangan pernah menggunakan input yang tidak tepercaya (seperti request.queryparam.* atau request.header.*) secara langsung dalam atribut ref yang mendukung pembuatan template.
  • Sanitasi input: Jika Anda harus menggunakan data eksternal dalam klaim JWT/JWS, gunakan kebijakan AssignMessage terlebih dahulu untuk menghapus tanda kurung kurawal ({ }) atau karakter template lainnya dari input sebelum mereferensikannya.
  • Gunakan klaim eksplisit untuk string: Untuk klaim string sederhana, hindari type="map". Menggunakan type="string" default mencegah pembuatan template implisit dari nilai yang direferensikan.
  • Perhatikan inkonsistensi perilaku antara kebijakan verifikasi dan pembuatan: Kebijakan pembuatan JWS dan JWT berperilaku berbeda dengan kebijakan verifikasi terkait pembuatan template.

Tentang algoritma tanda tangan

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 Decode JWS/JWT berfungsi terlepas dari algoritma yang digunakan untuk menandatangani JWS/JWT.

Algoritma HMAC

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

Panjang minimum kunci secret bergantung pada kekuatan bit algoritma:

  • HS256: Panjang kunci minimum 32 byte
  • HS386: Panjang kunci minimum 48 byte
  • HS512: Panjang kunci minimum 64 byte

Algoritma RSA

Algoritma RSA menggunakan pasangan kunci publik/pribadi untuk tanda tangan kriptografi. Dengan tanda tangan RSA, pihak penandatangan menggunakan kunci pribadi RSA untuk menandatangani JWS/JWT, dan pihak verifikasi 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. Seperti RSS, RSASSA-PSS menggunakan pasangan kunci publik/pribadi RSA untuk tanda tangan kriptografi. Format kunci sama seperti untuk RSS. Pihak penandatangan menggunakan kunci pribadi untuk menandatangani JWS/JWT, dan pihak verifikasi menggunakan kunci publik yang cocok untuk memverifikasi tanda tangan pada JWS/JWT. Tidak ada persyaratan ukuran pada kunci.

Algoritma ECDSA

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

Algoritma Kurva Persyaratan kunci
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 kunci

Kebijakan JWS/JWT mendukung semua algoritma enkripsi kunci yang didukung oleh OpenSSL.

Menggunakan JSON Web Key Set (JWKS) untuk memverifikasi JWS/JWT

Saat memverifikasi JWS/JWT yang ditandatangani, Anda harus memberikan kunci publik yang terkait dengan kunci pribadi yang digunakan untuk menandatangani token. Anda memiliki dua opsi untuk memberikan kunci publik ke kebijakan verifikasi JWS/JWT:

  • menggunakan nilai kunci publik sebenarnya (biasanya disediakan dalam flow variable), atau
  • menggunakan kunci publik yang digabungkan dalam JWKS.

Tentang JWKS

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

Struktur JWKS

RFC7517 menjelaskan elemen kunci JWKS untuk setiap jenis kunci, seperti "RSA" atau "EC". Misalnya, bergantung pada jenis kunci, parameter ini dapat mencakup:

  • kty - Jenis kunci, seperti "RSA" atau "EC".
  • kid (ID kunci) - Dapat berupa nilai arbitrer apa pun (tidak ada duplikat dalam kumpulan kunci ). Jika JWT masuk memiliki ID kunci yang ada dalam kumpulan JWKS, kebijakan 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 - Jika ada, harus sig.

JWKS berikut menyertakan elemen dan nilai yang diperlukan dan akan valid di Edge (dari https://www.googleapis.com/oauth2/v3/certs):

{
   "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",
      }
   ]
}

Mendesain proxy untuk menggunakan JWKS

Saat JWS/JWT diperoleh dari penerbit, penerbit sering kali menyisipkan ID Kunci (atau kid) ke dalam header JWS/JWT. Kunci memberi tahu penerima JWS/JWT cara menemukan kunci publik atau secret yang diperlukan untuk memverifikasi tanda tangan pada JWS/JWT yang ditandatangani.

Misalnya, anggaplah penerbit menandatangani JWT dengan kunci pribadi. "ID Kunci" mengidentifikasi kunci publik yang cocok untuk digunakan guna memverifikasi JWT. Daftar kunci publik biasanya tersedia di beberapa endpoint terkenal, misalnya: https://www.googleapis.com/oauth2/v3/certs.

Ini adalah urutan dasar yang perlu dilakukan Edge (atau platform apa pun yang berfungsi dengan JWKS) untuk bekerja dengan JWS/JWT yang memiliki JWKS:

  1. Periksa header JWS/JWT untuk menemukan ID Kunci (kid).
  2. Periksa header JWS/JWT untuk menemukan algoritma penandatanganan (alg), seperti RS256.
  3. Ambil daftar kunci dan ID dari JWKS endpoint terkenal untuk penerbit tertentu.
  4. Ekstrak kunci publik dari daftar kunci dengan ID kunci yang tercatat di header JWS/JWT dan dengan algoritma yang cocok, jika kunci JWKS menentukan algoritma.
  5. Gunakan kunci publik tersebut untuk memverifikasi tanda tangan pada JWS/JWT.

Sebagai developer proxy API Edge, Anda harus melakukan hal berikut untuk melakukan verifikasi JWS/JWT:

  1. Ambil daftar kunci dan ID dari endpoint terkenal untuk penerbit tertentu. Anda dapat menggunakan kebijakan Panggilan Layanan untuk langkah ini.
  2. Dalam kebijakan Verify JWS/JWT, tentukan lokasi JWS/JWT di elemen <Source> dan payload 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 ref="public.jwks"/>
    </PublicKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
</VerifyJWT>

Kebijakan Verify JWT melakukan semua hal lainnya:

  • Jika kunci dengan ID Kunci yang cocok dengan ID Kunci (kid) yang ditetapkan dalam JWT tidak ditemukan di JWKS, kebijakan Verify JWT akan menampilkan error dan tidak memvalidasi JWT.
  • Jika JWT masuk tidak memiliki ID kunci (kid) di header, pemetaan keyid-ke-kunci-verifikasi ini tidak dapat dilakukan.

Sebagai desainer proxy, Anda bertanggung jawab untuk menentukan kunci yang akan digunakan; dalam beberapa kasus, kunci ini mungkin merupakan kunci tetap yang dikodekan secara permanen.