Menggunakan token OAuth JWT

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Baca dokumentasi Apigee Edge.

Fitur ini tersedia untuk Apigee Hybrid 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, 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:

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

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.

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

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>

Kunci rahasia adalah rahasia. Untuk melindungi secret, praktik terbaiknya adalah bagi Proxy API untuk mengambilnya dari peta nilai kunci cakupan lingkungan (KVM). Lihat juga Menggunakan peta nilai kunci.

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>

Kunci pribadi RSA adalah rahasia. Untuk melindungi secret, praktik terbaiknya adalah bagi Proxy API untuk mengambilnya dari peta nilai kunci cakupan lingkungan (KVM). Lihat juga Menggunakan peta nilai kunci.

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>

Kunci pribadi RSA adalah rahasia. Untuk melindungi secret, praktik terbaiknya adalah Proxy API mengambilnya dari peta nilai kunci cakupan lingkungan (KVM). 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 secret, praktik terbaiknya adalah Proxy API mengambilnya dari peta nilai kunci cakupan lingkungan (KVM). 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 bukan rahasia. Opsi yang tepat untuk menyimpan kunci publik mencakup kumpulan properti cakupan lingkungan atau peta nilai kunci cakupan lingkungan (KVM). Lihat juga Mengakses nilai kumpulan properti dan Menggunakan peta nilai kunci.

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>

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

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": "[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	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.