Mengonfigurasi workload identity federation dengan penyedia identitas lain

Panduan ini menjelaskan cara menggunakan workload identity federation dengan penyedia identitas (IdP) lain.

Workload yang berjalan di luar Google Cloud mungkin memiliki akses di kredensial khusus lingkungan yang ada—misalnya:

Workload mungkin dapat memperoleh pernyataan SAML atau token OpenID Connect (OIDC) dari penyedia identitas (IdP) yang berjalan di lingkungan yang sama.

Untuk mengautentikasi ke Google Cloud, Anda dapat mengizinkan workload menukar kredensial khusus lingkungannya dengan kredensial Google Cloud yang memiliki jangka waktu pendek menggunakan workload identity federation.
Workload mungkin memiliki jenis kredensial lain seperti sertifikat klien mTLS.

Dengan menggabungkan workload identity federation denganbroken token kustom, Anda dapat mengizinkan workload menggunakan jenis kredensial lain untuk mendapatkan kredensial Google Cloud yang memiliki jangka waktu pendek.

Menggunakan workload identity federation dapat membantu Anda mengurangi jumlah kredensial yang memerlukan rotasi.

Bagian berikut menjelaskan cara menggunakan workload identity federation dengan IdP yang mendukung protokol autentikasi OpenID Connect (OIDC) atau SAML.

Menyiapkan IdP eksternal Anda

Langkah ini hanya perlu dilakukan satu kali untuk setiap IdP.

Sebelum memulai, verifikasi IdP eksternal Anda memenuhi persyaratan berikut:

OIDC

IdP mendukung OpenID Connect 1.0.
Metadata OIDC dan endpoint JWKS IdP yang diamankan dengan SSL dan TLS, URL endpoint dimulai dengan https://, dan endpoint dapat diakses secara publik melalui internet.

Google Cloud menggunakan endpoint ini untuk mendownload serangkaian kunci IdP Anda dan menggunakan serangkaian kunci ini untuk memvalidasi token.

Endpoints yang diamankan dengan sertifikat yang ditandatangani sendiri tidak didukung oleh Google Cloud.

SAML

IdP mendukung SAML 2.0.
IdP menyediakan dokumen SAML SP metadata yang menjelaskan konfigurasi penyedia layanan SAML dan berisi sertifikat penandatanganan IdP.

Google Cloud menggunakan sertifikat ini untuk memvalidasi pernyataan dan respons SAML.

Jika IdP Anda memenuhi kriteria ini, lakukan hal berikut:

OIDC

Konfigurasikan IdP Anda sehingga beban kerja Anda dapat memperoleh token ID yang memenuhi kriteria berikut:

Token ditandatangani menggunakan algoritme RS256 atau ES256.
Token berisi klaim aud dengan nilai berikut:
```
https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
```
Ganti kode berikut:
- PROJECT_NUMBER: nomor project pada project Google Cloud yang Anda gunakan untuk membuat workload identity pool.
- POOL_ID: ID pilihan Anda yang mengidentifikasi workload identity pool. Anda harus menggunakan ID yang sama saat nanti membuat workload identity pool.
- PROVIDER_ID: ID pilihan Anda yang mengidentifikasi penyedia workload identity pool. Anda harus menggunakan ID yang sama saat nanti membuat penyedia workload identity pool.
Atau, Anda dapat mengonfigurasi penyedia workload identity pool yang diharapkan audiens kustom.
Token berisi klaim exp untuk masa mendatang dan klaim iat yang sudah lalu.

Nilai exp harus lebih besar dari nilai iat maksimal 24 jam.

Biasanya, sebaiknya gunakan token ID saat melakukan pertukaran token, karena token ID mencerminkan identitas pengguna. Jika Anda memutuskan untuk menggunakan token akses, pastikan token akses memenuhi persyaratan tambahan berikut:

Token akses berformat Token Web JSON
Token akses bersi klaim ISSUER sehingga URL poin ISSUER/.well-known/openid-configuration yang mengarah ke endpoint metadata OIDC IdP.
Untuk mengupload kunci JWK lokal, lihat Mengelola JWK OIDC.

SAML

Konfigurasikan IdP Anda agar pernyataan SAML berisi:

elemen Issuer yang ditetapkan ke ID Entitas yang dikonfigurasi di penyedia workload identity pool. Format penerbit harus dihapus atau ditetapkan ke urn:oasis:names:tc:SAML:2.0:nameid-format:entity.
elemen Subject dengan:
- elemen NameID.
- tepat satu elemen SubjectConfirmation dengan Method yang ditetapkan ke urn:oasis:names:tc:SAML:2.0:cm:bearer.
- elemen SubjectConfirmationData dengan NotOnOrAfter yang ditetapkan ke stempel waktu yang terjadi di masa mendatang dan tanpa nilai NotBefore.
elemen Conditions dengan:
- NotBefore dihapus atau sudah berlalu.
- NotOnOrAfter dihapus atau di masa mendatang.
- Audience yang diformat sebagai berikut:
```
https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
```
  Ganti kode berikut:
  - PROJECT_NUMBER: nomor project pada project Google Cloud yang Anda gunakan untuk membuat workload identity pool.
  - POOL_ID: ID pilihan Anda yang mengidentifikasi workload identity pool. Anda harus menggunakan ID yang sama saat nanti membuat workload identity pool.
  - PROVIDER_ID: ID pilihan Anda yang mengidentifikasi penyedia workload identity pool. Anda harus menggunakan ID yang sama saat nanti membuat penyedia workload identity pool.
setidaknya satu elemen AuthnStatement.
elemen SessionNotOnOrAfter dengan stempel waktu yang terjadi di masa mendatang. Atau, hapus elemen tersebut.

Untuk pernyataan SAML yang disertakan dalam respons SAML, respons SAML harus berisi:

hanya satu pernyataan yang memenuhi kriteria di atas.
atribut IssueInstant dengan nilai kurang dari 1 jam yang lalu.
StatusCode urn:oasis:names:tc:SAML:2.0:status:Success.

Salah satu pernyataan SAML, respons, atau keduanya harus ditandatangani.

Mengonfigurasi workload identity federation

Langkah ini hanya perlu dilakukan satu kali untuk setiap IdP. Anda kemudian dapat menggunakan workload identity pool dan penyedia workload yang sama untuk beberapa workload serta di beberapa project Google Cloud.

Untuk mulai mengonfigurasi workload identity federation, lakukan hal berikut:

Di konsol Google Cloud, pada halaman pemilih project, pilih atau buat project Google Cloud.

Buka pemilih project

gunakan project yang dikhususkan untuk mengelola workload identity pool dan penyedia workload

Pastikan penagihan telah diaktifkan untuk project Google Cloud Anda.

Aktifkan API IAM, Resource Manager, Service Account Credentials, and Security Token Service.

Mengaktifkan API

Mengelola JWK OIDC (Opsional)

Bagian ini menunjukkan cara mengelola JWK OIDC yang diupload sendiri di penyedia oidc workload identity pool.

Membuat penyedia dan mengupload JWK OIDC

Untuk membuat JWK OIDC, lihat Implementasi JWT, JWS, JWE, JWK, dan JWA.

Untung mengupload file JWK OIDC saat Anda membuat penyedia workload identity pool, jalankan dengan perintah gcloud iam workload-identity-pools providers create-oidc dengan --jwk-json-path="JWK_JSON_PATH". Ganti JWK_JSON_PATH dengan jalur ke file JSON JWK.

Operasi ini membuat kunci yang diupload dengan kunci yang ada dalam file.

Perbarui JWK OIDC

Untuk mengupdate JWK OIDC, jalankan perintah gcloud iam workload-identity-pools providers update-oidc dengan --jwk-json-path="JWK_JSON_PATH". Ganti JWK_JSON_PATH dengan jalur ke file JSON JWK.

Operasi ini mengganti kunci apa pun yang sudah diupload dengan kunci yang ada dalam file. Anda tidak dapat memulihkan kunci yang diganti.

Hapus semua JWK OIDC yang diupload

Untuk menghapus semua JWK OIDC yang diupload dan kembali menggunakan URI penerbit untuk mengambil kunci, jalankan perintah gcloud iam workload-identity-pools providers update-oidc dengan --jwk-json-path="JWK_JSON_PATH". Ganti JWK_JSON_PATH dengan jalur ke file kosong. Gunakan tanda --issuer-uri untuk menetapkan URI penerbit.

Operasi ini menghapus semua kunci yang sudah diupload dengan kunci yang ada di file. Anda tidak dapat memulihkan kunci yang dihapus.

Menentukan pemetaan dan kondisi atribut

Token OIDC atau pernyataan SAML yang dikeluarkan oleh IdP Anda mungkin berisi beberapa atribut, dan Anda harus menentukan atribut yang ingin digunakan sebagai ID subjek (google.subject) di Google Cloud.

Secara opsional, Anda dapat memetakan atribut tambahan. Selanjutnya, Anda dapat merujuk ke atribut ini saat memberikan akses ke resource.

OIDC

Pemetaan atribut Anda dapat menggunakan klaim yang tersemat pada token ID atau token akses yang dikeluarkan oleh IdP eksternal.

Anda harus memetakan salah satu klaim ini ke google.subject untuk mengidentifikasi pengguna secara unik. Untuk melindungi dari ancaman proofing, pilih klaim dengan nilai unik yang tidak dapat diganti.

Banyak IdP mengisi klaim sub dengan ID unik dan tidak dapat diubah. Untuk IdP ini, pertimbangkan untuk memetakan klaim sub ke google.subject:

google.subject=assertion.sub

Hindari penggunaan klaim seperti email untuk tujuan ini. Alamat email biasanya dapat ditetapkan ulang atau diubah, sehingga tidak secara unik dan permanen mengidentifikasi pengguna.

SAML

Pemetaan atribut Anda dapat menggunakan elemen <Subject> dan <Attribute> yang disematkan dalam pernyataan yang dikeluarkan oleh IdP eksternal. Atribut SAML dapat dirujuk menggunakan kata kunci berikut:

assertion.subject berisi NameID dari pengguna yang diautentikasi yang ditemukan pada elemen <Subject>.
assertion.attributes['ATTRIBUTE_NAME'] berisi daftar nilai untuk <Attribute> yang serupa.

Anda harus memetakan salah satu klaim ini ke google.subject untuk mengidentifikasi pengguna secara unik. Untuk melindungi dari ancaman spoofing, pilih klaim dengan nilai unik yang tidak dapat diubah.

Banyak IdP mengisi NameId dengan ID yang unik dan tidak dapat diubah. Untuk IdP ini, pertimbangkan untuk memetakan atribut NameId ke google.subject:

google.subject=assertion.subject

Hindari penggunaan atribut seperti http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress untuk tujuan ini. Alamat email biasanya dapat ditetapkan ulang atau diubah, sehingga sehingga tidak mengidentifikasi pengguna secara unik dan permanen.

Secara opsional, Anda dapat menentukan kondisi atribut. Kondisi atribut adalah ekspresi CEL yang dapat memeriksa atribut pernyataan dan atribut target. Jika kondisi atribut bernilai true untuk kredensial tertentu, kredensial tersebut akan diterima. Jika tidak, kredensial akan ditolak.

OIDC

Anda dapat menggunakan kondisi atribut untuk membatasi pengguna yang dapat menggunakan workload identity federation untuk mendapatkan token Google Cloud dengan masa berlaku pendek.

Misalnya, kondisi berikut membatasi akses ke token yang berisi klain service_account kustom dengan nilai true:

assertion.service_account==true

SAML

Anda dapat menggunakan kondisi atribut untuk membatasi pengguna yang dapat menggunakan workload identity federation untuk mendapatkan token Google Cloud dengan masa berlaku pendek.

Misalnya, kondisi berikut membatasi akses ke pernyataan yang berisi atribut https://example.com/SAML/Attributes/AllowGcpFederation kustom dengan nilai true:

assertion.attributes['https://example.com/SAML/Attributes/AllowGcpFederation'][0]=='true'

Membuat workload identity pool dan penyedia workload

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk mengonfigurasi workload identity federation, minta administrator Anda untuk memberikan peran IAM berikut pada project:

Admin Workload Identity Pool (roles/iam.workloadIdentityPoolAdmin)
Admin Akun Layanan (roles/iam.serviceAccountAdmin)

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Atau, peran dasar Pemilik IAM (roles/owner) juga mencakup izin untuk mengonfigurasi penggabungan identitas. Anda tidak boleh memberikan peran dasar dalam lingkungan produksi, tetapi Anda dapat memberikannya dalam lingkungan pengembangan atau pengujian.

Sekarang Anda telah mengumpulkan semua informasi yang diperlukan untuk membuat workload identity pool dan penyedia workload.

Konsol

Di konsol Google Cloud, buka halaman Penyedia workload dan workload pool baru .

Buka Penyedia workload dan workload pool baru
Di bagian Buat identity pool, masukkan informasi berikut:
- Nama: Nama untuk pool. Nama ini juga digunakan sebagai ID pool. Anda tidak dapat mengubah ID pool nanti.
- Deskripsi: Teks yang menjelaskan tujuan pool.
Klik Lanjutkan.
Konfigurasikan setelan penyedia sebagai berikut:
OIDC
- Pada Pilih penyedia, pilih OpenID Connect (OIDC).
- Pada Nama penyedia, masukkan nama penyedia. Nama ini juga digunakan sebagai ID penyedia. Anda tidak dapat mengubah ID penyedia setelah penyedia dibuat.
- Pada URL Penerbit, masukkan URL penerbit IdP Anda. URL harus dimulai dengan https://
- Opsional: Pada file JWK(JSON), pilih file JWK yang akan diupload. Jika kolom ini tidak tersedia, Google Cloud akan mencoba mengambil JWK dari penerbit.
- Audiens yang diizinkan: Audiens token ID yang diharapkan.
SAML
- Pada Pilih penyedia, pilih SAML.
- Pada Nama penyedia, masukkan nama penyedia. Nama ini juga digunakan sebagai ID penyedia. Anda tidak dapat mengubah ID penyedia setelah penyedia dibuat.
- Pada file Metadata IDP (XML), upload dokumen XML metadata SAML yang disediakan oleh penyedia identitas Anda.
Klik Lanjutkan.
Pada bagian Konfirgurasi atribut penyedia, tambahkan pemetaan atribut yang Anda identifikasi sebelumnya dalam panduan ini.
Pada bagian Kondisi atribut, masukkan kondisi atribut yang Anda identifikasi sebelumnya dalam panduan ini. Biarkan kolom ini kosong jika Anda tidak memiliki kondisi atribut.
Untuk membuat workload identity pool dan penyedia workload klik Simpan.

gcloud

Untuk membuat workload identity pool baru, jalankan perintah berikut:
```
gcloud iam workload-identity-pools create POOL_ID \
    --location="global" \
    --description="DESCRIPTION" \
    --display-name="DISPLAY_NAME"
```
Ganti kode berikut:
- POOL_ID: ID unik untuk pool.
- DISPLAY_NAME: nama pool.
- DESCRIPTION: deskripsi pool yang Anda pilih. Deskripsi ini muncul saat Anda memberikan akses ke identitas pool.
Untuk menambahkan penyedia workload identity pool, lakukan hal berikut:
OIDC
Untuk menambahkan penyedia workload identity pool OIDC, jalankan perintah berikut:
```
gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="ISSUER" \
    --allowed-audiences="AUDIENCE" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"
    --jwk-json-path="JWK_JSON_PATH"
```
Ganti kode berikut:
- PROVIDER_ID: ID penyedia unik untuk workload identity pool yang Anda pilih.
- POOL_ID: ID workload identity pool yang telah Anda buat sebelumnya.
- ISSUER: URI penerbit seperti yang didefinisikan dalam metadata OIDC.
- AUDIENCE: Audiens yang diharapkan dari token ID, yang bagi banyak penyedia, cocok dengan client ID.
- MAPPINGS: Daftar yang dipisahkan koma untuk pemetaan atribut yang telah Anda buat sebelumnya dalam panduan ini.
- CONDITIONS: Kondisi atribut opsional yang telah Anda buat sebelumnya dalam panduan ini. Hapus parameter jika Anda tidak memiliki kondisi atribut.
- JWK_JSON_PATH: Jalur opsional ke JWK OIDC yang diupload secara lokal. Jika parameter ini tidak tersedia, Google Cloud akan menggunakan jalur /.well-known/openid-configuration IdP Anda untuk source JWK yang berisi kunci publik.
SAML
Untuk menambahkan penyedia workload identity pool SAML, jalankan perintah berikut:
```
gcloud iam workload-identity-pools providers create-saml PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --idp-metadata-path="IDP_METADATA_PATH" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"
```
Ganti kode berikut:
- POOL_ID: ID pool
- IDP_METADATA_PATH: jalur file lokal ke dokumen metadata IdP SAML
- MAPPINGS: daftar yang dipisahkan koma untuk pemetaan atribut yang Anda buat sebelumnya dalam panduan ini
- CONDITIONS: Opsional: the kondisi atribut yang Anda buat sebelumnya dalam panduan ini
gcp- awalan dicadangkan dan tidak dapat digunakan dalam ID pool atau penyedia.

Opsional: Menerima pernyataan SAML terenkripsi dari IdP

Untuk mengaktifkan IdP SAML 2.0 guna menghasilkan pernyataan SAML terenkripsi yang dapat diterima oleh workload identity federation, lakukan hal berikut:
- Dalam workload identity federation, lakukan hal berikut:
- Di IdP Anda, lakukan hal berikut:
Perlu diperhatikan bahwa, meskipun kunci penyedia enkripsi SAML dikonfigurasi, workload identity federation masih dapat memproses pernyataan teks biasa.

Membuat kunci enkripsi pernyataan SAML workload identity federation

Bagian ini memandu Anda untuk membuat pasangan kunci asimetris yang memungkinkan workload identity federation untuk menerima pernyataan SAML yang terenkripsi.

Google Cloud menggunakan kunci pribadi untuk mendeskripsi pernyataan SAML yang menjadi masalah IdP Anda. Untuk membuat pasangan kunci asimetris yang akan digunakan dengan enkripsi SAML, jalankan perintah berikut. Untuk mempelajari lebih lanjut, lihat Algoritma enkripsi SAML yang didukung.
```
gcloud iam workload-identity-pools providers keys create KEY_ID \
    --workload-identity-pool WORKLOAD_POOL_ID \
    --provider PROVIDER_ID \
    --location global \
    --use encryption \
    --spec KEY_SPECIFICATION
```
Ganti kode berikut:
- KEY_ID: nama kunci yang Anda pilih
- WORKLOAD_POOL_ID: ID pool
- PROVIDER_ID: ID penyedia
- KEY_SPECIFICATION: spesifikasi kunci, yang dapat berupa salah satu dari rsa-2048, rsa-3072, dan rsa-4096.
Setelah membuat pasangan kunci, untuk mendownload kunci publik ke dalam file sertifikat, jalankan perintah berikut. Hanya workload identity federation yang memiliki akses ke kunci pribadi.
```
gcloud iam workload-identity-pools providers keys describe KEY_ID \
    --workload-identity-pool WORKLOAD_POOL_ID \
    --provider PROVIDER_ID \
    --location global \
    --format "value(keyData.key)" \
    > CERTIFICATE_PATH
```
Ganti kode berikut:
- KEY_ID: adalah nama kunci
- WORKLOAD_POOL_ID: ID pool
- PROVIDER_ID: ID penyedia
- CERTIFICATE_PATH: jalur untuk menulis sertifikat misalnya, saml-certificate.cer atau saml-certificate.pem
Mengonfigurasi IdP yang sesuai dengan SAML 2.0 untuk mengeluarkan pernyataan SAML terenkripsi

Konfigurasikan IdP SAML untuk menggunakan sertifikat publik yang didownload dari langkah terakhir untuk mengenkripsi pernyataan SAML yang dikeluarkan. Konsultasikan dengan tim IdP Anda untuk mendapatkan petunjuk khusus.

Setelah mengonfigurasi IdP untuk mengenkripsi pernyataan SAML, sebaiknya Anda memeriksa untuk memastikan bahwa pernyataan yang dihasilkan benar-benar dienkripsi. Bahkan dengan enkripsi pernyataan SAML yang dikonfigurasi, workload identity federation masih dapat memproses pernyataan teks biasa.

Menghapus kunci enkripsi workload identity federation
Untuk menghapus kunci enkripsi SAML, jalankan perintah berikut:
```
  gcloud iam workload-identity-pools providers keys delete KEY_ID \
      --workload-identity-pool WORKLOAD_POOL_ID \
      --provider PROVIDER_ID \
      --location global
```
Ganti kode berikut:
- KEY_ID: adalah nama kunci
- WORKLOAD_POOL_ID: ID pool
- PROVIDER_ID: ID penyedia
Algoritma enkripsi SAML yang didukung

Workload identity federation mendukung algoritma transpor utama berikut:
Workload identity federation mendukung algoritma enkripsi blok berikut:

Mengautentikasi workload

Langkah ini harus dilakukan satu kali untuk setiap workload.

Membuat akun layanan untuk workload eksternal

Aktifkan API IAM, Security Token Service, and Service Account Credentials.
Mengaktifkan API
Buat akun layanan yang merepresentasikan workload. Sebaiknya, gunakan akun layanan khusus untuk setiap workload.

Akun layanan tidak perlu berada dalam project yang sama dengan workload identity pool.
Berikan akses akun layanan untuk resource yang ingin diakses oleh identitas eksternal.

Mengizinkan workload eksternal untuk meniru identitas akun layanan

Agar identitas eksternal dapat meniru identitas akun layanan, berikan peran Pengguna Workload Identity ke identitas eksternal (roles/iam.workloadIdentityUser) pada akun layanan tersebut. Anda dapat memberikan peran ke identitas eksternal tertentu, atau ke beberapa identitas eksternal:

Untuk identitas eksternal tertentu, tulis kondisi atribut yang memeriksa atribut google.subject.
Untuk grup identitas eksternal, tulis kondisi atribut yang memeriksa atribut google.groups atau atribut khusus attribute.NAME.

Konsol

Agar identitas eksternal dapat meniru identitas akun layanan menggunakan Konsol Google Cloud, lakukan hal berikut:

Di Konsol Google Cloud, buka halaman Workload Identity Pool.

Buka Workload Identity Pool
Temukan workload identity pool yang ingin Anda perbarui lalu pilih pool tersebut.
Untuk memberikan akses ke workload identity pool yang dipilih, klik Berikan akses.
Dalam daftar Akun layanan, pilih akun layanan untuk ditiru oleh identitas eksternal.
Untuk memilih identitas dalam pool yang dapat meniru identitas akun layanan, lakukan salah satu tindakan berikut:
- Untuk mengizinkan hanya identitas tertentu dari workload identity pool untuk meniru identitas akun layanan, pilih Hanya identitas yang cocok dengan filter.
  
  Di daftar Nama atribut, pilih atribut yang ingin Anda filter.
  
  Di kolom Nilai atribut, masukkan nilai atribut yang diharapkan; contohnya, jika Anda menggunakan pemetaan atribut google.subject=assertion.sub, tetapkan namaAtribut menjadi subject dan Nilai atribut menjadi nilai klaim sub dalam token yang dikeluarkan oleh penyedia identitas eksternal Anda.
Untuk menyimpan konfigurasi, klik Simpan, lalu Tutup.

gcloud

Agar identitas eksternal dapat meniru identitas akun layanan menggunakan gcloud CLI, lakukan hal berikut:

Untuk memperoleh nomor project Anda saat ini, jalankan perintah berikut:

gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\)

Untuk memberikan peran Pemilik Workload Identity (roles/iam.workloadIdentityUser) ke identitas eksternal yang memenuhi kriteria tertentu:

Menurut subjek

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"

Menurut grup

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"

Menurut atribut

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"

Ganti kode berikut:

SERVICE_ACCOUNT_EMAIL: alamat email akun layanan
PROJECT_NUMBER: nomor project dari project yang berisi workload identity pool
POOL_ID: ID pool dari workload identity pool
SUBJECT: nilai yang diharapkan untuk atribut yang Anda petakan ke google.subject
GROUP: nilai yang diharapkan untuk atribut yang Anda petakan ke google.groups
ATTRIBUTE_NAME: nama atribut khusus dalam pemetaan atribut Anda

Membuat konfigurasi kredensial

Library Klien Cloud, gcloud CLI, dan Terraform dapat otomatis memperoleh kredensial eksternal, serta menggunakannya untuk meniru identitas akun layanan. Agar library dan alat dapat menyelesaikan proses ini, Anda harus menyediakan file konfigurasi kredensial. File ini menentukan:

Tempat Anda dapat memperoleh kredensial eksternal
Workload identity pool dan penyedia workload identity yang akan digunakan
Akun layanan yang akan ditiru

Library Klien Cloud mendapatkan kredensial eksternal dari file local, yaitu HTTP URL, dengan menjalankan file lokal yang dapat dieksekusi:

Kredensial dari file yang dapat dieksekusi: Library akan meluncurkan file yang dapat dieksekusi setiap kali mereka membutuhkan kredensial baru. Jika file yang dapat dieksekusi berhasilkan mendapatkan kredensial eksternal baru, file tersebut harus menulis dokumen JSON ke STDOUT yang terlihat sebagai berikut:
OIDC
```
{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}
```
Jika file yang dapat dieksekusi gagal mendapatkan kredensial baru, file tersebut harus menulis dokumen JSON ke STDOUT yang terlihat seperti berikut:
```
{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}
```
Dokumen JSON menggunakan kolom berikut:
- version: Versi output JSON. Hanya versi 1 yang didukung saat ini.
- success: Status respons.
  
  Saat true, respons harus berisi kolom id_token dan token_type. File yang dapat dieksekusi harus keluar dengan kode keluar 0.
  
  Saat false, respons harus berisi kolom code dan message serta keluar dengan nilai bukan nol.
- token_type: Jenis token kredensial eksternal. Nilai yang didukung adalah:
  - urn:ietf:params:oauth:token-type:id_token
  - urn:ietf:params:oauth:token-type:jwt
- id_token: Kredensial eksternal.
- expiration_time: Akhir masa berlaku token OIDC dalam detik (waktu epoch unix). Kolom ini hanya diperlukan jika file output telah ditentukan dalam konfigurasi kredensial.
- code: String kode error.
- message: Pesan error.
SAML
```
{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:saml2",
  "saml_response": "...",
  "expiration_time": 1620499962
}
```
Jika file yang dapat dieksekusi gagal mendapatkan kredensial baru, file tersebut harus menulis dokumen JSON ke STDOUT yang terlihat seperti berikut:
```
{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}
```
Dokumen JSON menggunakan kolom berikut:
- version: Versi output JSON. Hanya versi 1 yang didukung saat ini.
- success: Status respons.
  
  Saat true, respons harus berisi kolom id_token dan token_type. File yang dapat dieksekusi harus keluar dengan kode keluar 0.
  
  Saat false, respons harus berisi kolom code dan message serta keluar dengan nilai bukan nol.
- token_type: Jenis token kredensial eksternal. Harus berupa urn:ietf:params:oauth:token-type:saml2.
- saml_response: Respons SAML atau pernyataan SAML berenkode base64.
- expiration_time: Akhir masa berlaku pernyataan dalam detik (waktu epoch unix). Kolom ini hanya diperlukan jika file output telah ditentukan dalam konfigurasi kredensial.
- code: String kode error.
- message: Pesan error.
Saat meluncurkan file yang dapat dieksekusi, library klien menetapkan variabel lingkungan berikut:
- GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: Audiens dari konfigurasi kredensial. Selalu ada
- GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: Jenis token subjek yang diharapkan. Selalu ada
- GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL: Email akun layanan. Hanya ada jika peniruan akun layanan digunakan.
- GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: Lokasi file output dari konfigurasi kredensial. Hanya ada jika ditetapkan pada konfigurasi kredensial.
Untuk menggunakan kredensial dari file yang dapat dieksekusi, Anda harus menetapkan variabel lingkungan GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES ke 1.
Kredensial dari file: Library ini membaca kredensial eksternal dari teks biasa atau file JSON lokal. Contoh:
JSON
```
{
  "mytoken": "ey...
}
```
Teks
```
ey...
```
Kredensial eksternal dapat berupa:
- token OIDC
- respons SAML
- pertanyaan SAML berenkode base64
Anda harus mengupdate file secara berkala agar selalu berisi kredensial yang valid. Misalnya, jika token OIDC atau pernyataan SAML valid selama satu jam, Anda harus me-refresh file setidaknya sekali setiap jam.
Kredensial dari URL: Setiap kali memerlukan kredensial baru, library melakukan permintaan GET ke endpoint HTTP. Endpoint harus menampilkan teks biasa atau respons JSON yang setara dengan format yang digunakan oleh kredensial dari file.

Untuk membuat file konfigurasi kredensial, laukan hal berikut:

Kredensial dari file yang dapat dieksekusi

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --output-file=FILEPATH.json \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE

Ganti kode berikut:

PROJECT_NUMBER: Nomor project dari project yang berisi workload identity pool
POOL_ID: ID workload identity pool
PROVIDER_ID: ID penyedia workload identity pool
SERVICE_ACCOUNT_EMAIL: Alamat email akun layanan
SERVICE_ACCOUNT_TOKEN_LIFETIME: masa berlaku token akses akun layanan, dalam hitungan detik, default-nya adalah satu jam jika tidak disediakan. Untuk menentukan masa berlaku lebih lama satu jam, Anda harus mengonfigurasi constraints/iam.allowServiceAccountCredentialLifetimeExtension batasan kebijakan organisasi.
FILEPATH: File untuk menyimpan konfigurasi
EXECUTABLE_COMMAND: Perintah lengkap, termasuk argumen, akan dijalankan untuk mengambil token ID OIDC (misalnya --executable-command="/path/to/command --foo=bar")
EXECUTABLE_TIMEOUT: Durasi opsional dalam milidetik untuk menunggu file yang dapat dieksekusi untuk dijalankan (defaultnya adalah 30 detik)
EXECUTABLE_OUTPUT_FILE: Jalur file ini menunjuk ke kredensial 3PI yang dihasilkan oleh file yang dapat dieksekusi. Hal ini berguna untuk menyimpan kredensial dalam cache. Dengan menentukan jalur ini, library Auth akan memeriksa keberadaannya terlebih dahulu sebelum menjalankan file yang dapat dieksekusi.

Kredensial dari file

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --output-file=FILEPATH.json \
    --credential-source-file=TOKEN_FILEPATH \
    --credential-source-type=SOURCE_TYPE \
    --credential-source-field-name=FIELD_NAME

Ganti kode berikut:

PROJECT_NUMBER: Nomor project dari project yang berisi workload identity pool
POOL_ID: ID workload identity pool
PROVIDER_ID: ID penyedia workload identity pool
SERVICE_ACCOUNT_EMAIL: Alamat email akun layanan
SERVICE_ACCOUNT_TOKEN_LIFETIME: masa berlaku token akses akun layanan, dalam hitungan detik, default-nya adalah satu jam jika tidak disediakan. Untuk menentukan masa berlaku lebih lama satu jam, Anda harus mengonfigurasi constraints/iam.allowServiceAccountCredentialLifetimeExtension batasan kebijakan organisasi.
FILEPATH: File untuk menyimpan konfigurasi
TOKEN_FILEPATH: Jalur tempat token ID OIDC disimpan
SOURCE_TYPE: Format file token ID OIDC, ditetapkan ke text (default) atau json
FIELD_NAME: Kolom pada file teks berisi token (jika SOURCE_TYPE merupakan json)

Kredensial dari URL

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --output-file=FILEPATH.json \
    --credential-source-url="TOKEN_URL" \
    --credential-source-headers="KEY_1=VALUE_1,KEY_2=VALUE_2" \
    --credential-source-type=SOURCE_TYPE \
    --credential-source-field-name=FIELD_NAME

Ganti kode berikut:

PROJECT_NUMBER: Nomor project dari project yang berisi workload identity pool
POOL_ID: ID workload identity pool
PROVIDER_ID: ID penyedia workload identity pool
SERVICE_ACCOUNT_EMAIL: Alamat email akun layanan
SERVICE_ACCOUNT_TOKEN_LIFETIME: masa berlaku token akses akun layanan, dalam hitungan detik, default-nya adalah satu jam jika tidak disediakan. Untuk menentukan masa berlaku lebih lama satu jam, Anda harus mengonfigurasi constraints/iam.allowServiceAccountCredentialLifetimeExtension batasan kebijakan organisasi.
FILEPATH: File untuk menyimpan konfigurasi
TOKEN_URL: URL untuk mengambil token ID OIDC dari
KEY_n, VALUE_n: Header kustom yang disertakan ke permintaan HTTPS ke TOKEN_URL
SOURCE_TYPE: Format file token ID OIDC, ditetapkan ke text (default) atau json
FIELD_NAME: Kolom pada file teks berisi token (jika SOURCE_TYPE merupakan json)

Menggunakan konfigurasi kredensial untuk mengakses Google Cloud

Untuk mengizinkan alat dan library klien menggunakan konfigurasi kredensial Anda, lakukan hal berikut:

Lakukan inisialisasi variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS dan arahkan ke file konfigurasi kredensial:
Bash
```
  export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
  
```
dengan FILEPATH sebagai jalur file relatif ke file konfigurasi kredensial.
PowerShell
```
  $env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
  
```
dengan FILEPATH sebagai jalur file relatif ke file konfigurasi kredensial.
Gunakan library klien atau alat yang mendukung workload identity federation dan dapat menemukan kredensial secara otomatis:
C++
Library Klien Google Cloud untuk C++ mendukung penggabungan workload identity sejak versi v2.6.0. Untuk menggunakan workload identity federation, Anda harus membangun library klien dengan gRPC versi 1.36.0 atau yang lebih baru.
Go
Library klien untuk Go mendukung penggabungan identitas jika menggunakan modul golang.org/x/oauth2 versi v0.0.0-20210218202405-ba52d332ba99 atau versi lebih baru.

Untuk memeriksa versi modul yang digunakan library klien Anda, jalankan perintah berikut:
```
cd $GOPATH/src/cloud.google.com/go
go list -m golang.org/x/oauth2
```
Java
Library klien untuk Java mendukung penggabungan identitas jika menggunakan artefak com.google.auth:google-auth-library-oauth2-http versi 0.24.0 atau versi lebih baru.

Untuk memeriksa versi artefak yang digunakan library klien Anda, jalankan perintah Maven berikut di direktori aplikasi Anda:
```
mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http
```
Node.js
Library klien untuk Node.js mendukung workload identity federation jika menggunakan paket google-auth-library versi 7.0.2 atau versi lebih baru.

Untuk memeriksa versi paket yang digunakan library klien Anda, jalankan perintah berikut di direktori aplikasi Anda:
```
npm list google-auth-library
```
Saat membuat objek GoogleAuth, Anda dapat menentukan project ID atau mengizinkan GoogleAuth untuk otomatis menemukan project ID. Untuk otomatis menemukan project ID, akun layanan dalam file konfigurasi harus memiliki peran Browser (roles/browser), atau peran dengan izin yang setara, di project Anda. Untuk mengetahui detailnya, lihat README untuk paket google-auth-library.
Python
Library klien untuk Python mendukung penggabungan identitas jika menggunakan paket google-auth versi 1.27.0 atau versi lebih baru.

Untuk memeriksa versi paket yang digunakan library klien Anda, jalankan perintah berikut di lingkungan tempat paket diinstal:
```
pip show google-auth
```
Untuk menentukan project ID bagi klien autentikasi, Anda dapat menetapkan variabel lingkungan GOOGLE_CLOUD_PROJECT atau mengizinkan klien untuk otomatis menemukan project ID. Untuk otomatis menemukan project ID, akun layanan dalam file konfigurasi harus memiliki peran Browser (roles/browser), atau peran dengan izin yang setara, di project Anda. Untuk mengetahui detailnya, lihat panduan pengguna untuk paket google-auth.
gcloud
Untuk melakukan autentikasi menggunakan workload identity federation, gunakan perintah gcloud auth login:
```
gcloud auth login --cred-file=FILEPATH.json
```
Ganti FILEPATH dengan jalur file ke file konfigurasi kredensial.

Dukungan untuk workload identity federation di gcloud CLI tersedia di gcloud CLI versi 363.0.0 dan versi lebih baru.
Terraform
Penyedia Google Cloud mendukung workload identity federation jika Anda menggunakan versi 3.61.0 atau versi lebih baru:
```
terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 3.61.0"
    }
  }
}
```
gsutil
Untuk melakukan autentikasi menggunakan workload identity federation, gunakan salah satu metode berikut:

Saat Anda menggunakan gsutil bersamaan dengan gcloud, login seperti biasa:
```
gcloud auth login --cred-file=FILEPATH.json
```
Saat Anda menggunakan gsutil sebagai aplikasi command line mandiri, edit file .boto untuk menyertakan bagian berikut:
```
[Credentials]
gs_external_account_file = FILEPATH
```
Dalam kedua kasus tersebut, ganti FILEPATH dengan jalur file ke file konfigurasi kredensial.

Dukungan untuk workload identity federation di gsutil tersedia di gcloud CLI versi 379.0.0 dan versi lebih baru.
bq
Untuk melakukan autentikasi menggunakan workload identity federation, gunakan perintah gcloud auth login, sebagai berikut:
```
gcloud auth login --cred-file=FILEPATH.json
```
Ganti FILEPATH dengan jalur file ke file konfigurasi kredensial.

Dukungan untuk workload identity federation di bq tersedia di gcloud CLI versi 390.0.0 dan versi yang lebih baru.

Langkah selanjutnya

Baca selengkapnya mengenai workload identity federation.
Pelajari praktik terbaik untuk menggunakan workload identity federation.
Lihat cara mengelola workload identity pool dan penyedia workload identity.

Mengonfigurasi workload identity federation dengan penyedia identitas lain

Menyiapkan IdP eksternal Anda

OIDC

SAML

OIDC

SAML

Mengonfigurasi workload identity federation

Mengelola JWK OIDC (Opsional)

Membuat penyedia dan mengupload JWK OIDC

Perbarui JWK OIDC

Hapus semua JWK OIDC yang diupload

Menentukan pemetaan dan kondisi atribut

OIDC

SAML

OIDC

SAML

Membuat workload identity pool dan penyedia workload

Peran yang diperlukan

Konsol

OIDC

SAML

gcloud

OIDC

SAML

Opsional: Menerima pernyataan SAML terenkripsi dari IdP

Membuat kunci enkripsi pernyataan SAML workload identity federation

Mengonfigurasi IdP yang sesuai dengan SAML 2.0 untuk mengeluarkan pernyataan SAML terenkripsi

Menghapus kunci enkripsi workload identity federation

Algoritma enkripsi SAML yang didukung

Mengautentikasi workload

Membuat akun layanan untuk workload eksternal

Mengizinkan workload eksternal untuk meniru identitas akun layanan

Konsol

gcloud

Menurut subjek

Menurut grup

Menurut atribut

Membuat konfigurasi kredensial

OIDC

SAML

JSON

Teks

Kredensial dari file yang dapat dieksekusi

Kredensial dari file

Kredensial dari URL

Menggunakan konfigurasi kredensial untuk mengakses Google Cloud

Bash

PowerShell

C++

Go

Java

Node.js

Python

gcloud

Terraform

gsutil

bq

Langkah selanjutnya