Workload Identity Federation memungkinkan Anda menggunakan sertifikat X.509 yang dikeluarkan oleh certificate authority (CA) Anda untuk melakukan autentikasi ke Google Cloud tanpa mengelola kunci akun layanan. Saat Anda mendaftarkan trust anchor dan CA perantara opsional, workload dapat menggunakan sertifikat klien melalui mutual TLS (mTLS) untuk mendapatkan kredensial jangka pendek untuk APIGoogle Cloud .
Konsep
Konsep federasi berbasis sertifikat X.509 mencakup hal berikut:
Trust anchor adalah sertifikat CA yang dianggap sebagai root of trust. Setiap rantai sertifikat klien harus dirantai ke salah satu trust anchor.
CA perantara adalah sertifikat CA opsional yang membantu membangun rantai sertifikat klien.
Trust store berisi sertifikat trust anchor dan sertifikat CA perantara yang digunakan untuk memvalidasi rantai sertifikat klien. CA menerbitkan sertifikat tepercaya untuk klien.
Anda dapat mengupload jenis sertifikat klien berikut ke trust store:
- Sertifikat yang diterbitkan oleh CA pihak ketiga pilihan Anda
- Sertifikat yang diterbitkan oleh CA pribadi Anda
- Sertifikat yang ditandatangani, seperti yang dijelaskan dalam Membuat sertifikat yang ditandatangani sendiri
Sebelum memulai
Untuk mulai mengonfigurasi Workload Identity Federation, lakukan langkah berikut:
- Pastikan Anda memiliki izin yang diperlukan untuk menyelesaikan panduan ini.
-
Di konsol Google Cloud , pada halaman pemilih project, pilih atau buat project Google Cloud .
Peran yang diperlukan untuk memilih atau membuat project
- Memilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project apa pun yang perannya telah diberikan kepada Anda.
-
Membuat project: Untuk membuat project, Anda memerlukan peran Project Creator
(
roles/resourcemanager.projectCreator), yang berisi izinresourcemanager.projects.create. Pelajari cara memberikan peran.
Sebaiknya Anda
menggunakan project khusus untuk mengelola workload identity pool dan penyedia workload.
-
Pastikan penagihan diaktifkan untuk project Google Cloud Anda.
Aktifkan API IAM, Resource Manager, Service Account Credentials, dan Security Token Service, jika belum diaktifkan.
Peran yang diperlukan untuk mengaktifkan API
Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda
membuat project, kemungkinan Anda sudah memiliki izin ini melalui
peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui
peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin).
Pelajari cara memberikan peran.
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) - Service Account Admin (
roles/iam.serviceAccountAdmin)
Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.
Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.
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.
Membuat trust store
Bagian ini menunjukkan cara membuat trust store. Pada tingkat tinggi, langkah-langkahnya adalah sebagai berikut:
Membuat sertifikat yang ditandatangani sendiri
Bagian ini menunjukkan cara membuat kunci dan membuat sertifikat yang ditandatangani. Jika sudah membuat sertifikat, Anda dapat melewati bagian ini dan melanjutkan ke Memformat sertifikat.
Bagian ini menggunakan perintah openssl untuk membuat root certificate dan intermediate certificate.
Untuk membuat root certificate dan intermediate certificate yang ditandatangani dengan kolom keyUsage dan extendedKeyUsage yang valid, lakukan hal berikut:
Buat file konfigurasi
openssluntuk membuat sertifikat penandatanganan Anda. Setidaknya, file tersebut mirip dengan yang berikut ini, tetapi Anda dapat menetapkan kolom tambahan sesuai kebutuhan.cat > example.cnf << EOF [req] distinguished_name = empty_distinguished_name [empty_distinguished_name] # Kept empty to allow setting via -subj command-line argument. [ca_exts] basicConstraints=critical,CA:TRUE keyUsage=keyCertSign extendedKeyUsage=clientAuth [leaf_exts] keyUsage=critical,Digital Signature, Key Encipherment basicConstraints=critical, CA:FALSE EOFBuat root certificate.
openssl req -x509 \ -new -sha256 -newkey rsa:2048 -nodes \ -days 3650 -subj '/CN=root' \ -config example.cnf \ -extensions ca_exts \ -keyout root.key -out root.certBuat permintaan penandatanganan untuk intermediate certificate.
openssl req \ -new -sha256 -newkey rsa:2048 -nodes \ -subj '/CN=int' \ -config example.cnf \ -extensions ca_exts \ -keyout int.key -out int.reqBuat intermediate certificate.
openssl x509 -req \ -CAkey root.key -CA root.cert \ -set_serial 1 \ -days 3650 \ -extfile example.cnf \ -extensions ca_exts \ -in int.req -out int.certBuat permintaan penandatanganan untuk sertifikat entitas akhir.
openssl req -new -sha256 -newkey rsa:2048 -nodes \ -subj '/CN=example' \ -config example.cnf \ -extensions leaf_exts \ -keyout leaf.key -out leaf.reqBuat sertifikat entitas akhir yang diterbitkan oleh perantara.
openssl x509 -req \ -CAkey int.key -CA int.cert \ -set_serial 1 -days 1 \ -extfile example.cnf \ -extensions leaf_exts \ -in leaf.req -out leaf.cert
Memformat sertifikat
Untuk menyertakan sertifikat baru atau yang sudah ada di trust store, format sertifikat menjadi string satu baris, dan simpan di variabel lingkungan. Sertifikat harus dalam format PEM. Untuk memformat sertifikat dan menyimpannya dalam variabel lingkungan, lakukan hal berikut:
Simpan root certificate sebagai string satu baris.
export ROOT_CERT=$(cat root.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')Simpan intermediate certificate sebagai string satu baris.
export INTERMEDIATE_CERT=$(cat int.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')
Membuat trust store
Di bagian ini, Anda akan membuat trust store menggunakan file berformat YAML yang berisi trust anchor dan CA perantara.
File ini berisi konten sertifikat dari variabel lingkungan yang Anda buat di bagian Memformat sertifikat. Untuk menambahkan trust anchor tambahan, tambahkan entri trustAnchors tambahan di bagian trustStore.
Untuk menambahkan sertifikat CA perantara tambahan, tambahkan entri intermediateCas tambahan di bagian trustStore.
Untuk membuat file trust store, jalankan perintah berikut:
cat << EOF > trust_store.yaml
trustStore:
trustAnchors:
- pemCertificate: "${ROOT_CERT}"
intermediateCas:
- pemCertificate: "${INTERMEDIATE_CERT}"
EOF
Menentukan pemetaan dan kondisi atribut
Sertifikat X.509 klien dapat berisi beberapa atribut.
Anda harus memilih atribut yang ingin digunakan sebagai ID subjek dengan memetakan
google.subject di Google Cloud ke atribut dari sertifikat Anda.
Misalnya, jika atribut dalam sertifikat adalah
nama umum subjek, pemetaannya akan seperti berikut:
google.subject=assertion.subject.dn.cn
Secara opsional, Anda dapat memetakan atribut tambahan. Selanjutnya, Anda dapat merujuk ke atribut ini saat memberikan akses ke resource.
Pemetaan atribut Anda dapat menggunakan atribut dalam sertifikat klien, termasuk yang berikut ini:
serialNumberHex: nomor serisubject.dn.cn: nama umum subjeksubject.dn.o: nama organisasi subjeksubject.dn.ou: unit organisasi terakhir subjekissuer.dn.cn: nama umum penerbitissuer.dn.o: nama organisasi penerbitissuer.dn.ou: unit organisasi terakhir penerbitsan.dns: nama DNS pertama dari nama alternatif subjeksan.uri: URI pertama nama alternatif subjeksha256Fingerprint: Hash sertifikat entitas akhir SHA256 (Base64)
Anda harus memetakan salah satu atribut ini ke google.subject untuk mengidentifikasi
subjek secara unik. Untuk melindungi dari ancaman spoofing, pilih atribut dengan nilai unik
yang tidak dapat diubah. Secara default, ID google.subject ditetapkan ke nama umum subjek sertifikat klien, assertion.subject.dn.cn.
Anda juga dapat menentukan kondisi atribut.
Kondisi atribut adalah ekspresi CEL yang dapat memeriksa atribut pernyataan dan atribut target. Jika kondisi atribut dievaluasi ke true untuk kredensial
tertentu, kredensial tersebut akan diterima. Jika tidak, kredensial akan ditolak.
Anda dapat menggunakan kondisi atribut untuk membatasi subjek yang dapat menggunakan Workload Identity Federation untuk mendapatkan token Google Cloudberumur singkat.
Misalnya, kondisi berikut membatasi akses ke sertifikat klien
yang berisi ID SPIFFE spiffe://example/path:
assertion.san.uri=="spiffe://example/path"
Mengonfigurasi Workload Identity Federation
Bagian ini menunjukkan cara mengonfigurasi workload identity pool dan penyedia workload identity pool. Anda hanya perlu melakukan langkah-langkah ini satu kali untuk setiap trust store. Anda kemudian dapat menggunakan workload identity pool dan penyedia workload identity yang sama untuk beberapa workload dan di beberapa project Google Cloud .
Membuat workload identity pool dan penyedia workload
Konsol
Di konsol Google Cloud , buka halaman Penyedia workload dan workload pool baru .
Di bagian Buat identity pool, masukkan:
- 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.
Di bagian Add a provider to pool, lakukan hal berikut:
- Di Select a provider, pilih X509.
- Pada Nama penyedia, masukkan nama penyedia. Nama ini juga digunakan sebagai ID penyedia. Anda tidak dapat mengubah ID penyedia setelah penyedia dibuat.
- Di Trust anchors, masukkan sertifikat CA tepercaya Anda dalam format PEM. Sertifikat ini digunakan untuk memvalidasi rantai sertifikat klien.
- Opsional: Di Intermediate certificates, masukkan sertifikat CA perantara dalam format PEM untuk membantu membangun rantai kepercayaan penuh.
- Klik Lanjutkan.
Di bagian Configure provider attributes, tambahkan pemetaan dan kondisi atribut yang telah Anda identifikasi sebelumnya.
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 poolDISPLAY_NAME: Nama poolDESCRIPTION: Deskripsi pool yang Anda pilih Deskripsi ini muncul saat Anda memberikan akses ke identitas pool.
Untuk menambahkan penyedia workload identity pool X.509, jalankan perintah berikut:
gcloud iam workload-identity-pools providers create-x509 PROVIDER_ID \ --location=global \ --workload-identity-pool="POOL_ID" \ --trust-store-config-path="TRUST_STORE_CONFIG" \ --attribute-mapping="MAPPINGS" \ --attribute-condition="CONDITIONS"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.TRUST_STORE_CONFIG: File YAML trust store.MAPPINGS: Daftar yang dipisahkan koma untuk pemetaan atribut yang telah Anda buat sebelumnya dalam dokumen ini. Misalnya,google.subject=assertion.subject.dn.cn.CONDITIONS: Opsional. Kondisi atribut yang Anda buat sebelumnya dalam dokumen ini. Hapus parameter jika Anda tidak memiliki kondisi atribut.
Mengonfigurasi Penerapan Kebijakan Akses Kontekstual untuk Workload Identity Federation
Anda dapat memperkuat keamanan resource terhadap serangan replay token dengan mengaktifkan Akses Kontekstual, yang menerapkan validasi mTLS untuk permintaan akses. Dalam proses ini, binding mTLS menggabungkan kebijakan berdasarkan konteks transpor dan menggunakan status sertifikat klien dalam sesi TLS untuk membuat keputusan otorisasi. Untuk workload identity federation X.509, binding mTLS memastikan bahwa seluruh alur autentikasi terikat dengan aman ke workload tepercaya. Hal ini mengurangi risiko pencurian kredensial, karena autentikasi terikat ke endpoint tertentu yang tepercaya.
Mengautentikasi workload
Langkah ini harus dilakukan satu kali untuk setiap workload.
Mengizinkan workload eksternal Anda mengakses resource Google Cloud
Untuk memberi workload Anda akses ke resource Google Cloud , sebaiknya berikan akses resource langsung ke akun utama. Dalam hal ini, principal-nya adalah pengguna gabungan. Beberapa produk Google Cloud memiliki batasan Google Cloud API. Jika workload Anda memanggil endpoint API yang memiliki batasan, Anda dapat menggunakan peniruan akun layanan. Dalam hal ini, akun utama adalah akun layananGoogle Cloud , yang bertindak sebagai identitas. Anda memberikan akses ke akun layanan pada resource.
Akses resource langsung
Anda dapat memberikan akses ke identitas gabungan langsung pada resource menggunakan konsol Google Cloud atau gcloud CLI.
Konsol
Untuk menggunakan konsol Google Cloud guna memberikan peran IAM
langsung pada resource, Anda harus membuka halaman resource, lalu
memberikan peran. Contoh berikut menunjukkan cara membuka halaman Cloud Storage dan memberikan peran Storage Object Viewer (roles/storage.objectViewer) ke identitas gabungan langsung di bucket Cloud Storage.
- Di konsol Google Cloud , buka halaman Buckets Cloud Storage.
Dalam daftar bucket, klik nama bucket yang ingin Anda beri peran.
Pilih tab Permissions di dekat bagian atas halaman.
Klik tombol add_box Berikan akses.
Dialog Add principals akan muncul.
Di kolom Akun utama baru, masukkan satu atau beberapa identitas yang memerlukan akses ke bucket Anda.
Menurut subjek
principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECTGanti kode berikut:
PROJECT_NUMBER: nomor projectPOOL_ID: ID workload poolSUBJECT: subjek individual yang dipetakan dari IdP Anda—misalnya,administrator@example.com
Menurut grup
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUPGanti kode berikut:
PROJECT_NUMBER: nomor projectWORKLOAD_POOL_ID: ID workload poolGROUP: grup yang dipetakan dari IdP Anda—misalnya:administrator-group@example.com
Menurut atribut
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUEGanti kode berikut:
PROJECT_NUMBER: nomor projectWORKLOAD_POOL_ID: ID workload poolATTRIBUTE_NAME: salah satu atribut yang dipetakan dari IdP AndaATTRIBUTE_VALUE: nilai atribut
Pilih satu (atau beberapa) peran dari menu drop-down Select a role. Peran yang Anda pilih akan muncul di panel dengan deskripsi singkat tentang izin yang diberikan.
Klik Save.
gcloud
Untuk menggunakan gcloud CLI guna memberikan peran IAM pada resource dalam project, lakukan hal berikut:
Dapatkan nomor project dari project tempat resource ditentukan.
gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\)
Memberikan akses ke resource.
Untuk menggunakan gcloud CLI guna memberikan peran Storage Object Viewer (
roles/storage.objectViewer) ke identitas eksternal yang memenuhi kriteria tertentu, jalankan perintah berikut.Menurut subjek
gcloud storage buckets add-iam-policy-binding BUCKET_ID \ --role=roles/storage.objectViewer \ --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"Menurut grup
gcloud storage buckets add-iam-policy-binding BUCKET_ID \ --role=roles/storage.objectViewer \ --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"Menurut atribut
gcloud storage buckets add-iam-policy-binding BUCKET_ID \ --role=roles/storage.objectViewer \ --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"Ganti kode berikut:
BUCKET_ID: bucket yang akan diberi aksesPROJECT_NUMBER: nomor project. dari project yang berisi workload identity poolPOOL_ID: ID pool dari workload identity poolSUBJECT: nilai yang diharapkan untuk atribut yang Anda petakan kegoogle.subjectGROUP: nilai yang diharapkan untuk atribut yang Anda petakan kegoogle.groupsATTRIBUTE_NAME: nama atribut khusus dalam pemetaan atribut AndaATTRIBUTE_VALUE: nilai atribut kustom dalam pemetaan atribut Anda
Anda dapat memberikan peran pada resource Google Cloud apa pun yang mendukung kebijakan izin IAM.
Peniruan akun layanan
Untuk membuat akun layanan bagi workload eksternal, lakukan hal berikut:
Aktifkan IAM, Security Token Service, dan Service Account Credentials API, jika belum diaktifkan.
Peran yang diperlukan untuk mengaktifkan API
Untuk mengaktifkan API, Anda memerlukan izin
serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.Buat akun layanan yang merepresentasikan workload. Sebaiknya Anda menggunakan akun layanan khusus untuk setiap workload. Akun layanan tidak perlu berada dalam project yang sama dengan workload identity pool, tetapi Anda harus merujuk ke project yang berisi akun layanan.
Berikan akses akun layanan untuk resource yang ingin diakses oleh identitas eksternal.
Agar identitas gabungan dapat meniru akun layanan, lakukan hal berikut:
Konsol
Untuk menggunakan konsol Google Cloud guna memberikan peran IAM ke identitas gabungan dengan akun layanan, lakukan hal berikut:
Akun Layanan dalam project yang sama
Untuk memberikan akses menggunakan peniruan akun layanan untuk akun layanan dalam project yang sama, lakukan hal berikut:
Buka halaman Workload Identity Pools.
Pilih Berikan akses.
Dalam dialog Grant access to service account, pilih Grant access using Service Account impersonation.
Dalam daftar Service accounts, pilih akun layanan untuk ditiru oleh identitas eksternal, dan lakukan hal berikut:
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 Attribute value, masukkan nilai atribut yang diharapkan; misalnya, jika Anda menggunakan pemetaan atribut
google.subject=assertion.sub, tetapkan nama Attribute kesubjectdan Attribute value ke nilai klaimsubdalam token yang dikeluarkan oleh penyedia identitas eksternal Anda.
Untuk menyimpan konfigurasi, klik Simpan, lalu Tutup.
Akun layanan di project yang berbeda
Untuk memberikan akses menggunakan peniruan akun layanan untuk akun layanan di project lain, lakukan hal berikut:
Buka halaman Akun Layanan.
Pilih akun layanan yang ingin Anda tiru.
Klik Kelola akses.
Klik Add principal.
Di kolom New principal, masukkan salah satu principal identifier berikut untuk identitas dalam pool Anda yang akan meniru identitas akun layanan.
Menurut subjek
principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECTGanti kode berikut:
PROJECT_NUMBER: nomor projectPOOL_ID: ID workload poolSUBJECT: subjek individual yang dipetakan dari IdP Anda—misalnya,administrator@example.com
Menurut grup
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUPGanti kode berikut:
PROJECT_NUMBER: nomor projectWORKLOAD_POOL_ID: ID workload poolGROUP: grup yang dipetakan dari IdP Anda—misalnya:administrator-group@example.com
Menurut atribut
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUEGanti kode berikut:
PROJECT_NUMBER: nomor projectWORKLOAD_POOL_ID: ID workload poolATTRIBUTE_NAME: salah satu atribut yang dipetakan dari IdP AndaATTRIBUTE_VALUE: nilai atribut
Menurut pool
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*Ganti kode berikut:
PROJECT_NUMBER: nomor projectWORKLOAD_POOL_ID: ID workload pool
Di Select a role, pilih peran Workload Identity User (
roles/iam.workloadIdentityUser).Untuk menyimpan konfigurasi, klik Save.
gcloud
Untuk memberikan peran Workload Identity User (roles/iam.workloadIdentityUser)
ke akun utama atau set akun utama gabungan, jalankan perintah
berikut. Untuk mempelajari lebih lanjut ID utama Workload Identity Federation, lihat Jenis akun utama.
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 layananPROJECT_NUMBER: nomor project. dari project yang berisi workload identity poolPOOL_ID: ID pool dari workload identity poolSUBJECT: nilai yang diharapkan untuk atribut yang Anda petakan kegoogle.subjectGROUP: nilai yang diharapkan untuk atribut yang Anda petakan kegoogle.groupsATTRIBUTE_NAME: nama atribut khusus dalam pemetaan atribut AndaATTRIBUTE_VALUE: nilai atribut kustom dalam pemetaan atribut Anda
Mendownload atau membuat konfigurasi kredensial
Library Klien Cloud dan gcloud CLI dapat otomatis memperoleh kredensial eksternal dan menggunakannya untuk meniru identitas akun layanan. Agar library dan alat dapat menyelesaikan proses ini, Anda harus menyediakan file konfigurasi kredensial.
Selain itu, untuk penggabungan sertifikat X.509, file konfigurasi sertifikat diperlukan.
File konfigurasi mencakup hal berikut:
- Konfigurasi Kredensial: File JSON yang menentukan cara library klien berinteraksi dengan Security Token Service (STS).
- Konfigurasi Sertifikat: File JSON yang menentukan jalur lokal untuk sertifikat klien dan kunci pribadi di workload Anda.
Buat file konfigurasi kredensial dan sertifikat yang memungkinkan library memperoleh token akses menggunakan sertifikat X.509.
Akses resource langsung
Untuk membuat file konfigurasi kredensial dan sertifikat untuk akses resource langsung, lakukan hal berikut:
Konsol
Di konsol Google Cloud , buka halaman Workload Identity Pools.
Klik nama pool yang berisi penyedia yang ingin Anda gunakan.
Klik Berikan akses.
Di panel Grant access to service account, pilih Grant access using identitas gabungan (Recommended).
Klik Download config.
Di bagian Configure your application, pilih penyedia yang berisi identitas eksternal dan berikan setelan berikut:
- Client certificate path: Jalur lokal ke file sertifikat klien Anda.
- Client private key path: Jalur lokal ke file kunci pribadi klien Anda.
- Jalur rantai kepercayaan: (Opsional) Jalur file rantai kepercayaan yang berisi sertifikat klien dan intermediate certificate apa pun yang diperlukan untuk pencarian sertifikat, tetapi tidak dikonfigurasi di penyedia X.509.
Untuk mendownload file ZIP yang berisi file Konfigurasi Kredensial dan Konfigurasi Sertifikat, klik Download konfigurasi.
Klik Tutup.
Jika Anda ingin menggunakan endpoint regional Security Token Service—misalnya,
https://sts.us-central1.rep.mtls.googleapis.com, lihat
Menggunakan endpoint Security Token Service regional untuk keandalan yang lebih baik.
gcloud
Untuk membuat file konfigurasi kredensial dan sertifikat untuk akses resource langsung menggunakan
gcloud iam workload-identity-pools create-cred-config, jalankan perintah berikut:gcloud iam workload-identity-pools create-cred-config \ projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \ --credential-cert-path=CLIENT_CERT_PATH \ --credential-cert-private-key-path=CLIENT_PRIVATE_KEY_PATH \ --credential-cert-trust-chain-path=TRUST_CHAIN_PATH \ --sts-location=REGION \ --output-file=FILEPATH.jsonGanti 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.CLIENT_CERT_PATH: Jalur file sertifikat klien.CLIENT_PRIVATE_KEY_PATH: Jalur file kunci pribadi sertifikat klien.TRUST_CHAIN_PATH: Opsional. Jalur file rantai kepercayaan yang berisi sertifikat klien dan sertifikat perantara apa pun yang diperlukan untuk pencarian sertifikat, tetapi tidak dikonfigurasi di penyedia X.509.REGION: Opsional. Tentukan region endpoint Security Token Service regional, jika tersedia.FILEPATH: File untuk menyimpan konfigurasi.
Menjalankan perintah ini juga akan membuat file konfigurasi sertifikat dan menyimpannya di lokasi gcloud CLI default:
Linux dan macOS:
~/.config/gcloud/certificate_config.jsonWindows:
%APPDATA%\gcloud\certificate_config.json
Peniruan akun layanan
Untuk membuat file konfigurasi kredensial dan sertifikat dengan peniruan akun layanan, lakukan hal berikut:
Konsol
Di konsol Google Cloud , buka halaman Workload Identity Pools.
Klik nama pool yang berisi penyedia yang ingin Anda gunakan.
Klik Berikan akses.
Pilih Berikan akses menggunakan peniruan akun layanan.
Pilih akun layanan yang ingin Anda tiru.
Klik Download config.
Dalam dialog Configure your application, berikan setelan berikut:
- Client certificate path: Jalur lokal ke file sertifikat klien Anda.
- Client private key path: Jalur lokal ke file kunci pribadi klien Anda.
- Jalur rantai kepercayaan: (Opsional) Jalur file rantai kepercayaan yang berisi sertifikat klien dan intermediate certificate apa pun yang diperlukan untuk pencarian sertifikat, tetapi tidak dikonfigurasi di penyedia X.509.
Untuk mendownload file ZIP yang berisi file Konfigurasi Kredensial dan Konfigurasi Sertifikat, klik Download konfigurasi.
Klik Tutup.
Jika Anda ingin menggunakan endpoint regional Security Token Service—misalnya,
https://sts.us-central1.rep.mtls.googleapis.com, lihat
Menggunakan endpoint Security Token Service regional untuk keandalan yang lebih baik.
gcloud
Untuk membuat file konfigurasi kredensial dan sertifikat dengan peniruan akun layanan menggunakan
gcloud iam workload-identity-pools create-cred-config, jalankan perintah berikut: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 \ --credential-cert-path=CLIENT_CERT_PATH \ --credential-cert-private-key-path=CLIENT_PRIVATE_KEY_PATH \ --credential-cert-trust-chain-path=TRUST_CHAIN_PATH \ --sts-location=REGION \ --output-file=FILEPATH.jsonGanti 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: Jika Anda menggunakan peniruan akun layanan, ganti SERVICE_ACCOUNT_EMAIL dengan alamat email akun layanan.SERVICE_ACCOUNT_TOKEN_LIFETIME: Masa aktif token akses akun layanan, dalam detik, jika Anda menggunakan peniruan akun layanan. Jika dihilangkan, masa aktif ini ditetapkan secara default ke satu jam. Hilangkan flag ini jika Anda tidak menggunakan peniruan akun layanan. Untuk menentukan masa aktif agar lebih lama dari satu jam, Anda harus mengonfigurasi batasan kebijakan organisasiconstraints/iam.allowServiceAccountCredentialLifetimeExtension.CLIENT_CERT_PATH: Jalur file sertifikat klien.CLIENT_PRIVATE_KEY_PATH: Jalur file kunci pribadi sertifikat klien.TRUST_CHAIN_PATH: Opsional. Jalur file rantai kepercayaan yang berisi sertifikat klien dan sertifikat perantara apa pun yang diperlukan untuk pencarian sertifikat, tetapi tidak dikonfigurasi di penyedia X.509.REGION: Opsional. Tentukan region endpoint Security Token Service regional, jika tersedia.FILEPATH: File untuk menyimpan konfigurasi.
Menjalankan perintah ini juga akan membuat file konfigurasi sertifikat dan menyimpannya di lokasi Google Cloud CLI default:
Linux dan macOS:
~/.config/gcloud/certificate_config.jsonWindows:
%APPDATA%\gcloud\certificate_config.json
Menggunakan konfigurasi kredensial untuk mengakses Google Cloud
Agar alat dan library klien dapat menggunakan konfigurasi kredensial Anda, lakukan hal berikut. Untuk mempelajari lebih lanjut Kredensial Default Aplikasi, lihat Cara kerja Kredensial Default Aplikasi.
Jika Anda mendownload file ZIP dari konsol Google Cloud , ekstrak file tersebut di workload eksternal Anda.
Perbarui file Certificate Configuration dengan jalur file lokal yang sebenarnya untuk sertifikat klien dan kunci pribadi Anda untuk kolom berikut:
cert_path: Jalur ke sertifikat klien Anda.key_path: Jalur ke kunci pribadi Anda.
Lakukan inisialisasi variabel lingkungan
GOOGLE_APPLICATION_CREDENTIALSdan tetapkan ke file konfigurasi kredensial:Bash
Gantiexport GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
FILEPATHdengan jalur relatif ke file konfigurasi kredensial.PowerShell
Ganti$env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
FILEPATHdengan jalur relatif ke file konfigurasi kredensial.Pastikan library klien dapat menemukan file konfigurasi sertifikat. File konfigurasi sertifikat terletak di salah satu jalur berikut:
Jalur tempat Anda mengekstrak file ZIP. (jika Anda mendownload konfigurasi dari konsol Google Cloud ).
Jalur gcloud CLI default:
Linux dan macOS:
~/.config/gcloud/certificate_config.jsonWindows:
%APPDATA%\gcloud\certificate_config.json
Jalur yang ditetapkan dalam variabel lingkungan
GOOGLE_API_CERTIFICATE_CONFIG.
Gunakan Library Klien Cloud berikut yang mendukung Workload Identity Federation dengan sertifikat X.509.
Go
Library klien untuk Go mendukung Workload Identity Federation X.509 jika menggunakan modul
cloud.google.com/go/authversi 0.16.0 atau yang lebih baru dan modulgoogle.golang.org/apiversi 0.189.0.Untuk memeriksa versi modul yang digunakan library klien Anda, jalankan perintah berikut saat berada di direktori yang berisi file go.mod untuk modul Anda:
go list -m cloud.google.com/go/auth go list -m cloud.google.com/apiPython
Library klien untuk Python mendukung Workload Identity Federation X.509 jika menggunakan paket
google-authversi 2.39.0 atau yang lebih baruUntuk memeriksa versi paket yang digunakan library klien Anda, jalankan perintah berikut di lingkungan tempat paket diinstal:
pip show google-authUntuk menentukan project ID bagi klien autentikasi, Anda dapat menetapkan variabel lingkungan
GOOGLE_CLOUD_PROJECTatau 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 paketgoogle-auth.Jika workload Anda berjalan di macOS, tetapkan
CLOUDSDK_PYTHON_SITEPACKAGES=1untuk mengonfigurasi gcloud CLI agar menggunakan library Python di luar direktori penginstalannya.Untuk melakukan autentikasi menggunakan gcloud CLI, jalankan perintah berikut:
gcloud auth login --cred-file=FILEPATH.json
Ganti
FILEPATHdengan jalur ke file konfigurasi kredensial.Dukungan untuk Workload Identity Federation X.509 di gcloud CLI tersedia di gcloud CLI versi 538.0 dan versi yang lebih baru.
Mendapatkan token akses menggunakan permintaan biasa untuk mengakses Google Cloud
Membuat rantai kepercayaan
Langkah ini menunjukkan cara membuat rantai kepercayaan. Anda meneruskan rantai kepercayaan di kolom subject_token saat memanggil Security Token Service dalam permintaan biasa.
Format sertifikat yang perlu disertakan dalam rantai sebagai daftar berformat JSON seperti yang ditentukan dalam RFC 7515. Sertifikat entitas akhir yang digunakan untuk handshake mTLS harus ditentukan sebagai item pertama. Setiap sertifikat dalam paket harus berupa string berenkode base64.
Simpan sertifikat entitas akhir dan intermediate certificate ke string berenkode base64.
export LEAF_CERT=$(openssl x509 -in leaf.cert -out leaf.der -outform DER && cat leaf.der | openssl enc -base64 -A)export INTERMEDIATE_CERT=$(openssl x509 -in int.cert -out int.der -outform DER && cat int.der | openssl enc -base64 -A)Buat daftar string berformat JSON yang dapat diteruskan sebagai
subject_tokendalam panggilan ke Security Token Service, nanti dalam panduan ini.export TRUST_CHAIN="[\\\"${LEAF_CERT}\\\", \\\"${INTERMEDIATE_CERT}\\\"]"
Mendapatkan token akses
Untuk mendapatkan token akses, lakukan hal berikut:
Lakukan pertukaran token dengan mTLS dan sertifikat klien:
curl --key CLIENT_CERT_KEY \ --cert CLIENT_CERT \ --request POST 'https://sts.mtls.googleapis.com/v1/token' \ --header "Content-Type: application/json" \ --data-raw '{ "subject_token_type": "urn:ietf:params:oauth:token-type:mtls", "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange", "audience": "WORKLOAD_IDENTITY_POOL_URI", "requested_token_type": "urn:ietf:params:oauth:token-type:access_token", "scope": "https://www.googleapis.com/auth/cloud-platform", "subject_token": "TRUST_CHAIN" }'Ganti kode berikut:
CLIENT_CERT_KEY: Kunci pribadi sertifikat klienCLIENT_CERT: Sertifikat klienWORKLOAD_IDENTITY_POOL_URI: URL penyedia workload identity pool dalam format berikut://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_IDTRUST_CHAIN: Rantai kepercayaan yang diperlukan untuk memverifikasi sertifikat entitas akhir, harus menyertakan setidaknyaCLIENT_CERTsebagai item pertama. Jika Anda mengikuti petunjuk di bagian Memformat sertifikat, gantiTRUST_CHAINdengan'"${TRUST_CHAIN}"'
Untuk menggunakan endpoint Security Token Service regional, ganti
https://sts.mtls.googleapis.com/v1/tokendengan berikut ini:https://sts.REGION.rep.mtls.googleapis.com/v1/token
Ganti
REGIONdengan lokasiGoogle Cloud , misalnya,us-central1ataueurope-west4.Opsional: Jika Anda menggunakan peniruan akun layanan, panggil metode
generateAccessTokendari IAM Service Account Credentials API dengan token dari Security Token Service untuk mendapatkan token akses.curl -X POST 'https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateAccessToken' \ -H "Content-Type: application/json; charset=utf-8" \ -H "Authorization: Bearer STS_TOKEN" \ -d '{"scope": ["https://www.googleapis.com/auth/cloud-platform"]}'Ganti kode berikut:
SERVICE_ACCOUNT_EMAIL: alamat email akun layanan.STS_TOKEN: Token akses yang dihasilkan oleh Security Token Service pada langkah sebelumnya.
Gunakan token akses pemilik untuk mengakses resourceGoogle Cloud —misalnya:
curl -X GET 'https://storage.googleapis.com/my_object' -H "Authorization: Bearer $ACCESS_TOKEN"
Batas
Tabel berikut mencantumkan batas.
| Item | Batas | Catatan |
|---|---|---|
| Jumlah trust anchor | 3 | Setiap sertifikat tidak boleh melebihi 32 KB. |
| Jumlah intermediate certificate | 10 | Setiap sertifikat tidak boleh melebihi 32 KB. |
| Jumlah batasan nama yang diizinkan selama validasi root certificate dan intermediate certificate | 10 | |
| Intermediate certificate yang memiliki informasi Subjek dan Kunci Publik Subjek yang sama | 5 | Batas ini berlaku untuk setiap trust store. |
| Kedalaman rantai sertifikat | 5 | Kedalaman maksimum untuk rantai sertifikat, termasuk sertifikat root dan sertifikat klien. |
| Frekuensi intermediate certificate dapat dievaluasi saat mencoba membangun rantai kepercayaan | 100 | |
| Kunci sertifikat yang diupload dan diteruskan dari klien | Kunci RSA dapat berkisar dari 2048 hingga 4096 bit. Sertifikat ECDSA harus menggunakan kurva P-256 atau P-384. |
RSA-2048 dan P-256 direkomendasikan untuk kasus penggunaan normal, gunakan yang lain untuk praktik keamanan terbaik. |
| Masa berlaku maksimum sertifikat entitas akhir | 390 hari. | Sertifikat dengan masa berlaku lebih dari 390 hari akan berhenti berfungsi setelah berlaku selama lebih dari 390 hari. |
Langkah berikutnya
- Baca selengkapnya tentang Workload Identity Federation.
- Pelajari praktik terbaik untuk menggunakan Workload Identity Federation.
- Lihat cara mengelola workload identity pool dan penyedia workload identity.