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
.
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 penerapan 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
.
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, fungsi Cloud Run, 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
Anda dapat menggunakan JWT yang ditandatangani sendiri untuk mengautentikasi 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
IdP Anda mengelola masa aktif token yang memiliki masa aktif lama. Pengecualian adalah file ADC lokal, yang berisi token refresh yang digunakan oleh library autentikasi untuk memuat ulang token akses secara otomatis untuk library klien.
Token gabungan
Token gabungan dibuat dari identitas gabungan oleh Workload Identity Federation dan Workforce Identity Federation.
Token gabungan digunakan dengan cara berikut:
Untuk layanan yang mendukung token ini, token gabungan dapat digunakan secara langsung. Metode ini terkadang disebut akses langsung.
Token gabungan dapat ditukar dengan token akses OAuth 2.0, menggunakan Security Token Service API.
Token gabungan yang ditampilkan oleh Workload Identity Federation dan Workforce Identity Federation tidak setara dengan token yang ditampilkan oleh Workload Identity Federation untuk GKE. Untuk informasi selengkapnya tentang cara aplikasi Google Kubernetes Engine mengautentikasi ke Google API, lihat Mengonfigurasi aplikasi untuk menggunakan Workload Identity Federation untuk GKE.
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.
Langkah selanjutnya
- Pelajari cara menyiapkan kredensial untuk ADC.
- Lihat informasi tentang cara mendapatkan token ID.
- Pahami metode autentikasi lebih lanjut.