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 memuat ulang token akses JWT menggunakan Kebijakan OAuthV2.

Pengantar

JWT memungkinkan kebijakan OAuthV2 untuk menghasilkan, memverifikasi, dan memperbarui token akses yang sesuai dengan IETF RFC 9068, standar yang menjelaskan cara menerbitkan token akses dalam format JWT. JWT adalah yang biasanya digunakan untuk berbagi klaim atau pernyataan antaraplikasi yang terhubung. Menerbitkan token akses OAuthV2 dalam format JWT adalah suatu alternatif hingga mengeluarkan token akses buram.

Ketika dikonfigurasikan untuk JWT, kebijakan OAuthV2 menghasilkan dan menampilkan JWT berenkode Base64 yang terdiri {i>header<i}, {i>payload<i}, 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 akan menentukan parameter seperti algoritma penandatanganan dan elemen {i> payload<i} seperti subjek dan nama. Misalnya, {i>header<i} mungkin 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 di konfigurasi kebijakan, sedangkan kode lainnya akan otomatis dibuat 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}. Sebagai contoh: https://api.mycompany.com/auth/v2.	Apigee
sub	Client-ID atau ID pemilik resource (dalam kasus jenis pemberian sandi atau 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, yang direpresentasikan 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 ini dinyatakan dalam waktu epoch (dalam detik).	Apigee
iat	Waktu diterbitkan, waktu token dibuat. Nilai ini dinyatakan dalam waktu epoch (dalam detik).	Apigee
client_id	ID unik aplikasi klien.	Developer API
scope	Cakupan OAuth yang ditetapkan ke token. Lihat juga Menggunakan 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 isi token tidak dirusak.

Untuk 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 atau operasi tradisional yang membuat token string buram, penggunaan dasar kebijakan OAuthV2 adalah sama. Anda dapat menggunakan JWT token akses dengan semua jenis pemberian OAuthV2 yang didukung. Lihat juga Pengantar OAuth 2.0.

Membuat

Menggunakan GenerateJWTAccessToken dan GenerateJWTAccessTokenImplicitGrant operasi untuk menghasilkan token akses JWT dengan kebijakan OAuthV2. Operasi ini mirip dengan GenerateAccessToken dan GenerateAccessTokenImplicitGrant tradisional kebijakan operasional bisnis. Perbedaan utamanya adalah operasi JWT menampilkan token akses berformat JWT sebagai gantinya token string buram. Lihat juga Mendapatkan token OAuth 2.0.

Contoh berikut menunjukkan cara menggunakan operasi ini di kebijakan OAuthV2. Contoh tersebut menggunakan jenis pemberian client_credentials; Namun, Anda dapat gunakan salah satu jenis pemberian yang didukung dengan operasi ini.

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

Membuat token format JWT yang ditandatangani dengan algoritma HMAC

Tentukan elemen <Algorithm> dengan salah satu Algoritma HMAC (HS256/HS384/HS512). Sediakan juga <SecretKey>. Contoh berikut menunjukkan kebijakan yang dikonfigurasi untuk menghasilkan JWT yang ditandatangani dengan 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, sebaiknya bagi Proxy API untuk mengambilnya dari cakupan {i>key value map <i}(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 dalam elemen <PrivateKey>. Contoh berikut menunjukkan kebijakan 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 rahasia, sebaiknya bagi Proxy API untuk mengambilnya dari cakupan {i>key value map <i}(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. Akselerator ini secara otomatis memberikan token jenis pemberian implisit; oleh karena itu, elemen <SupportedGrantTypes> tidak diperlukan. Karena ini adalah JWT, elemen <Algorithm> diperlukan. Hal berikut contoh menunjukkan penggunaan algoritma RS256. Oleh karena itu, <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 rahasia, sebaiknya bagi Proxy API untuk mengambilnya dari peta nilai kunci (KVM) cakupan lingkungan. Lihat juga Menggunakan peta nilai kunci.

Memverifikasi

Gunakan operasi VerifyJWTAccessToken untuk memverifikasi token akses JWT dengan kebijakan OAuthV2. Operasi ini mirip dengan VerifyAccessToken operation; 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 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, sebaiknya bagi Proxy API untuk mengambilnya dari peta nilai kunci (KVM) cakupan 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 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 baik untuk menyimpan kunci publik mencakup cakupan lingkungan kumpulan properti atau cakupan lingkungan {i>key value map <i}(KVM). Lihat juga Mengakses nilai kumpulan properti dan Menggunakan peta nilai kunci.

Menyegarkan

Gunakan operasi RefreshJWTAccessToken untuk memuat ulang token akses JWT. Operasi ini mirip dengan RefreshAccessToken tradisional kebijakan operasi. Lihat juga Memuat ulang token akses.

Memperbarui token akses yang ditandatangani HMAC

Contoh kebijakan berikut menggambarkan cara mengonfigurasi kebijakan OAuthV2 untuk memuat ulang JWT yang ditandatangani dengan algoritma HMAC. <SecretKey> dan <Algorithm> elemen diperlukan dalam kasus ini.

Respons operasi pemuatan ulang serupa dengan respons token yang baru dibuat. Pembaruan menghasilkan operasi token JWT baru dengan waktu kedaluwarsa yang diperbarui, sehingga menjaga 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 menggambarkan cara mengonfigurasi kebijakan OAuthV2 untuk memuat ulang JWT yang ditandatangani dengan algoritma RSA. Lihat juga Memuat ulang 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, sebaiknya bagi Proxy API untuk mengambilnya dari peta nilai kunci (KVM) cakupan lingkungan. Lihat juga Menggunakan peta nilai kunci.

Contoh respons token

Untuk operasi buat dan muat ulang, isi respons terlihat mirip dengan yang berikut contoh. Perhatikan 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	Catatan
Algoritme	Nilai statis	Menentukan algoritma yang digunakan untuk menandatangani token.
SecretKey	Nilai yang direferensikan	Memberikan kunci rahasia yang digunakan untuk memverifikasi atau menandatangani token dengan algoritma HMAC: HS (256/384/512).
PrivateKey	Nilai yang direferensikan	Menyediakan kunci pribadi yang digunakan untuk membuat token. Gunakan hanya jika algoritma adalah algoritma RSA: RS (256/384/512).
PublicKey	Nilai yang direferensikan	Menyediakan kunci publik yang digunakan untuk memverifikasi token. Gunakan hanya jika algoritma adalah algoritma RSA: RS (256/384/512).

Elemen kebijakan tidak didukung

Elemen kebijakan OAuthV2 berikut tidak didukung dengan konfigurasi token JWT:

Elemen	Catatan
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 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 sandi dan kode autentikasi yang diberikan 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 dibuat akan tetap valid hingga masa berlakunya habis. Anda dapat mencabut token refresh yang terkait dengan token akses JWT.
• Pembuatan, verifikasi, dan pembaruan token akses harus ditangani oleh Apigee. Meskipun aplikasi eksternal atau {i>gateway<i} yang memiliki akses ke kunci publik atau kunci rahasia dapat memecahkan kode konten JWT, aplikasi eksternal tidak memiliki informasi terkait produk API yang diidentifikasi oleh klaim client_id, sehingga tidak dapat berperan dalam Otorisasi proxy API.