Menggunakan token OAuth JWT

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Fitur ini tersedia untuk Apigee dan Apigee Hybrid.

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, sebuah standar yang menjelaskan cara menerbitkan token akses dalam format JWT. JWT biasanya digunakan untuk membagikan klaim atau pernyataan antaraplikasi yang terhubung. Penerbitan token akses OAuthV2 dalam format JWT adalah alternatif untuk menerbitkan token akses tersembunyi.

Jika dikonfigurasi untuk JWT, kebijakan OAuthV2 akan membuat dan menampilkan JWT berenkode Base64 yang terdiri dari header, payload, dan tanda tangan yang dipisahkan dengan titik. Contoh:

Gambar 1: Format berseri JWT yang terdiri dari header, payload, dan tanda tangan yang dipisahkan oleh titik.

Isi elemen yang dienkode ini bergantung pada cara Anda mengonfigurasi kebijakan OAuthV2. Dalam kebijakan, Anda menentukan parameter seperti algoritma penandatanganan dan elemen payload seperti subjek dan nama. Misalnya, header dapat didekode 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 entitas. 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	ID Klien atau ID pemilik resource (dalam kasus jenis pemberian otorisasi atau sandi). Jika parameter appEndUserId diberikan dalam permintaan, nilai tersebut akan digunakan sebagai ID pemilik resource. Anda dapat mengontrol tempat nilai ini ditetapkan menggunakan elemen <AppEndUser> dari kebijakan OAuthV2.	Developer API
jti	ID unik, yang ditampilkan sebagai string acak yang didukung UUID untuk mengidentifikasi token secara unik.	Apigee
exp	Waktu habis masa berlaku, dengan kata lain waktu setelah token harus dianggap tidak valid. Nilai dinyatakan dalam waktu epoch (dalam detik).	Apigee
iat	Waktu penerbitan, waktu saat token dibuat. Nilai dinyatakan dalam waktu epoch (dalam detik).	Apigee
client_id	ID unik aplikasi klien.	Developer API
scope	Cakupan OAuth yang ditetapkan ke token. Lihat juga Bekerja dengan cakupan OAuth.	Developer API

Tanda Tangan

Tanda tangan dibuat menggunakan header, payload, kunci rahasia/pribadi yang dienkode, dan algoritma. Tanda tangan digunakan untuk memastikan bahwa konten token tidak dirusak.

Untuk mengetahui informasi selengkapnya tentang token akses OAuth 2.0 format JWT, lihat IETF RFC 9068: Profil Token Web JSON (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 atau operasi tradisional yang membuat token string buram, penggunaan dasar kebijakan OAuthV2 tetap sama. Anda dapat menggunakan token akses JWT dengan semua jenis pemberian OAuthV2 yang didukung. Lihat juga Pengantar OAuth 2.0.

Membuat

Gunakan operasi GenerateJWTAccessToken dan GenerateJWTAccessTokenImplicitGrant untuk membuat token akses JWT dengan kebijakan OAuthV2. Operasi ini mirip dengan operasi GenerateAccessToken dan GenerateAccessTokenImplicitGrant kebijakan tradisional. 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 menggunakan jenis pemberian client_credentials; namun, Anda dapat menggunakan jenis pemberian yang didukung dengan operasi ini.

Catatan: Selain token akses JWT, respons kebijakan juga menyertakan token refresh buram.

Membuat token format JWT yang ditandatangani dengan algoritma HMAC

Tentukan elemen <Algorithm> dengan salah satu algoritma HMAC (HS256/HS384/HS512). Berikan juga <SecretKey>. Contoh berikut menunjukkan kebijakan yang dikonfigurasi untuk membuat JWT yang ditandatangani dengan algoritma 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>

Kunci rahasia adalah rahasia. Untuk melindungi rahasia, praktik terbaiknya adalah agar Proxy API mengambilnya dari peta nilai kunci (KVM) yang tercakup dalam lingkungan. Lihat juga Menggunakan peta nilai kunci.

Membuat token berformat JWT yang ditandatangani dengan algoritma RSA

Tentukan salah satu algoritma RSA (salah satu dari RS256/RS384/RS512) dalam elemen <Algorithm>, dan berikan kunci pribadi dalam elemen <PrivateKey>. Contoh berikut menunjukkan kebijakan yang dikonfigurasi untuk membuat 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>

Kunci pribadi RSA adalah rahasia. Untuk melindungi rahasia, praktik terbaiknya adalah agar Proxy API mengambilnya dari peta nilai kunci (KVM) yang tercakup dalam lingkungan. Lihat juga Menggunakan peta nilai kunci.

Membuat token format JWT dengan jenis pemberian implisit

Operasi GenerateJWTAccessTokenImplicitGrant menghasilkan token akses JWT menggunakan jenis pemberian izin implisit. Token tersebut otomatis diberi jenis pemberian implisit; oleh karena itu, elemen <SupportedGrantTypes> tidak diperlukan. Karena berupa JWT, elemen <Algorithm> diperlukan. Contoh berikut menunjukkan penggunaan algoritma RS256. Oleh karena itu, elemen <PrivateKey> wajib diisi. Lihat juga Menggunakan jenis pemberian implicit.

<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>

Kunci pribadi RSA adalah rahasia. Untuk melindungi rahasia, praktik terbaiknya adalah API Proxy mengambilnya dari peta nilai kunci (KVM) yang tercakup dalam lingkungan. Lihat juga Menggunakan peta nilai kunci.

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>

Kunci rahasia adalah rahasia. Untuk melindungi rahasia, praktik terbaiknya adalah agar Proxy API mengambilnya dari peta nilai kunci (KVM) yang tercakup dalam lingkungan. Lihat juga Menggunakan peta nilai kunci.

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>

Kunci publik bukanlah rahasia. Opsi yang baik untuk menyimpan kunci publik mencakup set properti yang tercakup dalam lingkungan atau peta nilai kunci (KVM) yang tercakup dalam lingkungan. Lihat juga Mengakses nilai set properti dan Menggunakan peta nilai kunci.

Menyegarkan

Gunakan RefreshJWTAccessToken operasi untuk memperbarui token akses JWT. Operasi ini mirip dengan operasi RefreshAccessToken tradisional kebijakan. Lihat juga Memperbarui token akses.

Memperbarui token akses yang ditandatangani HMAC

Contoh kebijakan berikut menggambarkan cara mengonfigurasi kebijakan OAuthV2 untuk memperbarui token JWT yang ditandatangani dengan algoritma HMAC. Elemen <SecretKey> dan <Algorithm> wajib diisi dalam kasus ini.

Respons operasi refresh mirip dengan respons token yang baru dibuat. Operasi refresh membuat token JWT baru dengan waktu habis masa berlaku yang diperbarui, dan mempertahankan klaim lainnya.

<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>

Memperbarui token akses JWT yang ditandatangani RSA

Contoh kebijakan berikut menggambarkan 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>

Kunci pribadi RSA adalah rahasia. Untuk melindungi rahasia, praktik terbaiknya adalah API Proxy mengambilnya dari peta nilai kunci (KVM) yang tercakup dalam lingkungan. Lihat juga Menggunakan peta nilai kunci.

Contoh respons token

Untuk operasi pembuatan dan pengambilan, isi respons akan terlihat mirip dengan contoh berikut. Perhatikan bahwa access_token ditampilkan sebagai JWT yang diserialisasi, dan token refresh adalah token buram tradisional.

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImF0K0pXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "Bearer",
  "developer.email": "[e-mail]",
  "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	Catatan
Algoritme	Nilai statis	Menentukan algoritma yang digunakan untuk menandatangani token.
SecretKey	Nilai yang dirujuk	Memberikan 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 membuat token. Gunakan hanya jika algoritma adalah algoritma RSA: RS (256/384/512).
PublicKey	Nilai yang dirujuk	Menyediakan kunci publik yang digunakan untuk memverifikasi token. Gunakan hanya jika algoritma adalah algoritma RSA: RS (256/384/512).

Elemen kebijakan yang tidak didukung

Elemen kebijakan OAuthV2 berikut tidak didukung dengan konfigurasi token JWT:

Elemen	Catatan
ExternalAuthorization	Saat membuat token akses JWT, kebijakan OAuthV2 akan memvalidasi ID dan Rahasia klien.
ExternalAccessToken	Saat membuat token akses JWT, token akan ditandatangani oleh Apigee dan klaim akan diberikan oleh Apigee baik secara default maupun melalui konfigurasi kebijakan. Kebijakan ini mendukung ExternalRefreshToken, yang dapat membantu kasus penggunaan migrasi.
RFCCompliantRequestResponse	Pembuatan dan pembaruan token akses JWT secara default sesuai dengan RFC.

Catatan penggunaan

• JWT terenkripsi tidak didukung.
• Selain token akses JWT, respons kebijakan juga menyertakan token refresh buram untuk jenis pemberian yang mendukung token refresh. Hanya jenis pemberian kode otorisasi dan sandi 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 masa berlakunya berakhir. Anda dapat mencabut token refresh yang terkait dengan token akses JWT.
• Pembuatan, verifikasi, dan pembaruan token akses harus ditangani oleh Apigee. Meskipun aplikasi atau gateway eksternal yang memiliki akses ke kunci publik atau rahasia dapat mendekode isi JWT, aplikasi eksternal tidak memiliki informasi tentang produk API yang diidentifikasi oleh klaim client_id, dan oleh karena itu tidak dapat berperan dalam otorisasi proxy API.