Halaman ini berlaku untuk Apigee dan Apigee Hybrid.
Baca dokumentasi Apigee Edge.
Topik ini menjelaskan cara membuat, memverifikasi, dan memperbarui token akses JWT menggunakan kebijakan OAuthV2.
Pengantar
Operasi JWT memungkinkan kebijakan OAuthV2 membuat, memverifikasi, dan memperbarui token akses yang sesuai dengan IETF RFC 9068, standar yang menjelaskan cara mengeluarkan token akses dalam format JWT. JWT biasanya digunakan untuk membagikan klaim atau pernyataan antara aplikasi yang terhubung. Menerbitkan token akses OAuthV2 dalam format JWT adalah alternatif untuk menerbitkan token akses buram.
Saat dikonfigurasi untuk JWT, kebijakan OAuthV2 menghasilkan dan menampilkan JWT berenkode Base64 yang terdiri dari header, payload, dan tanda tangan yang dipisahkan oleh titik. Contoh:
Konten yang dienkode dari elemen ini
bergantung pada cara Anda mengonfigurasi kebijakan OAuthV2. Dalam kebijakan tersebut, Anda menetapkan parameter seperti algoritma penandatanganan dan elemen payload seperti subjek dan nama. Misalnya, header
dapat mendekode sebagai {"alg":"HS256","typ":"at+JWT"}
, dan
payload dapat didekode sebagai: {"sub":"ABC1234567","iat":1516239022}
.
Header
Header menentukan klaim typ
(selalu "at+JWT
) dan klaim alg
, yang menunjukkan algoritma yang digunakan untuk menandatangani JWT. Apigee mendukung algoritma RSA dan HMAC: RS(256.384.512) dan HS(256.384.512).
Payload
Payload terdiri dari klaim tentang entity. Beberapa klaim harus diberikan dalam konfigurasi kebijakan, sementara klaim lainnya dibuat secara otomatis oleh runtime Apigee. Kebijakan ini mendukung klaim berikut:
Klaim | Deskripsi | Disediakan oleh |
---|---|---|
iss |
Penerbit token. Nilai ini ditetapkan sebagai berikut: (http|https)://{domain-name-for-proxy}/{proxy-basePath} . Contoh: https://api.mycompany.com/auth/v2 . |
Apigee |
sub |
Client-ID atau ID pemilik resource (untuk
jenis sandi atau pemberian otorisasi). Jika parameter appEndUserId
disediakan dalam permintaan, nilai tersebut akan digunakan sebagai ID pemilik resource. Anda dapat mengontrol tempat nilai ini ditetapkan menggunakan elemen <AppEndUser> kebijakan OAuthV2. |
Developer API |
jti |
ID unik, direpresentasikan sebagai string acak yang didukung UUID untuk mengidentifikasi token secara unik. | Apigee |
exp |
Dengan kata lain, waktu habis masa berlaku token harus dianggap tidak valid. Nilai ini dinyatakan dalam waktu epoch (dalam detik). | Apigee |
iat |
Waktu penerbitan, saat token dibuat. Nilai ini dinyatakan dalam waktu epoch (dalam detik). | Apigee |
client_id |
ID unik aplikasi klien. | Developer API |
scope |
Cakupan OAuth yang ditetapkan untuk token. Lihat juga Bekerja dengan cakupan OAuth. | Developer API |
Tanda Tangan
Tanda tangan tersebut dihasilkan menggunakan header, payload, kunci rahasia/pribadi yang dienkode, dan algoritma. Tanda tangan digunakan untuk memastikan bahwa isi token belum dirusak.
Untuk mengetahui informasi selengkapnya tentang token akses OAuth 2.0 format JWT, lihat IETF RFC 9068: Profil JSON Web Token (JWT) untuk Token Akses OAuth 2.0.
Prasyarat
Dokumen ini mengasumsikan bahwa Anda memahami cara membuat dan memverifikasi token akses OAuthV2 menggunakan kebijakan OAuthV2. Baik Anda menggunakan operasi JWT maupun operasi tradisional yang membuat token string buram, penggunaan dasar kebijakan OAuthV2 sama. Anda dapat menggunakan token akses JWT dengan semua pemberian jenis OAuthV2 yang didukung. Lihat juga Pengantar OAuth 2.0.
Membuat
Gunakan operations GenerateJWTAccessToken
dan GenerateJWTAccessTokenImplicitGrant
untuk membuat token akses JWT dengan
kebijakan OAuthV2. Operasi ini mirip dengan operasi GenerateAccessToken
dan GenerateAccessTokenImplicitGrant
tradisional kebijakan. Perbedaan utamanya adalah operasi JWT menampilkan token akses berformat JWT,
bukan token string buram. Lihat juga Mendapatkan token OAuth 2.0.
Contoh berikut menunjukkan cara menggunakan operasi ini dalam kebijakan OAuthV2. Contoh ini menggunakan jenis pemberian client_credentials
; tetapi, Anda dapat menggunakan salah satu jenis hibah yang didukung dengan operasi ini.
Menghasilkan token format JWT yang ditandatangani dengan algoritma HMAC
Tentukan elemen <Algorithm>
dengan salah satu algoritma HMAC (HS256/HS384/HS512). Selain itu, sediakan <SecretKey>
.
Contoh berikut menunjukkan kebijakan yang dikonfigurasi untuk menghasilkan JWT yang ditandatangani dengan algoritme HS512, menggunakan kunci rahasia yang ditentukan.
<OAuthV2 name="generate-policy"> <Operation>GenerateJWTAccessToken</Operation> <SupportedGrantTypes> <GrantType>client_credentials</GrantType> </SupportedGrantTypes> <GenerateResponse enabled="true"/> <Algorithm>HS512</Algorithm> <SecretKey> <Value ref="private.mysecretkey"/> </SecretKey> <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn> </OAuthV2>
Membuat token format JWT yang ditandatangani dengan algoritma RSA
Tentukan salah satu algoritma RSA (salah satu dari RS256/RS384/RS512) di elemen <Algorithm>
, dan berikan kunci pribadi di elemen <PrivateKey>
. Contoh berikut menunjukkan kebijakan yang dikonfigurasi untuk menghasilkan JWT yang ditandatangani dengan kunci pribadi RSA menggunakan algoritma RS256.
<OAuthV2 name="generate-policy"> <Operation>GenerateJWTAccessToken</Operation> <SupportedGrantTypes> <GrantType>client_credentials</GrantType> </SupportedGrantTypes> <GenerateResponse enabled="true"/> <Algorithm>RS256</Algorithm> <PrivateKey> <Value ref="private.rsa-privatekey-1"/> </PrivateKey> <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn> </OAuthV2>
Menghasilkan token format JWT dengan jenis pemberian implisit
Operasi GenerateJWTAccessTokenImplicitGrant
menghasilkan token akses JWT menggunakan jenis pemberian implisit. Atribut ini otomatis memberikan token jenis pemberian implisit;
oleh karena itu, elemen <SupportedGrantTypes>
tidak diperlukan.
Karena ini adalah JWT, elemen <Algorithm>
diperlukan. Contoh berikut menunjukkan penggunaan algoritma RS256. Oleh karena itu, elemen <PrivateKey>
diperlukan. Lihat juga
Menggunakan jenis pemberian implisit.
<OAuthV2 name="generate-policy"> <Operation>GenerateJWTAccessTokenImplicitGrant</Operation> <GenerateResponse enabled="true"/> <Algorithm>RS256</Algorithm> <PrivateKey> <Value ref="private.rsa-privatekey-1"/> </PrivateKey> <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn> </OAuthV2>
Memverifikasi
Gunakan operasi VerifyJWTAccessToken
untuk memverifikasi token akses JWT dengan
kebijakan OAuthV2. Operasi ini mirip dengan operasi VerifyAccessToken
; perbedaannya adalah VerifyJWTAccessToken
berlaku untuk token dalam format JWT,
sedangkan VerifyAccessToken
berlaku untuk token buram.
Memverifikasi token akses JWT yang ditandatangani dengan algoritma HMAC
Contoh berikut menunjukkan cara mengonfigurasi kebijakan OAuthV2 untuk memverifikasi token JWT yang ditandatangani dengan algoritma HS512. Saat menggunakan operasi VerifyJWTAccessToken
dengan algoritma HMAC, konfigurasi kebijakan harus menggunakan elemen <SecretKey>
untuk menentukan kunci rahasia yang digunakan untuk menandatangani JWT.
<OAuthV2 name="OAuthV2-verify-jwt"> <Operation>VerifyJWTAccessToken</Operation> <Algorithm>HS512</Algorithm> <SecretKey> <Value ref="private.mysecretkey"/> </SecretKey> </OAuthV2>
Memverifikasi token akses JWT yang ditandatangani dengan algoritma RSA
Contoh berikut menunjukkan cara mengonfigurasi kebijakan OAuthV2 untuk memverifikasi token JWT yang ditandatangani dengan algoritma RS512. Saat menggunakan operasi VerifyJWTAccessToken
dengan algoritma RSA, konfigurasi kebijakan harus menggunakan elemen <PublicKey>
untuk menentukan kunci publik yang sesuai dengan kunci pribadi yang digunakan untuk menandatangani JWT.
<OAuthV2 name="OAuthV2-verify-jwt"> <Operation>VerifyJWTAccessToken</Operation> <Algorithm>RS512</Algorithm> <PublicKey> <Value ref="propertyset.non-secrets.rsa-publickey-1"/> </PublicKey> </OAuthV2>
Memuat ulang
Gunakan operasi RefreshJWTAccessToken
untuk memperbarui token akses JWT.
Operasi ini mirip dengan operasi RefreshAccessToken
tradisional kebijakan. Lihat juga Memperbarui token akses.
Memuat ulang token akses yang ditandatangani HMAC
Contoh kebijakan berikut mengilustrasikan cara mengonfigurasi kebijakan OAuthV2 untuk memperbarui token JWT yang ditandatangani dengan algoritma HMAC. Elemen <SecretKey>
dan <Algorithm>
diperlukan dalam kasus ini.
Respons operasi refresh serupa dengan respons token yang baru dibuat. Operasi refresh menghasilkan token JWT baru dengan waktu habis masa berlaku yang diperbarui, sehingga klaim lainnya tetap sama.
<OAuthV2 name="RefreshAccessToken"> <Operation>RefreshJWTAccessToken</Operation> <GenerateResponse enabled="true"/> <Algorithm>HS512</Algorithm> <SecretKey> <Value ref="private.mysecretkey"/> </SecretKey> <RefreshTokenExpiresIn ref="kvm.oauth.expires_in">3600000</RefreshTokenExpiresIn> </OAuthV2>
Memuat ulang token akses JWT yang ditandatangani RSA
Contoh kebijakan berikut mengilustrasikan cara mengonfigurasi kebijakan OAuthV2 untuk memperbarui token JWT yang ditandatangani dengan algoritma RSA. Lihat juga Memperbarui token akses.
<OAuthV2 name="RefreshAccessToken"> <Operation>RefreshJWTAccessToken</Operation> <GenerateResponse enabled="true"/> <Algorithm>RS256</Algorithm> <PrivateKey> <Value ref="private.rsa-privatekey-1"/> </PrivateKey> <RefreshTokenExpiresIn ref="kvm.oauth.expires_in">3600000</RefreshTokenExpiresIn> </OAuthV2>
Contoh respons token
Untuk operasi pembuatan dan refresh, isi respons terlihat mirip dengan contoh
berikut. Perlu diketahui bahwa access_token
direpresentasikan sebagai JWT serial, dan
token refresh adalah token buram tradisional.
{ "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImF0K0pXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", "token_type": "Bearer", "developer.email": "developer@example.org", "token_type": "Bearer", "issued_at": "1658352381404", "expires_in": 1799, "refresh_token": "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ", "refresh_token_issued_at": "1658352381404", "refresh_token_expires_in": 86399, "refresh_token_status": "Approved", "refresh_count": "0", "organization_name": "cerruti", "api_product_list_json": [ "TestingProduct" ] }
Ringkasan elemen kebijakan yang diperlukan
Tabel berikut menjelaskan elemen khusus JWT yang digunakan dalam contoh sebelumnya:
Elemen | Jenis | Notes |
---|---|---|
Algoritma | Nilai statis | Menentukan algoritma yang digunakan untuk menandatangani token. |
SecretKey | Nilai yang dirujuk | Menyediakan kunci rahasia yang digunakan untuk memverifikasi atau menandatangani token dengan algoritma HMAC: HS (256/384/512). |
PrivateKey | Nilai yang dirujuk | Menyediakan kunci pribadi yang digunakan untuk menghasilkan token. Gunakan hanya jika algoritma yang digunakan adalah algoritma RSA: RS (256/384/512). |
PublicKey | Nilai yang dirujuk | Menyediakan kunci publik yang digunakan untuk memverifikasi token. Gunakan hanya jika algoritma yang digunakan adalah algoritma RSA: RS (256/384/512). |
Elemen kebijakan yang tidak didukung
Elemen kebijakan OAuthV2 berikut tidak didukung dengan konfigurasi token JWT:
Elemen | Notes |
---|---|
ExternalAuthorization | Saat membuat token akses JWT, kebijakan OAuthV2 akan memvalidasi client ID dan Secret. |
ExternalAccessToken | Saat membuat token akses JWT, token tersebut akan ditandatangani oleh Apigee dan
klaim akan diberikan oleh Apigee secara default atau melalui konfigurasi kebijakan.
Kebijakan ini mendukung ExternalRefreshToken , yang dapat membantu dalam
kasus penggunaan migrasi.
|
RFCCompliantRequestResponse | Pembuatan dan refresh token akses JWT mematuhi RFC secara default. |
Catatan penggunaan
- JWT terenkripsi tidak didukung.
- Selain token akses JWT, respons kebijakan juga menyertakan token refresh buram untuk jenis pemberian jika token refresh didukung. Hanya jenis pemberian sandi dan kode autentikasi yang mendukung token refresh.
- Sertakan header Otorisasi dalam permintaan yang dikirim ke proxy yang berisi kebijakan OAuthV2.
- Anda tidak dapat mencabut token akses JWT. Token JWT yang dihasilkan akan tetap valid hingga kedaluwarsa. Anda dapat mencabut token refresh yang terkait dengan token akses JWT.
- Pembuatan, verifikasi, dan pemuatan ulang token akses harus ditangani oleh Apigee. Meskipun
aplikasi eksternal atau gateway yang memiliki akses ke kunci publik atau rahasia dapat mendekode konten JWT, aplikasi eksternal tidak memiliki informasi tentang produk API
yang diidentifikasi oleh klaim
client_id
, sehingga tidak dapat berperan dalam otorisasi proxy API.