Mencabut dan menyetujui token

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Memahami pencabutan token

Pada beberapa kasus, aplikasi diwajibkan untuk mencabut atau membatalkan validasi token individual secara eksplisit. Kasus yang umum terjadi adalah saat pengguna logout dari aplikasi berkemampuan OAuth. Token yang dicabut tidak akan berguna lagi untuk otorisasi. Setelah token dicabut, jika aplikasi memberikan token tersebut ke proxy API, kebijakan OAuthV2 dengan Operasi VerifyAccessToken akan menolak token tersebut.

Standar untuk pencabutan token ditetapkan oleh IETF RFC 7009, spesifikasi OAuth 2.0 Token Revocation.

Sebagai alternatif untuk mencabut token tertentu, Anda dapat mencabut client ID, atau seluruh aplikasi developer. Lihat Mencabut dan menyetujui kunci aplikasi developer untuk mengetahui detailnya. Dibandingkan dengan mencabut token individual, mencabut client ID atau aplikasi developer memiliki dampak yang lebih luas. Saat Anda mencabut client ID atau aplikasi developer, Apigee akan menolak semua token yang terkait dengan client ID atau aplikasi developer tersebut, dan tidak akan lagi mengeluarkan token baru untuk client ID atau aplikasi developer tersebut.

Setelah mencabut token, baik token akses maupun token refresh, Anda dapat secara opsional menyetujui kembali token tersebut kapan saja sebelum masa berlakunya habis. Setelah menyetujui ulang token, kebijakan Apigee OAuthV2 akan kembali menerima token tersebut untuk otorisasi, hingga masa berlaku token berakhir. Akhir masa berlaku token tidak bergantung pada status token yang disetujui atau dicabut. Kebijakan OAuthV2 Apigee dengan Operasi ValidateAccessToken akan menerima token akses hanya jika token tersebut disetujui (atau tidak dicabut) dan masa berlakunya belum habis. Demikian juga, kebijakan OAuthV2 Apigee dengan Operasi RefreshAccessToken akan menerima token refresh hanya jika token tersebut disetujui (atau tidak dicabut) dan masa berlakunya belum habis.

Ada dua kebijakan yang dapat Anda gunakan untuk mencabut token:

kebijakan OAuthV2 menggunakan Operation dari InvalidateToken.
kebijakan CabutOAuthV2.

Kebijakan OAuthV2 memiliki kemampuan untuk mencabut, dan juga mengaktifkan kembali, token satu per satu. Kebijakan CabutOAuthV2 lebih fleksibel karena dapat mencabut beberapa token sekaligus, berdasarkan ID Aplikasi, atau ID Pengguna Akhir. Bagian selanjutnya dari halaman ini menjelaskan penggunaan kebijakan OAuthV2 untuk mencabut token atau mengaktifkan kembali token yang sebelumnya dicabut.

Mencabut token akses dan menyegarkan

Berikut adalah contoh konfigurasi untuk kebijakan OAuthV2 yang menggunakan Operasi InvalidateToken. Dalam hal ini, karena atribut cascade pada elemen Token bernilai true, Apigee akan mencabut token akses dan token refresh yang terkait.

  <OAuthV2 name="InvalidateToken">
    <Operation>InvalidateToken</Operation>
    <Tokens>
      <Token type="accesstoken" cascade="true">request.queryparam.token</Token>
    </Tokens>
  </OAuthV2>

Untuk informasi selengkapnya tentang cara kerja flag menurun, lihat bagian di bawah pada Atribut untuk elemen Token.

Elemen <Tokens>/<Token>

Mengidentifikasi variabel flow yang menentukan token yang akan dicabut. Jika developer diharapkan mengirimkan permintaan pencabutan menggunakan parameter kueri bernama access_token, misalnya, variabel alur yang benar adalah: request.queryparam.access_token. Misalnya, untuk meminta token di header HTTP, tetapkan nilai ini ke request.header.access_token.

Token akses yang ada dalam format JWT tidak dapat dicabut. Selain itu, Anda tidak dapat menggunakan kebijakan OAuthV2 untuk mencabut token refresh yang terkait dengan token akses yang memiliki format JWT. Error runtime akan terjadi jika variabel konteks yang ditentukan di sini merujuk pada token akses JWT, atau token refresh yang dikaitkan dengan token akses JWT. Anda dapat mencabut token refresh yang terkait dengan token akses JWT menggunakan kebijakan CabutOAuthV2.

Atribut

type (wajib, string): Jenis token yang diidentifikasi oleh variabel yang ditentukan. Nilai yang didukung adalah accesstoken dan refreshtoken:
- Untuk mencabut token akses, tentukan jenis accesstoken.
- Untuk mencabut token akses dan refresh, tentukan jenis refreshtoken. Saat melihat jenis refreshtoken, Apigee menganggap token tersebut adalah token refresh. Jika ditemukan, token refresh akan dicabut. Jika token refresh tersebut tidak ditemukan, Apigee akan memeriksa apakah token tersebut merupakan token akses atau bukan. Jika token akses ada, token tersebut akan dicabut.
  
  Catatan: Jika Anda meneruskan token yang sudah tidak valid ke kebijakan InvalidateToken, kebijakan tersebut tidak akan menampilkan error, meskipun Anda mungkin mengharapkannya demikian. Operasi tersebut tidak berpengaruh.
cascade (opsional, boolean, default: true) Penggunaan utama atribut ini adalah untuk mencabut token refresh tanpa mencabut token akses terkaitnya. Pertimbangkan kasus berikut:
- Cabut token refresh saja dan jangan cabut token akses terkaitnya. Untuk melakukannya, tetapkan jenis <Token> ke refreshtoken dan tetapkan cascade ke false.
- Cabut token akses dan token refresh. Untuk melakukannya, tetapkan jenis <Token> ke accesstoken. Nilai cascade dapat berupa true (default) atau false. Jika Anda menetapkannya ke true, token akses dan token refresh akan dicabut. Jika Anda menetapkannya ke false, token akses akan dicabut, dan token refresh tidak dapat digunakan. Lihat Catatan di bawah untuk penjelasan lebih lanjut.
- Mencabut token akses dan tidak mencabut token refresh yang terkait. Tidak didukung. Lihat Catatan di bawah untuk penjelasan lebih lanjut.

Catatan: Untuk alasan keamanan, jika Anda mencabut token akses, token refresh yang terkait juga akan dicabut. Oleh karena itu, Anda tidak dapat menggunakan atribut cascade untuk mencabut token akses saja. Misalnya, jika Anda menetapkan jenis <Token> ke accesstoken, dan menetapkan cascade=false, token akses akan dicabut (seperti yang diharapkan); tetapi, token refresh yang terkait tidak dapat digunakan. Token ini tidak dapat digunakan untuk memperbarui token akses yang dicabut. Kasus penggunaan utama untuk atribut menurun adalah ketika Anda hanya ingin mencabut token refresh. Dalam hal ini, tetapkan jenis <Token> ke refreshtoken, dan tetapkan cascade=false. Token refresh akan dicabut, tetapi token akses yang terkait akan tetap valid (hingga masa berlakunya habis atau dicabut). Untuk informasi selengkapnya, lihat Diskusi forum komunitas ini.

Menyetujui akses dan token refresh

Gunakan operasi ValidasiToken untuk "menyetujui kembali" token yang dicabut. Artinya, jika Anda menerapkan operasi ini, status token akses atau refresh yang ditargetkan akan diubah dari 'dicabut' menjadi 'disetujui'. Anda dapat memvalidasi setiap token yang dicabut yang belum habis masa berlakunya.

<OAuthV2 name="ValidateToken">
  <Operation>ValidateToken</Operation>
  <Tokens>
    <Token type="refreshtoken" cascade="true">flow.variable</Token>
  </Tokens>
</OAuthV2>

Elemen <Tokens>/<Token>

Mengidentifikasi variabel flow yang menentukan token yang akan divalidasi. Jika developer diharapkan untuk mengirimkan permintaan validasi menggunakan parameter kueri bernama access_token, misalnya, variabel flow yang benar adalah request.queryparam.access_token. Misalnya, untuk meminta token di header HTTP, tetapkan nilai ini ke request.header.access_token.

Atribut

type (wajib, string) Jenis token yang diidentifikasi oleh variabel yang ditentukan. Nilai yang didukung adalah accesstoken dan refreshtoken.
cascade (opsional, boolean): Secara default, opsi ini ditetapkan ke true, dan menyebabkan validasi disebarkan ke token yang terkait. Jadi, jika diterapkan ke token refresh, token akses terkaitnya juga akan divalidasi. Jika diterapkan pada token akses, token refresh yang terkait juga akan divalidasi. Jika Anda menetapkannya ke false, hanya token akses atau token refresh yang ditentukan yang akan divalidasi.