Jenis token

Google Cloud menerbitkan beberapa jenis token, yang berbeda berdasarkan tujuan dan pihak yang bertukar token tersebut.

Tabel berikut memberikan ringkasan kategori token utama, yang di dalamnya terdapat berbagai jenis token.

Kategori token Jalur komunikasi Tujuan
Token akses Server otorisasi Klien Google API Mengizinkan klien memanggil Google Cloud API.
Token pemberi token Server otorisasi Klien Memungkinkan klien mendapatkan token baru atau berbeda, mungkin di lain waktu.
Token identitas Server otorisasi Klien Memungkinkan klien mengidentifikasi pengguna yang berinteraksi dengan mereka.

Token akses dan identitas adalah token pemilik. Token pemilik adalah class token umum yang memberikan akses kepada pihak yang memiliki token.

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

Jika token pemilik tidak memberikan keamanan yang memadai untuk kasus penggunaan Anda, Anda dapat mengurangi risiko pencurian token dengan menggunakan akses yang sadar konteks, membatasi masa aktif token akses, atau menggunakan solusi Transport Layer Security (mTLS) bersama seperti Chrome Enterprise Premium.

Token akses

Token akses memungkinkan klien melakukan panggilan yang diautentikasi ke API Google Cloud . Google Cloud mendukung beberapa jenis token akses yang berbeda, yang memiliki properti umum berikut:

  • Mereka mengautentikasi akun utama, yang dapat berupa pengguna atau workload.

  • Token ini dikeluarkan untuk satu klien tertentu.

  • Masa berlakunya singkat dan akan berakhir paling lama beberapa jam setelah dibuat.

  • API ini dibatasi untuk cakupan, endpoint, atau resource OAuth tertentu. Artinya, token akses biasanya tidak memberikan akses ke semua resource pengguna, tetapi hanya ke sebagian resource tertentu.

Token akses dapat berbeda dalam hal berikut:

  • Penerbit: Pihak yang menerbitkan token.

  • Principal: Jenis principal yang dapat diautentikasi oleh token.

  • Batasan: Batasan yang dapat diberlakukan pada token.

Tabel berikut mencantumkan berbagai jenis token akses:

Jenis token Penerbit Kepala sekolah Pembatasan
Token akses pengguna Server otorisasi Google
  • Pengguna (pengguna terkelola)
  • Pengguna (akun konsumen)
Cakupan OAuth
Token akses akun layanan
  • Server otorisasi Google
  • Google Cloud Server otorisasi IAM
Akun layanan Cakupan OAuth
Token delegasi tingkat domain Server otorisasi Google Pengguna (pengguna terkelola) Cakupan OAuth
Token Web JSON (JWT) akun layanan Klien Akun layanan Cakupan OAuth atau API
Token akses gabungan Google Cloud Server otorisasi IAM
  • Principal kumpulan identitas tenaga kerja
  • Principal workload identity pool
Cakupan OAuth
Token batas akses kredensial Google Cloud Server otorisasi IAM
  • Pengguna (pengguna terkelola)
  • Pengguna (akun konsumen)
  • Akun layanan
Objek Cloud Storage tertentu
Token batas akses kredensial yang dikeluarkan klien Klien Akun layanan Objek Cloud Storage tertentu

Berbagai jenis token akses juga menunjukkan properti keamanan yang berbeda:

  • Format: Beberapa token akses bersifat tersembunyi, yang berarti token tersebut berada dalam format kepemilikan dan tidak dapat diperiksa. Token lainnya dienkode sebagai Token Web JSON, yang dapat didekode oleh klien.

  • Introspectability: Beberapa token buram dapat diintrospeksi menggunakan Google Cloud API, sedangkan yang lainnya tidak dapat diintrospeksi.

  • Masa berlaku: Token berbeda dalam masa berlaku dan sejauh mana token tersebut dapat dimodifikasi.

  • Dapat dicabut: Beberapa token dapat dicabut. Token lainnya tetap valid hingga masa berlakunya habis.

Tabel berikut merangkum perbedaan antara jenis token akses.

Jenis token Format Dapat diintrospeksi Selama ini Dapat dibatalkan
Token akses pengguna Buram Ya 1 jam Ya
Token akses akun layanan Buram Ya 5 menit–12 jam Tidak
Token delegasi tingkat domain Buram Ya 1 jam Tidak
Token Web JSON (JWT) akun layanan JWT T/A 5 menit–1 jam Tidak
Token akses gabungan Buram Tidak Lihat Token akses gabungan Tidak
Token batas akses kredensial Buram Tidak Lihat Token batas akses kredensial Tidak
Token batas akses kredensial yang dikeluarkan klien Buram Tidak T/A Tidak

Token akses pengguna

Token akses pengguna mengautentikasi pengguna dan mengizinkan klien untuk bertindak atas nama pengguna:

Akun utama yang diautentikasi adalah akun pengguna terkelola atau akun konsumen. Klien dapat berupa aplikasi web atau aplikasi native.

Token akses pengguna bersifat buram. Untuk tujuan diagnostik, Anda dapat memeriksa token akses menggunakan perintah berikut, dengan mengganti ACCESS_TOKEN dengan token akses yang valid:

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

Perintah ini menghasilkan output yang mirip dengan contoh berikut:

{
  "azp": "0000000000.apps.googleusercontent.com",
  "aud": "0000000000.apps.googleusercontent.com",
  "sub": "00000000000000000000",
  "scope": "openid https://www.googleapis.com/auth/userinfo.email",
  "exp": "1744687132",
  "expires_in": "3568",
  "email": "user@example.com",
  "email_verified": "true"
}

Outputnya mencakup kolom berikut:

Kolom Nama Deskripsi
aud Audiens

Klien OAuth yang dituju token ini, yang diidentifikasi oleh ID klien OAuth.

Klien OAuth dapat memperoleh token akses untuk klien OAuth lain yang termasuk dalam project yang sama. Audiens mungkin berbeda dengan pihak yang berwenang.

azp Pihak yang berwenang Klien OAuth yang meminta token, yang diidentifikasi oleh ID klien OAuth-nya.
email Alamat email utama

Alamat email utama pengguna.

Kolom ini hanya ada jika token menyertakan cakupan https://www.googleapis.com/auth/userinfo.email.

exp Kedaluwarsa Waktu habis masa berlaku token, dalam format waktu epoch Unix.
scope Cakupan OAuth Kumpulan API yang diizinkan untuk diakses klien atas nama pengguna, yang diidentifikasi oleh cakupan OAuth.
sub Subjek

Principal yang diautentikasi, yang diidentifikasi berdasarkan ID uniknya.

ID ini setara dengan ID yang diekspos di Directory API.

Token akses pengguna akan otomatis berakhir setelah satu jam, tetapi dapat dicabut lebih awal jika diperlukan.

Secara default, token akses pengguna adalah token pemilik, yang berarti token tersebut tidak terikat ke saluran komunikasi, jaringan, atau kredensial tambahan tertentu. Secara opsional, Anda dapat menerapkan pengikatan token dengan men-deploy akses berbasis sertifikat sehingga token akses pengguna hanya dapat digunakan bersama dengan sertifikat klien mTLS yang valid.

Token akses akun layanan

Token akses akun layanan mengautentikasi akun layanan. Token bersifat buram dan Anda dapat memeriksanya menggunakan https://oauth2.googleapis.com/tokeninfo API.

Untuk token akses akun layanan, API menampilkan output yang mirip dengan contoh berikut:

{
  "azp": "000000000000000000000",
  "aud": "000000000000000000000",
  "scope": "https://www.googleapis.com/auth/userinfo.email",
  "exp": "1744687132",
  "expires_in": "3568",
  "email": "service-account@example.",
  "email_verified": "true",
  "access_type": "online"
}

Token akun layanan mencakup kolom berikut:

Kolom Nama Deskripsi
aud Audiens Akun layanan yang dituju token, setara dengan pihak yang berwenang.
azp Pihak yang berwenang Akun layanan yang meminta token, yang diidentifikasi oleh ID uniknya.
email Alamat email utama

Alamat email akun layanan.

Kolom ini hanya ada jika token menyertakan cakupan https://www.googleapis.com/auth/userinfo.email.

exp Kedaluwarsa Waktu habis masa berlaku token, dalam format waktu epoch Unix.

Token akses akun layanan tidak dapat dicabut dan akan tetap valid hingga habis masa berlakunya.

Secara default, masa berlaku token akses akun layanan berakhir setelah satu jam. Dengan menggunakan metode serviceAccounts.generateAccessToken, Anda dapat meminta token dengan masa aktif yang berbeda. Karena masa aktif token yang lebih lama dapat meningkatkan risiko, Anda harus mengonfigurasi batasan iam.allowServiceAccountCredentialLifetimeExtension untuk mengizinkan klien meminta token akses akun layanan dengan masa aktif lebih dari satu jam.

Token delegasi tingkat domain

Token delegasi tingkat domain mengautentikasi pengguna dan memberikan otorisasi kepada akun layanan untuk bertindak atas nama pengguna. Token bersifat buram dan Anda dapat melakukan introspeksi menggunakan https://oauth2.googleapis.com/tokeninfo API.

Untuk token delegasi tingkat domain, API menampilkan output yang mirip dengan contoh berikut:

{
  "azp": "000000000000000000000",
  "aud": "000000000000000000000",
  "scope": "https://www.googleapis.com/auth/admin.directory.user.readonly https://www.googleapis.com/auth/userinfo.email",
  "exp": "1744688957",
  "expires_in": "3540",
  "email": "user@example.com",
  "email_verified": "true",
  "access_type": "offline"
}

Token delegasi tingkat domain mencakup kolom berikut:

Kolom Nama Deskripsi
aud Audiens Akun layanan yang ditujukan untuk token, setara dengan pihak yang berwenang.
azp Pihak yang berwenang Akun layanan yang meminta token, yang diidentifikasi oleh ID uniknya.
email Alamat email utama

Alamat email utama pengguna yang ditiru identitasnya.

Kolom ini hanya ada jika token menyertakan cakupan https://www.googleapis.com/auth/userinfo.email.

exp Kedaluwarsa Waktu habis masa berlaku token, dalam format waktu epoch Unix.
scope Cakupan OAuth Kumpulan API yang diizinkan untuk diakses klien atas nama pengguna yang di-impersonate, yang diidentifikasi oleh cakupan OAuth.

Masa berlaku token delegasi tingkat domain otomatis berakhir setelah satu jam, dan token tersebut tidak dapat dibatalkan.

Token Web JSON akun layanan

Token Web JSON (JWT) akun layanan mengautentikasi akun layanan. Sementara token akses akun layanan dikeluarkan oleh server otorisasi, JWT akun layanan dapat dikeluarkan oleh klien itu sendiri.

JWT ini terkadang disebut JWT "yang ditandatangani sendiri". JWT ini dapat berguna saat Anda perlu melakukan autentikasi ke beberapa Google API tanpa mendapatkan token akses dari server otorisasi—misalnya, saat membuat library klien Anda sendiri.

Untuk menerbitkan JWT akun layanan, klien harus melakukan langkah-langkah berikut:

  1. Siapkan payload tanda tangan web JSON yang mencakup alamat email akun layanan, cakupan OAuth atau endpoint API, dan waktu habis masa berlaku.

  2. Tandatangani payload menggunakan kunci akun layanan dari akun layanan yang bersangkutan. Klien dapat menandatangani payload secara offline menggunakan kunci akun layanan yang dikelola pengguna, atau secara online menggunakan metode signJwt dan kunci akun layanan yang dikelola Google. Untuk mengetahui informasi selengkapnya, lihat Membuat Token Web JSON yang ditandatangani sendiri

JWT akun layanan yang didekode akan terlihat mirip dengan berikut, dengan SIGNATURE diganti dengan tanda tangan token:

{
  "alg": "RS256",
  "kid": "290b7bf588eee0c35d02bf1164f4336229373300",
  "typ": "JWT"
}.{
  "iss": "service-account@example.",
  "sub": "service-account@example.",
  "scope": "https://www.googleapis.com/auth/cloud-platform",
  "exp": 1744851267,
  "iat": 1744850967
}.SIGNATURE

Daripada menentukan cakupan OAuth di kunci scope, JWT akun layanan dapat menentukan endpoint API di kunci aud:

{
  "alg": "RS256",
  "kid": "290b7bf588eee0c35d02bf1164f4336229373300",
  "typ": "JWT"
}.{
  "iss": "service-account@example.",
  "sub": "service-account@example.",
  "aud": "https://cloudresourcemanager.googleapis.com/",
  "exp": 1744854799,
  "iat": 1744851199
}.SIGNATURE

JWT akun layanan mencakup kolom berikut:

Kolom Nama Deskripsi
aud Audiens Endpoint API yang diizinkan untuk diakses klien. Hanya valid jika scope tidak ditentukan.
exp Kedaluwarsa Waktu habis masa berlaku token, dalam format waktu epoch Unix.
iat Waktu penerbitan Waktu penerbitan token, dalam format waktu epoch Unix.
iss Penerbit Penerbit token, yaitu akun layanan itu sendiri.
scope Cakupan OAuth Kumpulan API yang diizinkan untuk diakses klien, yang diidentifikasi oleh cakupan OAuth. Hanya valid jika aud tidak ditentukan.
sub Subjek Akun utama yang diautentikasi, yaitu akun layanan itu sendiri.

JWT akun layanan dapat berlaku hingga satu jam, dan tidak dapat dibatalkan.

Token akses gabungan

Token akses gabungan mengautentikasi prinsipal kumpulan workload atau prinsipal kumpulan tenaga kerja.

Workforce Identity Federation memungkinkan klien menukar token eksternal dengan token akses gabungan yang mengautentikasi pokok kumpulan tenaga kerja. Principal workload identity pool diidentifikasi oleh ID principal yang mirip dengan berikut ini:

principal://iam.googleapis.com/locations/global/workforcePools/POOL/subject/raha@altostrat.com.

Workload Identity Federation memungkinkan klien menukarkan token eksternal dengan token akses gabungan yang mengautentikasi pokok kumpulan beban kerja. Principal workload identity pool diidentifikasi oleh ID principal yang mirip dengan berikut ini:

principal://iam.googleapis.com/projects/PROJECT/locations/global/workloadIdentityPools/POOL/subject/SUBJECT_ATTRIBUTE_VALUE

Token akses gabungan bersifat tersembunyi dan tidak dapat diintrospeksi. Token tidak dapat dicabut dan tetap valid hingga masa berlakunya berakhir. Masa berlaku untuk setiap jenis token didasarkan pada hal berikut:

  • Workforce Identity Federation menetapkan masa berlaku token berdasarkan konfigurasi penyedia workforce identity pool.

  • Workload Identity Federation menetapkan masa berlaku token agar cocok dengan masa berlaku token eksternal.

Token batas akses kredensial

Token batas akses kredensial mengautentikasi pengguna atau akun layanan dan mencakup batas akses. Batas akses membatasi token sehingga hanya dapat digunakan untuk mengakses subset resource Cloud Storage yang ditentukan.

Token batas akses kredensial terkadang disebut sebagai diperkecil cakupannya karena berasal dari token input, tetapi lebih dibatasi dalam resource yang aksesnya diberikan.

Masa berlaku token batas akses kredensial berasal dari masa berlaku token input, yang dapat berupa token akses pengguna atau token akses akun layanan. Token batas akses kredensial bersifat tersembunyi dan tidak dapat diintrospeksi atau dicabut.

Token batas akses kredensial yang dikeluarkan klien

Token batas akses kredensial yang dikeluarkan klien mirip dengan token batas akses kredensial, tetapi dioptimalkan untuk skenario saat klien perlu mendapatkan token batas akses kredensial dengan batas akses yang berbeda pada frekuensi tinggi.

Klien dapat membuat token batas akses kredensial yang dikeluarkan klien secara lokal dengan menggunakan Library Klien Cloud dan token perantara batas akses, yang harus diperbarui secara berkala.

Token batas akses kredensial yang dikeluarkan klien bersifat tersembunyi dan tidak dapat diperiksa atau dicabut.

Token yang memberikan token

Token pemberi token memungkinkan klien mendapatkan token baru atau berbeda, mungkin di lain waktu. Google Cloud mendukung beberapa jenis token pemberi token, dan semuanya memiliki kesamaan berikut:

  • Token ini mewakili autentikasi sebelumnya.

  • Mereka mengautentikasi akun utama, yang dapat berupa identitas Google (pengguna atau beban kerja) atau identitas eksternal.

  • Kode ini dapat ditukarkan dengan token akses.

  • Token ini tidak dapat digunakan untuk melakukan panggilan Google API, yang membedakannya dengan token akses.

Token pemberi token dapat berbeda dalam hal berikut:

  • Penerbit: Pihak yang menerbitkan token.

  • Principal: Jenis identitas principal yang dapat diautentikasi oleh token.

  • Batasan: Batasan yang dapat diberlakukan pada token.

Tabel berikut mencantumkan berbagai jenis token yang memberikan token.

Jenis token Penerbit Jenis token akses yang ditukarkan Kepala sekolah Pembatasan
Token refresh Server otorisasi Google Token akses pengguna
  • Pengguna (pengguna terkelola)
  • Pengguna (akun konsumen)
Cakupan OAuth
Kode otorisasi Server otorisasi Google Token akses pengguna
  • Pengguna (pengguna terkelola)
  • Pengguna (akun konsumen)
Cakupan OAuth
Pernyataan Token Web JSON akun layanan Klien
  • Token delegasi tingkat domain
  • Token akses akun layanan
  • Pengguna (pengguna terkelola)
  • Akun layanan
Cakupan OAuth
Token Web JSON Eksternal Penyedia identitas eksternal Token akses gabungan Entity eksternal Tidak ada
Respons atau pernyataan SAML eksternal Penyedia identitas eksternal Token akses gabungan Entity eksternal Tidak ada
Token Amazon Web Services (AWS) GetCallerIdentity Penyedia identitas eksternal Token akses gabungan Entity eksternal Tidak ada

Berbagai jenis token pemberi token juga menunjukkan properti keamanan yang berbeda:

  • Format: Beberapa token bersifat buram. Token lain dapat didekode oleh klien.

  • Masa berlaku: Token berbeda dalam masa berlaku, dan sejauh mana token tersebut dapat dimodifikasi.

  • Penggunaan beberapa kali: Beberapa token pemberi token hanya dapat digunakan satu kali. Token lain dapat digunakan beberapa kali.

  • Dapat dicabut: Beberapa token dapat dicabut. Token lainnya tetap valid hingga masa berlakunya habis.

Tabel berikut merangkum perbedaan antara properti ini untuk token yang memberikan token:

Jenis token Format Selama ini Dapat dibatalkan Multiguna
Token refresh Buram Lihat Token refresh Ya Ya
Kode otorisasi Buram 10 menit Tidak Tidak
Pernyataan Token Web JSON akun layanan JWT 5 menit–1 jam Tidak Ya
Token eksternal atau Token Web JSON eksternal JWT Bergantung pada penyedia identitas Bergantung pada penyedia identitas Ya
Pernyataan atau respons SAML eksternal SAML Bergantung pada penyedia identitas Bergantung pada penyedia identitas Ya
Token GetCallerIdentity Amazon Web Services (AWS) Blob teks Bergantung pada penyedia identitas Bergantung pada penyedia identitas Ya

Token refresh

Token refresh adalah token buram yang memungkinkan klien mendapatkan token ID dan token akses untuk pengguna, jika pengguna sebelumnya mengizinkan klien untuk bertindak atas nama mereka.

Token refresh terikat ke klien tertentu dan hanya dapat digunakan bersama dengan kredensial klien yang valid; misalnya, client ID dan rahasia klien.

Jika otorisasi klien mencakup satu atau beberapa Google Cloud cakupan OAuth, masa aktif token refresh tunduk pada kontrol Google Cloud durasi sesi. Jika tidak, token refresh akan tetap valid hingga pengguna mencabut otorisasi mereka atau peristiwa pencabutan token lainnya terjadi.

Kode otorisasi

Kode otorisasi adalah token buram dengan masa aktif singkat. Kode hanya ditujukan untuk digunakan selama autentikasi pengguna sebagai perantara antara klien dan server otorisasi Google.

Seperti token refresh, kode otorisasi terikat ke klien dan hanya dapat digunakan bersama dengan kredensial klien yang valid. Tidak seperti token refresh, kode otorisasi hanya dapat digunakan satu kali.

Pernyataan Token Web JSON akun layanan

Pernyataan Token Web JSON (JWT) akun layanan menegaskan identitas akun layanan. Workload dapat menggunakan pernyataan JWT akun layanan untuk mendapatkan token akses akun layanan atau token delegasi tingkat domain. Pernyataan JWT akun layanan ditandatangani oleh kunci akun layanan.

Pernyataan JWT akun layanan yang didekode akan terlihat mirip dengan berikut, dengan SIGNATURE diganti dengan tanda tangan token:

{
  "alg": "RS256",
  "kid": "290b7bf588eee0c35d02bf1164f4336229373300",
  "typ": "JWT"
}.{
  "iss": "service-account@example.",
  "scope": "https://www.googleapis.com/auth/devstorage.read_only",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1744851267,
  "iat": 1744850967
}.SIGNATURE

Pernyataan JWT akun layanan secara struktural mirip dengan JWT akun layanan: kedua jenis token dapat dikeluarkan oleh klien itu sendiri, dan ditandatangani oleh kunci akun layanan. Namun, kedua jenis token tersebut menggunakan payload yang berbeda, seperti yang dijelaskan dalam tabel berikut.

Kolom JWT akun layanan Pernyataan JWT akun layanan
aud Google Cloud API, dihilangkan jika scope ditentukan Harus berupa https://oauth2.googleapis.com/token
exp Kedaluwarsa Kedaluwarsa
iat Waktu penerbitan Waktu penerbitan
iss Alamat email akun layanan Alamat email akun layanan
scope Cakupan OAuth, dihilangkan jika aud ditentukan Cakupan OAuth
sub Alamat email akun layanan Alamat email akun pengguna untuk delegasi tingkat domain, dihilangkan jika tidak

Pernyataan JWT akun layanan dapat valid hingga satu jam, dan tidak dapat dicabut.

Token Web JSON Eksternal

Token Web JSON (JWT) eksternal dikeluarkan oleh penyedia identitas eksternal seperti Microsoft Entra ID, Okta, Kubernetes, atau GitHub. Struktur dan kontennya mungkin berbeda.

Dengan mengonfigurasi Workforce Identity Federation atau Workload Identity Federation, Anda dapat menyiapkan hubungan tepercaya antara Google Cloud dan penyedia identitas eksternal. Workload kemudian dapat menggunakan JWT eksternal sebagai token pemberi token untuk mendapatkan token akses gabungan.

Saat Anda menggunakan Workforce Identity Federation, token akses gabungan yang dihasilkan mengautentikasi prinsipal kumpulan identitas tenaga kerja.

Saat Anda menggunakan Workload Identity Federation, token akses gabungan yang dihasilkan mengautentikasi prinsipal kumpulan identitas workload.

Dalam kedua kasus tersebut, ID akun utama berasal dari satu atau beberapa klaim JWT eksternal.

Agar kompatibel dengan Workforce Identity Federation atau Workload Identity Federation, JWT eksternal harus memenuhi persyaratan tertentu.

Pernyataan atau respons SAML eksternal

Pernyataan Security Assertion Markup Language (SAML) eksternal adalah pernyataan SAML 2.0 yang dikeluarkan oleh penyedia identitas eksternal seperti Microsoft Entra ID, Okta, atau Active Directory Federation Services. Pernyataan SAML eksternal ini dapat disertakan secara opsional dalam respons SAML 2.0 atau dienkripsi.

Seperti Token Web JSON eksternal, Anda dapat mengonfigurasi Workforce Identity Federation atau Workload Identity Federation sehingga beban kerja dapat menggunakan pernyataan atau respons SAML eksternal sebagai token pemberi token untuk mendapatkan token akses gabungan.

Agar kompatibel dengan Workforce Identity Federation atau Workload Identity Federation, pernyataan SAML eksternal harus memenuhi persyaratan tertentu.

Token GetCallerIdentity Amazon Web Services (AWS)

Token GetCallerIdentity AWS eksternal adalah blob teks yang berisi permintaan yang ditandatangani ke AWS GetCallerIdentity API. Mirip dengan JSON Web Token eksternal dan pernyataan SAML, Anda dapat mengonfigurasi Workforce Identity Federation atau Workload Identity Federation sehingga beban kerja dapat menggunakan blob teks ini sebagai token pemberi token untuk mendapatkan token akses gabungan.

Token identitas

Token identitas (ID) memungkinkan klien mengidentifikasi pengguna yang berinteraksi dengan mereka. Google Cloud mendukung beberapa jenis token identitas yang berbeda, dan semuanya memiliki kesamaan berikut:

  • Token ini diformat sebagai Token Web JSON (JWT) sehingga dapat didekode, diverifikasi, dan ditafsirkan oleh klien.

  • Mereka mengautentikasi akun utama, yang dapat berupa pengguna atau workload.

  • Token ini dikeluarkan untuk satu klien tertentu.

  • Token ini berumur pendek dan akan berakhir setelah paling lama satu jam.

  • Tidak dapat dibatalkan.

  • Token ini tidak dapat digunakan untuk melakukan panggilan Google API, yang membedakannya dari token akses.

  • Token ini tidak dapat digunakan untuk mendapatkan token akses, yang membedakannya dari token pemberi token.

  • Token ini dapat digunakan untuk mengautentikasi panggilan antar-microservice, atau untuk mengautentikasi secara terprogram ke Identity-Aware Proxy (IAP).

Token identitas dapat berbeda dalam hal berikut:

  • Audiens: Pihak yang dimaksudkan untuk mendekode dan menggunakan token.

  • Penerbit: Pihak yang menerbitkan token.

  • Masa berlaku: Token berbeda dalam masa berlaku, dan sejauh mana token tersebut dapat dimodifikasi.

  • Principal: Jenis identitas principal yang dapat diautentikasi oleh token.

Tabel berikut mencantumkan berbagai jenis token identitas.

Jenis token Penerbit Audiens Akun utama Selama ini
Token ID pengguna Server otorisasi Google Klien OAuth/OIDC
  • Pengguna (pengguna terkelola)
  • Pengguna (akun konsumen)
1 jam
Token ID akun layanan Google Cloud Server otorisasi IAM Bebas memilih audiens mana pun Akun layanan 1 jam
Pernyataan Identity-Aware Proxy (IAP) IAP
  • Backend
  • App Engine app
  • Pengguna (pengguna terkelola)
  • Pengguna (akun konsumen)
  • Principal kumpulan identitas tenaga kerja
10 menit
Pernyataan SAML Server otorisasi Google Aplikasi SAML Pengguna (pengguna terkelola) 10 menit

Token ID pengguna

Token ID pengguna adalah Token Web JSON (JWT) yang mengautentikasi pengguna. Klien dapat mendapatkan Token ID pengguna dengan memulai alur autentikasi OIDC.

Token ID pengguna ditandatangani menggunakan Set Kunci Web JSON (JWKS) Google. JWKS Google adalah resource global, dan kunci penandatanganan yang sama digunakan untuk berbagai jenis pengguna, termasuk yang berikut:

  • Akun pengguna terkelola

  • Akun pengguna konsumen

  • Akun layanan

Token ID pengguna yang didekode terlihat mirip dengan berikut, dengan SIGNATURE diganti dengan tanda tangan token:

{
  "alg": "RS256",
  "kid": "c37da75c9fbe18c2ce9125b9aa1f300dcb31e8d9",
  "typ": "JWT"
}.{
  "iss": "https://accounts.google.com",
  "azp": "1234567890-123456789abcdef.apps.googleusercontent.com",
  "aud": "1234567890-123456789abcdef.apps.googleusercontent.com",
  "sub": "12345678901234567890",
  "at_hash": "y0LZEe-ervzRNSxn4R-t9w",
  "name": "Example user",
  "picture": "https://lh3.googleusercontent.com/a/...",
  "given_name": "Example",
  "family_name": "User",
  "hd": "example.com",
  "iat": 1745361695,
  "exp": 1745365295
}.SIGNATURE

Token ID mencakup kolom berikut:

Kolom Nama Deskripsi
aud Audiens

Klien OAuth yang ditujukan untuk token ini, yang diidentifikasi oleh ID klien OAuth-nya.

Klien OAuth dapat memperoleh token akses untuk klien OAuth lain yang termasuk dalam project yang sama. Dalam hal ini, audiens mungkin berbeda dari pihak yang berwenang.

azp Pihak yang berwenang Klien OAuth yang melakukan alur autentikasi OIDC, yang diidentifikasi oleh Client ID OAuth.
exp Kedaluwarsa Waktu habis masa berlaku token, dalam format waktu epoch Unix.
hd Domain yang dihosting

Domain utama akun Cloud Identity atau Google Workspace pengguna.

Klaim ini hanya ada jika pengguna adalah akun pengguna terkelola dan klien menentukan parameter hd dalam permintaan autentikasi.

iss Penerbit Penerbit token. Selalu ditetapkan ke https://accounts.google.com.
sub Subjek

Principal yang diautentikasi, yang diidentifikasi berdasarkan ID uniknya.

ID ini setara dengan ID yang diekspos di Directory API.

Kumpulan klaim persis yang disertakan dalam token ID bergantung pada parameter scope dalam permintaan autentikasi.

Untuk mengidentifikasi apakah pengguna adalah akun pengguna terkelola, atau untuk mengidentifikasi akun Cloud Identity atau Google Workspace tempat pengguna berada, klien harus memeriksa klaim hd.

Token ID pengguna berlaku selama satu jam, dan tidak dapat dibatalkan.

Token ID akun layanan

Token ID akun layanan adalah Token Web JSON (JWT) yang mengautentikasi akun layanan.

Tidak seperti JWT akun layanan dan pernyataan JWT akun layanan, token ID akun layanan tidak ditandatangani oleh kunci akun layanan. Sebagai gantinya, token ID akun layanan ditandatangani oleh Google JSON Web Key Set (JWKS).

Token ID akun layanan yang didekode akan terlihat seperti berikut, dengan SIGNATURE diganti dengan tanda tangan token:

{
  "alg": "RS256",
  "kid": "c37da75c9fbe18c2ce9125b9aa1f300dcb31e8d9",
  "typ": "JWT"
}.{
  "aud": "example-audience",
  "azp": "112010400000000710080",
  "email": "service-account@example.",
  "email_verified": true,
  "exp": 1745365618,
  "iat": 1745362018,
  "iss": "https://accounts.google.com",
  "sub": "112010400000000710080"
}.SIGNATURE

Token ID akun layanan mencakup kolom berikut:

Kolom Nama Deskripsi
aud Audiens ID pihak yang dituju token ini. Nilai dapat dipilih secara bebas oleh pemohon token.
azp Pihak yang berwenang Akun layanan yang meminta token, yang diidentifikasi oleh ID uniknya.
exp Kedaluwarsa Waktu habis masa berlaku token, dalam format waktu epoch Unix.
iss Penerbit Penerbit token, selalu ditetapkan ke https://accounts.google.com.
sub Subjek Akun layanan yang meminta token, yang diidentifikasi oleh ID uniknya.

Kumpulan klaim persis yang disertakan dalam token ID bergantung pada cara token ID diminta. Misalnya, token ID yang diminta oleh server metadata Compute Engine dapat secara opsional menyertakan klaim tambahan yang mengonfirmasi identitas VM. Token ID yang diminta menggunakan IAM Credentials API dapat secara opsional berisi ID organisasi project akun layanan.

Tidak seperti token ID pengguna, token ID akun layanan tidak mendukung klaim hd.

Token ID akun layanan valid selama satu jam, dan tidak dapat dibatalkan.

Pernyataan Identity-Aware Proxy

Pernyataan Identity-Aware Proxy (IAP) adalah Token Web JSON (JWT) yang diteruskan IAP ke aplikasi web yang dilindungi IAP di header permintaan HTTP x-goog-iap-jwt-assertion. Pernyataan IAP mengautentikasi pengguna dan juga berfungsi sebagai bukti bahwa permintaan telah diizinkan oleh IAP.

Tidak seperti token ID pengguna dan token ID akun layanan, pernyataan IAP tidak ditandatangani menggunakan Set Kunci Web JSON (JWKS) Google. Sebagai gantinya, pernyataan IAP ditandatangani menggunakan JWKS terpisah, yaitu JWKS IAP. JWKS ini adalah resource global, dan kunci penandatanganan yang sama digunakan untuk berbagai jenis pengguna, termasuk yang berikut:

  • Akun pengguna terkelola

  • Akun konsumen

  • Akun layanan

  • Principal kumpulan identitas tenaga kerja

Pernyataan IAP yang didekode terlihat mirip dengan berikut, dengan SIGNATURE diganti dengan tanda tangan token:

{
  "alg": "ES256",
  "typ": "JWT",
  "kid": "4BCyVw"
}.{
  "aud": "/projects/0000000000/global/backendServices/000000000000",
  "azp": "/projects/0000000000/global/backendServices/000000000000",
  "email": "user@example.com",
  "exp": 1745362883,
  "google": {
    "access_levels": [
      "accessPolicies/0000000000/accessLevels/Australia"
    ]
  },
  "hd": "example.com",
  "iat": 1745362283,
  "identity_source": "GOOGLE",
  "iss": "https://cloud.google.com/iap",
  "sub": "accounts.google.com:112010400000000710080"
}.SIGNATURE

Jika Anda mengonfigurasi IAP untuk menggunakan Workforce Identity Federation bukan identitas Google, pernyataan IAP akan terlihat sedikit berbeda:

{
  "alg": "ES256",
  "typ": "JWT",
  "kid": "4BCyVw"
}.{
  "aud": "/projects/0000000000/global/backendServices/000000000000",
  "azp": "/projects/0000000000/global/backendServices/000000000000",
  "email": "user@example.com",
  "exp": 1745374290,
  "google": {
    "access_levels": [
      "accessPolicies/0000000000/accessLevels/Australia"
    ]
  },
  "iat": 1745373690,
  "identity_source": "WORKFORCE_IDENTITY",
  "iss": "https://cloud.google.com/iap",
  "sub": "sts.google.com:AAFTZ...Q",
  "workforce_identity": {
    "iam_principal": "principal://iam.googleapis.com/locations/global/workforcePools/example/subject/user-0000000000",
    "workforce_pool_name": "locations/global/workforcePools/example"
  }
}.SIGNATURE

Pernyataan IAP mencakup kolom berikut:

Kolom Nama Deskripsi
aud Audiens Layanan backend, aplikasi App Engine, atau layanan Cloud Run yang ditujukan untuk pernyataan IAP.
iss Penerbit Penerbit token, selalu ditetapkan ke https://cloud.google.com/iap
sub Subjek

Principal yang diautentikasi, yang diidentifikasi berdasarkan ID uniknya.

Jika IAP dikonfigurasi untuk menggunakan identitas Google, ID ini setara dengan ID yang diekspos di Directory API.

Untuk mengetahui detail lebih lanjut tentang klaim pernyataan IAP, lihat Memverifikasi payload JWT.

Pernyataan IAP berlaku selama 10 menit, dan tidak dapat dibatalkan.

Pernyataan SAML

Pernyataan Security Assertion Markup Language (SAML) mengautentikasi akun pengguna terkelola dan mengizinkannya untuk mengakses aplikasi SAML kustom. Pernyataan SAML dikeluarkan dan ditandatangani oleh Cloud Identity dan hanya dapat digunakan untuk mengautentikasi akun pengguna terkelola.

Tidak seperti token ID yang ditandatangani menggunakan kunci global, pernyataan SAML ditandatangani menggunakan kunci yang khusus untuk akun Cloud Identity atau Google Workspace.

Pernyataan respons SAML yang didekode akan terlihat seperti berikut:

<saml2:Assertion
  xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
  ID="..."
  IssueInstant="2025-04-23T22:47:20.881Z"
  Version="2.0">
  <saml2:Issuer>
    https://accounts.google.com/o/saml2?idpid=C0123456789
  </saml2:Issuer>
  <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">...</ds:Signature>
  <saml2:Subject>
    <saml2:NameID
      Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">
        user@example.com
    </saml2:NameID>
    <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
      <saml2:SubjectConfirmationData
        NotOnOrAfter="2025-04-23T22:52:20.881Z"
        Recipient="https://app.example.com/"/>
    </saml2:SubjectConfirmation>
  </saml2:Subject>

  <saml2:Conditions
    NotBefore="2025-04-23T22:42:20.881Z"
    NotOnOrAfter="2025-04-23T22:52:20.881Z">
    <saml2:AudienceRestriction>
      <saml2:Audience>example-app</saml2:Audience>
    </saml2:AudienceRestriction>
  </saml2:Conditions>

  <saml2:AuthnStatement
    AuthnInstant="2025-04-23T22:46:44.000Z"
    SessionIndex="...">
    <saml2:AuthnContext>
      <saml2:AuthnContextClassRef>
        urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified
      </saml2:AuthnContextClassRef>
    </saml2:AuthnContext>
  </saml2:AuthnStatement>
</saml2:Assertion>

Pernyataan SAML mencakup kolom berikut:

Kolom Nama Deskripsi
Audience Audiens ID entitas aplikasi SAML.
Issuer Penerbit Penerbit token, khusus untuk akun Cloud Identity atau Google Workspace.
NameID Subjek Principal yang diautentikasi. Format ID bergantung pada konfigurasi aplikasi SAML.

Kumpulan atribut yang tepat yang disertakan dalam pernyataan SAML bergantung pada konfigurasi aplikasi SAML.

Pernyataan SAML valid selama 10 menit, dan tidak dapat dibatalkan.