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 (Token Web JSON) dan JWS (Tanda Tangan Web JSON) dan kebijakan JWS/JWT Apigee yang mungkin menarik bagi developer proxy Apigee.

Pengantar

JWS dan JWT umumnya digunakan untuk berbagi klaim atau pernyataan antara menggunakan berbagai aplikasi obrolan. Kebijakan JWS/JWT memungkinkan proxy Edge API untuk:

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

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

Saat menggunakan kebijakan Verifikasi JWS/JWT, JWS/JWT yang tidak valid akan ditolak dan akan menyebabkan error . Demikian pula, saat menggunakan kebijakan Dekode JWS/JWT, format JWS/JWT yang salah akan menyebabkan error .

Video

Tonton video singkat untuk pengenalan singkat tentang JWT. Meskipun video ini khusus untuk menghasilkan JWT, banyak konsep yang sama untuk 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 target endpoint proxy Edge. Sebagai misalnya, Anda dapat membuat alur permintaan proxy yang menghasilkan JWS/JWT dan mengembalikannya ke klien. Atau, Anda dapat mendesain {i>proxy<i} sehingga menghasilkan JWS/JWT pada alur permintaan target, dan melampirkannya ke permintaan yang dikirim ke target. Klaim tersebut kemudian akan tersedia untuk mengaktifkan layanan backend untuk menerapkan pemrosesan keamanan lebih lanjut.
Memverifikasi dan mengekstrak klaim dari JWS/JWT yang diperoleh dari permintaan klien masuk, dari target respons layanan, dari respons kebijakan Info Layanan, atau dari sumber lain. Edge akan memverifikasi tanda tangan di JWS/JWT, apakah 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 Verifikasi JWS/JWT, saat nilai klaim (JWT) atau header (JWS/JWT) dari dalam JWS/JWT harus diketahui sebelum verifikasi JWS/JWT.

Bagian dari JWS/JWT

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

header.payload.signature

Kebijakan Buat JWS/JWT membuat ketiga bagian tersebut.
Kebijakan Verifikasi JWS/JWT memeriksa ketiga bagian tersebut.
Kebijakan Dekode JWS/JWT hanya memeriksa header dan payload.

JWS juga mendukung format terpisah yang menghilangkan payload dari JWS:

header..signature

Dengan JWS yang terpisah, payload akan dikirim secara terpisah dari JWS. Anda menggunakan Elemen <DetachedContent> kebijakan Verifikasi JWS untuk menentukan payload JWS mentah dan tidak dienkode. Verifikasi kebijakan JWS kemudian memverifikasi JWS menggunakan header dan tanda tangan di JWS serta payload yang ditentukan oleh elemen <DetachedContent>.

Untuk mempelajari lebih lanjut tentang 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 di antara aplikasi yang terhubung. Perbedaan utama antara keduanya adalah representasi payload:

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

Karena format JWT selalu menggunakan objek JSON untuk mewakili payload, Edge Menghasilkan JWT dan Verifikasi bahwa kebijakan JWT telah dilengkapi dukungan untuk menangani Nama Klaim Terdaftar yang umum, seperti aud, iss, sub, dan lainnya. Artinya, Anda dapat menggunakan elemen Buat kebijakan JWT untuk menetapkan klaim ini dalam payload, dan elemen kebijakan Verifikasi JWT untuk memverifikasi nilainya. Baca Nama Klaim Terdaftar dari spesifikasi JWT untuk informasi lebih lanjut.

Selain mendukung Nama Klaim Terdaftar tertentu, kebijakan Buat JWT secara langsung mendukung penambahan klaim dengan nama arbitrer ke JWT. Setiap klaim merupakan pasangan nama/nilai sederhana, dengan nilai dapat berupa angka 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 yang terlepas, tempat JWS menghilangkan payload. Payload yang terpisah memungkinkan Anda mengirim JWS serta payload secara terpisah dan diperlukan oleh beberapa standar keamanan.

Tentang algoritma tanda tangan

Kebijakan Verifikasi JWS/JWT dan Pembuatan JWS/JWT mendukung algoritma RSA, RSASSA-PSS, ECDSA, dan HMAC, menggunakan SHA2 {i>checksum<i} kekuatan bit 256, 384, atau 512. Kebijakan Dekode JWS/JWT berfungsi terlepas dari yang digunakan untuk menandatangani JWS/JWT.

algoritma HMAC

Algoritma HMAC bergantung pada 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 tersebut. Dengan RSA tanda tangan, pihak yang menandatangani menggunakan kunci pribadi RSA untuk menandatangani JWS/JWT, kunci publik RSA yang sesuai untuk memverifikasi tanda tangan di JWS/JWT. Tidak ada persyaratan ukuran di tombol.

Algoritma RSASSA-PSS

Algoritma RSASSA-PSS adalah pembaruan pada algoritma RSA. Seperti RSS, RSASSA-PSS menggunakan pasangan kunci publik/pribadi 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 untuk memverifikasi tanda tangan pada JWS/JWT. Tidak ada persyaratan ukuran pada kunci.

Algoritma ECDSA

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

Algoritma	Lengkung	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 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 menyediakan kunci publik yang yang terkait dengan kunci pribadi yang digunakan untuk menandatangani token. Anda memiliki dua opsi untuk memberikan kunci publik ke kebijakan JWS/JWT yang diverifikasi:

menggunakan nilai kunci publik sebenarnya (biasanya disediakan dalam variabel flow), atau
menggunakan kunci publik yang dibungkus dalam JWKS.

Tentang JWKS

JWKS adalah struktur JSON yang mewakili serangkaian Kunci Web JSON (JWK). JWK adalah data JSON yang mewakili kunci kriptografis. JWK dan JWKS dijelaskan dalam RFC7517. Lihat contoh JKWS di Apendiks A. Contoh Set Kunci Web JSON

Struktur JWKS

RFC7517 menjelaskan elemen kunci JWKS untuk setiap jenis kunci, seperti "RSA" atau "EC". Misalnya, tergantung 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 kunci ditetapkan). Jika JWT masuk membawa ID kunci yang ada dalam kumpulan JWKS, maka kebijakan akan menggunakan kunci publik yang benar untuk memverifikasi tanda tangan JWS/JWT.

Berikut adalah contoh elemen opsional dan nilainya:

alg - Algoritma kunci. Nama ini harus cocok dengan algoritma penandatanganan di JWS/JWT.
use - Jika ada, harus berupa 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",
      }
   ]
}

Merancang {i>proxy<i} untuk menggunakan JWKS

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

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

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

Periksa {i>header<i} JWS/JWT untuk menemukan ID Kunci (anak).
Periksa {i>header<i} JWS/JWT untuk menemukan algoritme penandatanganan (alg), seperti RS256.
Ambil daftar kunci dan ID dari JWKS endpoint terkenal untuk penerbit tertentu.
Ekstrak kunci publik dari daftar kunci dengan ID kunci yang tercantum di header JWS/JWT dan dengan algoritma pencocokan, jika kunci JWKS menentukan algoritma.
Gunakan kunci publik tersebut untuk memverifikasi tanda tangan di JWS/JWT.
Catatan: Kebijakan JWS/JWT Verifikasi melakukan pencarian key-for-keyid secara otomatis.

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

Ambil daftar kunci dan ID dari endpoint terkenal untuk penerbit tertentu. Anda dapat gunakan kebijakan Info Layanan untuk langkah ini.
Catatan: Sebaiknya simpan JWKS dalam cache untuk menghindari Info Layanan di setiap permintaan.

Di kebijakan Verifikasi JWS/JWT, tentukan lokasi JWS/JWT di <Source> dan payload 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 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 semua hal lainnya:

Jika kunci dengan ID Kunci yang cocok dengan ID Kunci (anak) yang ditegaskan di JWT tidak ditemukan di JWKS, maka kebijakan Verifikasi JWT akan menampilkan error dan tidak memvalidasi JWT.
Jika JWT masuk tidak membawa ID kunci ({i>kid<i}) di {i>header<i}, maka pemetaan keyid-to-verification-key tidak dimungkinkan.

Sebagai perancang {i>proxy<i}, Anda bertanggung jawab untuk menentukan kunci yang akan digunakan; dalam beberapa kasus, dapat berupa kunci tetap, yang di-hard code.