Halaman ini diterjemahkan oleh Cloud Translation API.

Ringkasan kebijakan JWS dan JWT

Anda sedang 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 Apigee JWS/JWT yang mungkin menarik bagi developer proxy Apigee.

Pengantar

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

Buat JWT atau JWS yang ditandatangani.
Memverifikasi JWT atau JWS yang ditandatangani dan mengklaim dalam JWS/JWT.
Dekode JWT atau JWS yang ditandatangani tanpa memvalidasi tanda tangan.

Pada dua kasus terakhir, kebijakan tersebut 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 Verifikasi 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 singkat untuk pengenalan singkat tentang JWT. Meskipun video ini khusus untuk menghasilkan JWT, banyak konsepnya yang sama untuk JWS.

Video singkat untuk mempelajari lebih lanjut tentang struktur JWT.

Kasus penggunaan

Anda dapat menggunakan kebijakan JWS/JWT untuk:

Buat JWS/JWT baru di sisi endpoint proxy atau target dari proxy Edge. 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. Klaim tersebut 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, respons kebijakan Service Callout, atau dari sumber lainnya. Edge akan memverifikasi tanda tangan di JWS/JWT, baik JWS/JWT dihasilkan oleh pihak ketiga, atau oleh Edge itu sendiri, menggunakan algoritma RSA atau HMAC.
Mendekode JWS/JWT. Decoding paling berguna jika digunakan bersamaan dengan kebijakan Verify JWS/JWT, yaitu jika nilai klaim (JWT) atau header (JWS/JWT) dari dalam JWS/JWT harus diketahui sebelum memverifikasi JWS/JWT.

Bagian dari JWS/JWT

JWS/JWT bertanda tangan 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 Verifikasi JWS/JWT mempelajari ketiga bagian tersebut.
Kebijakan Decode JWS/JWT hanya memeriksa header dan payload.

JWS juga mendukung format detached yang menghilangkan payload dari JWS:

header..signature

Dengan JWS yang terlepas, payload akan dikirim secara terpisah dari JWS. Anda dapat menggunakan elemen <DetachedContent> dari kebijakan Verify 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>.

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

JWT: IETF RFC7519
JWS: IETF RFC7515

Perbedaan antara JWS dan JWT

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

JWT
- Payload selalu berupa objek JSON
- Payload selalu ditambahkan ke JWT
- Header typ token selalu ditetapkan ke JWT
JWS
- Payload dapat diwakili oleh format apa pun, seperti objek JSON, aliran byte, aliran octet, dan lainnya
- Payload tidak harus dipasang ke JWS

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

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

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

Tentang algoritma tanda tangan

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 JWS/JWT Decode tetap berfungsi, apa pun 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 untuk memverifikasi tanda tangan.

Panjang minimum kunci rahasia 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 kriptografis. Dengan tanda tangan RSA, pihak yang menandatangani menggunakan kunci pribadi RSA untuk menandatangani JWS/JWT, dan pihak yang memverifikasi 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 merupakan pembaruan dari algoritma RSA. Seperti RSS, RSASSA-PSS menggunakan pasangan kunci publik/pribadi RSA untuk tanda tangan kriptografis. Format kunci sama seperti RSS. Pihak yang menandatangani menggunakan kunci pribadi untuk menandatangani JWS/JWT, dan pihak yang memverifikasi menggunakan kunci publik yang cocok untuk memverifikasi tanda tangan di JWS/JWT. Tidak ada persyaratan ukuran untuk kunci.

Algoritma ECDSA

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

Algorithm	Kurva	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 utama

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

Menggunakan Kumpulan Kunci Web JSON (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 yang sebenarnya (biasanya disediakan dalam variabel flow), atau
menggunakan kunci publik yang digabungkan dalam JWKS.

Tentang JWKS

JWKS adalah struktur JSON yang mewakili sekumpulan Kunci Web JSON (JWK). JWK adalah struktur data JSON yang merepresentasikan kunci kriptografis. JWK dan JWKS dijelaskan di RFC7517. Lihat contoh JKWS di Lampiran A. Contoh Kumpulan Kunci Web JSON

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 (tidak ada duplikat dalam kumpulan kunci). Jika JWT masuk memiliki ID kunci yang ada di 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. Ini harus sesuai dengan algoritma penandatanganan di JWS/JWT.
use - Jika ada, harus berupa sig.

JWKS berikut mencakup 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 Anda untuk menggunakan JWKS

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

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

Ini adalah urutan dasar yang harus dilakukan Edge (atau platform apa pun yang berfungsi dengan JWKS) agar dapat digunakan dengan JWS/JWT yang memiliki JWKS:

Periksa header JWS/JWT untuk menemukan ID Kunci (anak).
Periksa header JWS/JWT untuk menemukan algoritma penandatanganan (alg), seperti RS256.
Ambil daftar kunci dan ID dari JWKS endpoint populer untuk penerbit tertentu.
Ekstrak kunci publik dari daftar kunci dengan ID kunci yang tercantum dalam header JWS/JWT dan dengan algoritme yang cocok, jika kunci JWKS menentukan algoritma tersebut.
Gunakan kunci publik tersebut untuk memverifikasi tanda tangan pada JWS/JWT.
Catatan: Kebijakan Verifikasi JWS/JWT melakukan pencarian kunci untuk kunci secara otomatis.

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

Ambil daftar kunci dan ID dari endpoint yang dikenal untuk penerbit tertentu. Anda dapat menggunakan kebijakan Panggilan Layanan untuk langkah ini.
Catatan: Sebaiknya simpan JWKS dalam cache untuk menghindari Pemanggilan Layanan pada setiap permintaan.

Dalam kebijakan Verify JWS/JWT, tentukan lokasi JWS/JWT dalam 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 Verifikasi JWT melakukan hal lainnya:

Jika kunci dengan ID Kunci yang cocok dengan ID Kunci (anak) yang dinyatakan dalam JWT tidak ditemukan di JWKS, kebijakan Verifikasi JWT akan menampilkan error dan tidak memvalidasi JWT.
Jika JWT masuk tidak memuat ID kunci (anak) di header, pemetaan keyid-ke-verification-key ini tidak mungkin dilakukan.

Sebagai desainer proxy, Anda bertanggung jawab untuk menentukan kunci yang akan digunakan; dalam beberapa kasus, hal ini mungkin berupa kunci tetap yang di-hard code.