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, standar yang menjelaskan cara menerbitkan token akses dalam format JWT. JWT biasanya digunakan untuk membagikan klaim atau pernyataan antara aplikasi yang terhubung. Mengeluarkan token akses OAuthV2 dalam format JWT adalah alternatif untuk mengeluarkan token akses buram.

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

Gambar 1: Format serialisasi 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, Anda menentukan parameter seperti algoritma penandatanganan dan elemen payload seperti subjek dan nama. Misalnya, header mungkin didekode sebagai {"alg":"HS256","typ":"at+JWT"}, dan payload mungkin 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	Client ID atau ID pemilik resource (dalam kasus jenis pemberian sandi atau otorisasi). Jika parameter appEndUserId diberikan 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. Nilainya dinyatakan dalam waktu epoch (dalam detik).	Apigee
iat	Waktu diterbitkan, waktu token dibuat. Nilainya 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, dan algoritma yang dienkode. Tanda tangan digunakan untuk memastikan bahwa konten token belum dirusak.

Untuk informasi selengkapnya tentang token akses OAuth 2.0 berformat 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 salah satu jenis pemberian yang didukung dengan operasi ini.

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

Membuat token berformat 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 secret, praktik terbaiknya adalah Proxy API mengambilnya dari peta nilai kunci (KVM) cakupan 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) di elemen <Algorithm>, dan berikan kunci pribadi di 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 bersifat rahasia. Untuk melindungi secret, praktik terbaiknya adalah Proxy API mengambilnya dari peta nilai kunci (KVM) cakupan lingkungan. Lihat juga Menggunakan peta nilai kunci.

Membuat token berformat JWT dengan jenis pemberian implisit

Operasi GenerateJWTAccessTokenImplicitGrant menghasilkan token akses JWT menggunakan jenis pemberian izin implisit. Tindakan ini akan otomatis memberikan jenis pemberian implisit ke token; oleh karena itu, elemen <SupportedGrantTypes> tidak diperlukan. Karena merupakan 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 bersifat rahasia. Untuk melindungi secret, praktik terbaiknya adalah Proxy API 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 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 (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 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 cakupan lingkungan atau peta nilai kunci (KVM) cakupan lingkungan. 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 operasi RefreshAccessToken kebijakan tradisional. Lihat juga Memuat ulang token akses.

Memperbarui token akses yang ditandatangani HMAC

Contoh kebijakan berikut mengilustrasikan cara mengonfigurasi kebijakan OAuthV2 untuk memuat ulang token JWT yang ditandatangani dengan algoritma HMAC. Dalam hal ini, elemen <SecretKey> dan <Algorithm> diperlukan.

Respons operasi refresh mirip 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>

Memperbarui token akses JWT yang ditandatangani RSA

Contoh kebijakan berikut mengilustrasikan cara mengonfigurasi kebijakan OAuthV2 untuk memuat ulang token 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 bersifat rahasia. Untuk melindungi secret, praktik terbaiknya adalah Proxy API mengambilnya dari peta nilai kunci (KVM) cakupan lingkungan. Lihat juga Menggunakan peta nilai kunci.

Contoh respons token

Untuk operasi pembuatan dan pembaruan, isi respons terlihat mirip dengan contoh berikut. Perhatikan bahwa access_token direpresentasikan 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	Memberikan kunci pribadi yang digunakan untuk membuat token. Hanya gunakan jika algoritma adalah algoritma RSA: RS (256/384/512).
PublicKey	Nilai yang dirujuk	Memberikan kunci publik yang digunakan untuk memverifikasi token. Hanya gunakan 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 client ID dan Secret.
ExternalAccessToken	Saat membuat token akses JWT, token akan ditandatangani oleh Apigee dan pernyataan akan disediakan 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 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 Authorization 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 konten JWT, aplikasi eksternal tidak memiliki informasi tentang produk API yang diidentifikasi oleh klaim client_id, sehingga tidak dapat berperan dalam otorisasi proxy API.