Mengonfigurasi Workload Identity Federation dengan sertifikat X.509

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:

Sebelum memulai

Untuk mulai mengonfigurasi Workload Identity Federation, lakukan langkah berikut:

  1. Pastikan Anda memiliki izin yang diperlukan untuk menyelesaikan panduan ini.
  2. 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 izin resourcemanager.projects.create. Pelajari cara memberikan peran.

    Buka pemilih project

  3. Sebaiknya Anda menggunakan project khusus untuk mengelola workload identity pool dan penyedia workload.
  4. Pastikan penagihan diaktifkan untuk project Google Cloud Anda.

  5. 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.

    Aktifkan API

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk mengonfigurasi Workload Identity Federation, minta administrator Anda untuk memberikan peran IAM berikut pada project:

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:

  1. Buat file konfigurasi openssl untuk 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
    EOF
    
  2. Buat 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.cert
    
  3. Buat 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.req
    
  4. Buat 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.cert
    
  5. Buat 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.req
    
  6. Buat 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:

  1. 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')
    
  2. 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 seri
  • subject.dn.cn: nama umum subjek
  • subject.dn.o: nama organisasi subjek
  • subject.dn.ou: unit organisasi terakhir subjek
  • issuer.dn.cn: nama umum penerbit
  • issuer.dn.o: nama organisasi penerbit
  • issuer.dn.ou: unit organisasi terakhir penerbit
  • san.dns: nama DNS pertama dari nama alternatif subjek
  • san.uri: URI pertama nama alternatif subjek
  • sha256Fingerprint: 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

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

    Buka Penyedia workload dan workload pool baru

  2. 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.
  3. Klik Lanjutkan.

  4. Di bagian Add a provider to pool, lakukan hal berikut:

    1. Di Select a provider, pilih X509.
    2. Pada Nama penyedia, masukkan nama penyedia. Nama ini juga digunakan sebagai ID penyedia. Anda tidak dapat mengubah ID penyedia setelah penyedia dibuat.
    3. Di Trust anchors, masukkan sertifikat CA tepercaya Anda dalam format PEM. Sertifikat ini digunakan untuk memvalidasi rantai sertifikat klien.
    4. Opsional: Di Intermediate certificates, masukkan sertifikat CA perantara dalam format PEM untuk membantu membangun rantai kepercayaan penuh.
    5. Klik Lanjutkan.
  5. Di bagian Configure provider attributes, tambahkan pemetaan dan kondisi atribut yang telah Anda identifikasi sebelumnya.

  6. Klik Simpan.

gcloud

  1. 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.
  2. 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.

  1. Di konsol Google Cloud , buka halaman Buckets Cloud Storage.

    Buka Buckets

  2. Dalam daftar bucket, klik nama bucket yang ingin Anda beri peran.

  3. Pilih tab Permissions di dekat bagian atas halaman.

  4. Klik tombol Berikan akses.

    Dialog Add principals akan muncul.

  5. 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/SUBJECT
    

    Ganti kode berikut:

    • PROJECT_NUMBER: nomor project
    • POOL_ID: ID workload pool
    • SUBJECT: 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/GROUP
    

    Ganti kode berikut:

    • PROJECT_NUMBER: nomor project
    • WORKLOAD_POOL_ID: ID workload pool
    • GROUP: 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_VALUE
    

    Ganti kode berikut:

    • PROJECT_NUMBER: nomor project
    • WORKLOAD_POOL_ID: ID workload pool
    • ATTRIBUTE_NAME: salah satu atribut yang dipetakan dari IdP Anda
    • ATTRIBUTE_VALUE: nilai atribut
  6. 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.

  7. Klik Save.

gcloud

Untuk menggunakan gcloud CLI guna memberikan peran IAM pada resource dalam project, lakukan hal berikut:

  1. Dapatkan nomor project dari project tempat resource ditentukan.

    gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\)
    
  2. 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 akses
    • 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
    • ATTRIBUTE_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

  1. Untuk membuat akun layanan bagi workload eksternal, lakukan hal berikut:

    1. 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.

      Aktifkan API

    2. 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.

    3. Berikan akses akun layanan untuk resource yang ingin diakses oleh identitas eksternal.

  2. 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

  1. Untuk memberikan akses menggunakan peniruan akun layanan untuk akun layanan dalam project yang sama, lakukan hal berikut:

    1. Buka halaman Workload Identity Pools.

      Buka Workload Identity Pool

    2. Pilih Berikan akses.

    3. Dalam dialog Grant access to service account, pilih Grant access using Service Account impersonation.

    4. Dalam daftar Service accounts, pilih akun layanan untuk ditiru oleh identitas eksternal, dan lakukan hal berikut:

    5. 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 ke subject dan Attribute value ke nilai klaim sub dalam token yang dikeluarkan oleh penyedia identitas eksternal Anda.

    6. Untuk menyimpan konfigurasi, klik Simpan, lalu Tutup.

Akun layanan di project yang berbeda

  1. Untuk memberikan akses menggunakan peniruan akun layanan untuk akun layanan di project lain, lakukan hal berikut:

    1. Buka halaman Akun Layanan.

      Buka Akun Layanan

    2. Pilih akun layanan yang ingin Anda tiru.

    3. Klik Kelola akses.

    4. Klik Add principal.

    5. 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/SUBJECT
      

      Ganti kode berikut:

      • PROJECT_NUMBER: nomor project
      • POOL_ID: ID workload pool
      • SUBJECT: 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/GROUP
      

      Ganti kode berikut:

      • PROJECT_NUMBER: nomor project
      • WORKLOAD_POOL_ID: ID workload pool
      • GROUP: 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_VALUE
      

      Ganti kode berikut:

      • PROJECT_NUMBER: nomor project
      • WORKLOAD_POOL_ID: ID workload pool
      • ATTRIBUTE_NAME: salah satu atribut yang dipetakan dari IdP Anda
      • ATTRIBUTE_VALUE: nilai atribut

      Menurut pool

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*
      

      Ganti kode berikut:

      • PROJECT_NUMBER: nomor project
      • WORKLOAD_POOL_ID: ID workload pool
    6. Di Select a role, pilih peran Workload Identity User (roles/iam.workloadIdentityUser).

    7. 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 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
  • ATTRIBUTE_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

  1. Di konsol Google Cloud , buka halaman Workload Identity Pools.

    Buka Workload Identity Pool

  2. Klik nama pool yang berisi penyedia yang ingin Anda gunakan.

  3. Klik Berikan akses.

  4. Di panel Grant access to service account, pilih Grant access using identitas gabungan (Recommended).

  5. Klik Download config.

  6. 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.
  7. Untuk mendownload file ZIP yang berisi file Konfigurasi Kredensial dan Konfigurasi Sertifikat, klik Download konfigurasi.

  8. 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

  1. 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.json
    

    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.
    • 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.json

    • Windows: %APPDATA%\gcloud\certificate_config.json

Peniruan akun layanan

Untuk membuat file konfigurasi kredensial dan sertifikat dengan peniruan akun layanan, lakukan hal berikut:

Konsol

  1. Di konsol Google Cloud , buka halaman Workload Identity Pools.

    Buka Workload Identity Pool

  2. Klik nama pool yang berisi penyedia yang ingin Anda gunakan.

  3. Klik Berikan akses.

  4. Pilih Berikan akses menggunakan peniruan akun layanan.

  5. Pilih akun layanan yang ingin Anda tiru.

  6. Klik Download config.

  7. 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.
  8. Untuk mendownload file ZIP yang berisi file Konfigurasi Kredensial dan Konfigurasi Sertifikat, klik Download konfigurasi.

  9. 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

  1. 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.json
    

    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: 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 organisasi constraints/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.json

    • Windows: %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.

  1. Jika Anda mendownload file ZIP dari konsol Google Cloud , ekstrak file tersebut di workload eksternal Anda.

  2. 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.
  3. Lakukan inisialisasi variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS dan tetapkan ke file konfigurasi kredensial:

    Bash

      export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
      
    Ganti FILEPATH dengan jalur relatif ke file konfigurasi kredensial.

    PowerShell

      $env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
      
    Ganti FILEPATH dengan jalur relatif ke file konfigurasi kredensial.
  4. 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.json

      • Windows: %APPDATA%\gcloud\certificate_config.json

    • Jalur yang ditetapkan dalam variabel lingkungan GOOGLE_API_CERTIFICATE_CONFIG.

  5. 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/auth versi 0.16.0 atau yang lebih baru dan modul google.golang.org/api versi 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/api
    

    Python

    Library klien untuk Python mendukung Workload Identity Federation X.509 jika menggunakan paket google-auth versi 2.39.0 atau yang 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.

  6. Jika workload Anda berjalan di macOS, tetapkan CLOUDSDK_PYTHON_SITEPACKAGES=1 untuk mengonfigurasi gcloud CLI agar menggunakan library Python di luar direktori penginstalannya.

  7. Untuk melakukan autentikasi menggunakan gcloud CLI, jalankan perintah berikut:

    gcloud auth login --cred-file=FILEPATH.json
    

    Ganti FILEPATH dengan 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.

  1. 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)
    
  2. Buat daftar string berformat JSON yang dapat diteruskan sebagai subject_token dalam 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:

  1. 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 klien
    • CLIENT_CERT: Sertifikat klien
    • WORKLOAD_IDENTITY_POOL_URI: URL penyedia workload identity pool dalam format berikut:

      //iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

    • TRUST_CHAIN: Rantai kepercayaan yang diperlukan untuk memverifikasi sertifikat entitas akhir, harus menyertakan setidaknya CLIENT_CERT sebagai item pertama. Jika Anda mengikuti petunjuk di bagian Memformat sertifikat, ganti TRUST_CHAIN dengan '"${TRUST_CHAIN}"'

    Untuk menggunakan endpoint Security Token Service regional, ganti https://sts.mtls.googleapis.com/v1/token dengan berikut ini:

     https://sts.REGION.rep.mtls.googleapis.com/v1/token 

    Ganti REGION dengan lokasiGoogle Cloud , misalnya, us-central1 atau europe-west4.

  2. Opsional: Jika Anda menggunakan peniruan akun layanan, panggil metode generateAccessToken dari 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.
  3. 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