Jenis token

Halaman ini membahas jenis-jenis token yang digunakan untuk autentikasi ke Google API, layanan Google Cloud, dan layanan yang dibuat pelanggan dan dihosting di Google Cloud.

Jika Anda mengakses Google API dan layanan Google dengan menggunakan library klien, Anda dapat menyiapkan Kredensial Default Aplikasi, dan library klien akan menangani token untuk Anda. Ini adalah pendekatan yang direkomendasikan.

Pengertian token

Untuk autentikasi dan otorisasi, token adalah objek digital yang berisi informasi tentang identitas akun utama yang membuat permintaan dan jenis akses diberi otorisasi. Pada sebagian besar alur autentikasi, aplikasi—atau library yang digunakan oleh aplikasi—menukarkan kredensial dengan token, yang menentukan resource mana yang boleh diakses oleh aplikasi.

Jenis token

Berbagai jenis token digunakan di lingkungan yang berbeda. Jenis token berikut dijelaskan di halaman ini:

Halaman ini tidak membahas kunci API atau Client ID, yang dianggap sebagai kredensial.

Token akses

Token akses adalah token tersembunyi yang sesuai dengan framework OAuth 2.0. Token tersebut berisi informasi otorisasi, tetapi bukan informasi identitas. Kredensial digunakan untuk melakukan autentikasi dan memberikan informasi otorisasi ke Google API.

Jika menggunakan Kredensial Default Aplikasi (ADC) dan Library Klien Cloud atau Library Klien Google API, Anda tidak perlu mengelola token akses; library secara otomatis mengambil kredensial, menukarnya dengan token akses, dan memuat ulang token akses sesuai kebutuhan.

Konten token akses

Token akses adalah token tersembunyi, yang berarti bahwa token tersebut berada dalam format kepemilikan; aplikasi tidak dapat memeriksanya. Anda bisa mendapatkan informasi dari token akses yang valid (tidak habis masa berlakunya atau dicabut) menggunakan endpoint tokeninfo Google OAuth 2.0.

Ganti ACCESS_TOKEN dengan token akses yang valid dan belum habis masa berlakunya.

curl "https://oauth2.googleapis.com/tokeninfo?access_token=ACCESS_TOKEN"

Perintah ini menampilkan sesuatu yang mirip dengan contoh berikut:

{
  "azp": "32553540559.apps.googleusercontent.com",
  "aud": "32553540559.apps.googleusercontent.com",
  "sub": "111260650121245072906",
  "scope": "openid https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/accounts.reauth",
  "exp": "1650056632",
  "expires_in": "3488",
  "email": "user@example.com",
  "email_verified": "true"
}

Tabel berikut mencantumkan kolom yang paling penting untuk dipahami:

Kolom Deskripsi
azp ID project, email, atau akun layanan dari aplikasi yang meminta token. Nilai ini hanya disertakan jika https://www.googleapis.com/auth/userinfo.email ditentukan dalam daftar cakupan.
scope Cakupan OAuth yang telah ditambahkan ke token akses ini. Untuk layanan Google Cloud, praktik terbaiknya adalah menggunakan cakupan https://www.googleapis.com/auth/cloud-platform , yang meliputi semua Google Cloud API, bersama dengan Identity and Access Management (IAM), yang menyediakan kontrol akses terperinci.
expires_in Jumlah detik hingga masa berlaku token habis. Untuk informasi selengkapnya, lihat Masa berlaku token akses.

Masa berlaku token akses

Secara default, token akses berlaku selama 1 jam (3.600 detik). Saat masa berlaku token akses habis, kode pengelolaan token Anda harus mendapatkan kode baru.

Jika memerlukan token akses dengan masa berlaku yang lebih lama atau lebih pendek, Anda dapat menggunakan metode serviceAccounts.generateAccessToken untuk membuat token. Dengan metode ini, Anda dapat memilih masa berlaku token, dengan masa pakai maksimum 12 jam.

Jika ingin memperpanjang masa berlaku token melebihi default, Anda harus membuat kebijakan organisasi yang mengaktifkan batasan iam.allowServiceAccountCredentialLifetimeExtension. Anda tidak dapat membuat token akses dengan masa berlaku yang diperpanjang untuk kredensial pengguna atau identitas eksternal. Untuk informasi selengkapnya, lihat Membuat token akses jangka pendek.

Token ID

Token ID adalah Token Web JSON (JWT) yang sesuai dengan spesifikasi OpenID Connect (OIDC). Token tersebut terdiri dari kumpulan key-value pair yang disebut klaim.

Tidak seperti token akses, yang merupakan objek tersembunyi dan tidak dapat diperiksa oleh aplikasi, token ID dimaksudkan untuk dapat diperiksa dan digunakan oleh aplikasi. Informasi dari token, seperti Siapa yang menandatangani token atau identitas penerima token ID, tersedia untuk digunakan oleh aplikasi.

Untuk informasi selengkapnya tentang implementasi OIDC Google, lihat OpenID Connect. Untuk praktik terbaik dalam menggunakan JWT, lihat Praktik Terbaik Token Web JSON Saat Ini.

Konten token ID

Anda dapat memeriksa token ID yang valid (tidak habis masa berlakunya atau dicabut) menggunakan endpoint tokeninfo Google OAuth 2.0.

Ganti ID_TOKEN dengan token ID yang valid dan belum habis masa berlakunya.

curl "https://oauth2.googleapis.com/tokeninfo?id_token=ID_TOKEN"

Perintah ini menampilkan sesuatu yang mirip dengan contoh berikut:

{
  "iss": "https://accounts.google.com",
  "azp": "32555350559.apps.googleusercontent.com",
  "aud": "32555350559.apps.googleusercontent.com",
  "sub": "111260650121185072906",
  "hd": "google.com",
  "email": "user@example.com",
  "email_verified": "true",
  "at_hash": "_LLKKivfvfme9eoQ3WcMIg",
  "iat": "1650053185",
  "exp": "1650056785",
  "alg": "RS256",
  "kid": "f1338ca26835863f671403941738a7b49e740fc0",
  "typ": "JWT"
}

Tabel berikut menjelaskan klaim token ID yang diperlukan atau umum digunakan:

Klaim Deskripsi
iss Penerbit atau penanda tangan token. Untuk token ID yang ditandatangani Google, nilai ini adalah https://accounts.google.com.
azp Opsional. Kepada siapa token diterbitkan.
aud Audiens token. Nilai klaim ini harus cocok dengan aplikasi atau layanan yang menggunakan token tersebut untuk autentikasi permintaan. Untuk informasi selengkapnya, lihat klaim aud token ID.
sub Subjek: ID yang mewakili akun utama pembuat permintaan.
iat Waktu epoch Unix saat token diterbitkan.
exp Waktu epoch Unix saat masa berlaku token habis.

Klaim lain mungkin ada, tergantung pada penerbit dan aplikasinya.

Klaim token ID aud

Klaim aud menjelaskan nama layanan yang dibuat untuk dipanggil oleh token ini. Jika menerima token ID, layanan harus memverifikasi integritasnya (tanda tangan), validitas (apakah masih berlaku), dan jika klaim aud cocok dengan nama yang diharapkan. Jika tidak cocok, layanan harus menolak token tersebut, karena token mungkin berupa replay yang ditujukan untuk sistem lain.

Umumnya, ketika mendapatkan token ID, Anda menggunakan kredensial yang diberikan oleh akun layanan, bukan kredensial pengguna. Hal ini karena klaim aud untuk token ID yang dihasilkan menggunakan kredensial pengguna terikat secara statis dengan aplikasi yang digunakan pengguna untuk melakukan autentikasi. Jika menggunakan akun layanan untuk memperoleh token ID, Anda dapat menentukan nilai yang berbeda untuk klaim aud.

Masa berlaku token ID

Token ID valid hingga 1 jam (3.600 detik). Saat masa berlaku token ID habis, Anda harus mendapatkan token baru.

Validasi token ID

Saat layanan atau aplikasi Anda menggunakan layanan Google seperti Cloud Run, Cloud Functions, atau Identity-Aware Proxy, Google akan memvalidasi token ID untuk Anda; dalam hal ini, token ID harus ditandatangani oleh Google.

Jika perlu memvalidasi token ID dalam aplikasi, Anda dapat melakukannya, meskipun ini merupakan alur kerja lanjutan. Untuk mengetahui informasinya, lihat Memvalidasi token ID.

JSON Web Token (JWT) yang ditandatangani sendiri

JWT yang ditandatangani sendiri diperlukan untuk autentikasi ke API yang di-deploy dengan Gateway API. Selain itu, Anda dapat menggunakan JWT yang ditandatangani sendiri untuk autentikasi ke beberapa Google API tanpa harus mendapatkan token akses dari Server Otorisasi.

Disarankan untuk membuat JWT yang ditandatangani sendiri jika Anda membuat library klien sendiri untuk mengakses Google API, tetapi merupakan alur kerja lanjutan. Untuk informasi selengkapnya tentang JWT yang ditandatangani sendiri, lihat Membuat Token Web JSON yang ditandatangani sendiri. Untuk praktik terbaik dalam menggunakan JWT, lihat Praktik Terbaik Token Web JSON Saat Ini.

Token refresh

Secara default, token akses dan token ID berlaku selama 1 jam. Token refresh adalah token khusus yang digunakan untuk memperoleh token akses atau token ID tambahan. Saat pertama kali melakukan autentikasi, aplikasi Anda akan menerima token akses atau token ID, serta token refresh. Kemudian, jika aplikasi perlu mengakses resource lagi, dan token yang diberikan sebelumnya telah habis masa berlakunya, aplikasi akan menggunakan token refresh untuk meminta token baru. Token refresh hanya digunakan untuk autentikasi pengguna, seperti untuk Cloud Identity atau Google Workspace.

Token refresh tidak memiliki masa berlaku tetap; masa berlakunya dapat habis, tetapi jika tidak, token tersebut dapat terus digunakan. Untuk akses pengguna di Google Workspace atau Cloud Identity Premium Edition, Anda dapat mengonfigurasi durasi sesi untuk memastikan bahwa pengguna harus login secara berkala untuk mempertahankan akses ke layanan Google Cloud.

Jika aplikasi Anda membuat dan mengelola tokennya sendiri, aplikasi juga perlu mengelola token refresh. Untuk informasi selengkapnya, lihat link berikut:

Token gabungan

Token gabungan digunakan sebagai langkah perantara oleh workload identity federation. Token gabungan ditampilkan oleh Layanan Token Keamanan dan tidak dapat digunakan secara langsung. Token tersebut harus ditukarkan dengan token akses menggunakan peniruan akun layanan.

Token pemilik

Token pemilik adalah class token umum yang memberikan akses kepada pihak yang memiliki token. Token akses, token ID, dan JWT yang ditandatangani sendiri adalah token pemilik.

Penggunaan token pemilik untuk autentikasi bergantung pada keamanan yang disediakan oleh protokol terenkripsi, seperti HTTPS; jika token pemilik dicegat, token tersebut dapat digunakan oleh pihak tidak bertanggung jawab untuk mendapatkan akses.

Jika token pemilik tidak memberikan keamanan yang memadai untuk kasus penggunaan Anda, pertimbangkan untuk menambahkan lapisan enkripsi lain atau menggunakan solusi Transport Layer Security (mTLS) bersama seperti BeyondCorp Enterprise, yang membatasi akses hanya untuk pengguna yang diautentikasi pada perangkat tepercaya.

Langkah selanjutnya