Mengonfigurasi Workload Identity Federation dengan sertifikat X.509

Panduan ini menjelaskan cara menggunakan Workload Identity Federation dengan sertifikat X.509 yang diterbitkan oleh certificate authority (CA) Anda untuk melakukan autentikasi ke Trusted Cloud dan mengakses Trusted Cloud resource.

Jika workload Anda memiliki sertifikat klien mTLS, Anda dapat melakukan autentikasi ke Trusted Cloud dengan mendaftarkan satu atau beberapa CA ke Workload Identity Federation sebagai anchor tepercaya. Anda juga dapat mendaftarkan CA perantara.

Dengan menggunakan Workload Identity Federation, Anda dapat mengizinkan workload ini mendapatkan kredensial Trusted Cloud dengan masa aktif singkat melalui koneksi TLS timbal balik (mTLS). Workload dapat menggunakan kredensial jangka pendek ini untuk mengakses Trusted Cloud API.

Konsep

Konsep federasi berbasis sertifikat X.509 mencakup hal berikut:

• Anchor kepercayaan adalah sertifikat CA yang dianggap sebagai root kepercayaan. Semua rantai sertifikat klien harus dirantai hingga salah satu anchor tepercaya.

• CA perantara adalah sertifikat certificate authority 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 hal berikut:

1. In the Trusted Cloud console, on the project selector page, select or create a Trusted Cloud project.

   Go to project selector

Sebaiknya Anda menggunakan project khusus untuk mengelola workload identity pool dan penyedia workload.

2. Verify that billing is enabled for your Trusted Cloud project.

3. Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.

   Enable the APIs

Peran yang diperlukan

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

• Admin Workload Identity Pool (roles/iam.workloadIdentityPoolAdmin)
• Service Account Admin (roles/iam.serviceAccountAdmin)

Untuk mengetahui informasi selengkapnya tentang cara memberikan 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 penyimpanan tepercaya

Bagian ini menunjukkan cara membuat penyimpanan tepercaya. Pada tingkat tinggi, langkah-langkahnya adalah sebagai berikut:

• Membuat sertifikat yang ditandatangani sendiri
• Memformat sertifikat
• Membuat penyimpanan tepercaya

Membuat sertifikat yang ditandatangani sendiri

Bagian ini menunjukkan cara membuat kunci dan membuat sertifikat bertanda tangan. Jika sudah membuat sertifikat, Anda dapat melewati bagian ini dan melanjutkan ke Memformat sertifikat.

Bagian ini menggunakan perintah openssl untuk membuat sertifikat root dan sertifikat perantara.

Untuk membuat sertifikat root dan sertifikat perantara bertanda tangan dengan kolom keyUsage dan extendedKeyUsage yang valid, lakukan langkah-langkah berikut:

1. Buat file konfigurasi openssl untuk membuat sertifikat penandatanganan Anda. Setidaknya, file tersebut mirip dengan yang berikut, 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 sertifikat root.

   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 sertifikat perantara.

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

   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 leaf yang dikeluarkan oleh sertifikat perantara.

   openssl x509 -req \
       -CAkey int.key -CA int.cert \
       -set_serial 1 -days 3650 \
       -extfile example.cnf \
       -extensions leaf_exts \
       -in leaf.req -out leaf.cert
   

Memformat sertifikat

Untuk menyertakan sertifikat baru atau yang sudah ada dalam trust store, format sertifikat menjadi string satu baris, lalu simpan di variabel lingkungan. Sertifikat harus diformat PEM. Untuk memformat sertifikat dan menyimpannya dalam variabel lingkungan, lakukan langkah berikut:

1. Simpan sertifikat root 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 sertifikat perantara sebagai string satu baris.

   export INTERMEDIATE_CERT=$(cat int.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')
   

Buat penyimpanan tepercaya

Di bagian ini, Anda akan membuat trust store menggunakan file berformat YAML yang berisi anchor tepercaya dan CA perantara Anda.

File ini berisi konten sertifikat dari variabel lingkungan yang Anda buat di Memformat sertifikat. Untuk menambahkan anchor tepercaya 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 mana yang ingin digunakan sebagai ID subjek dengan memetakan google.subject di Trusted Cloud ke atribut dari sertifikat Anda. Misalnya, jika atribut dalam sertifikat adalah nama umum subjek, pemetaannya adalah sebagai 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 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 leaf 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 disetel ke nama umum subjek sertifikat klien, assertion.subject.dn.cn.

Secara opsional, Anda 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 Trusted Cloud dengan masa berlaku singkat.

Misalnya, kondisi berikut membatasi akses ke sertifikat klien yang berisi SPIFFE ID 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 penyimpanan tepercaya. Kemudian, Anda dapat menggunakan workload identity pool dan penyedia workload yang sama untuk beberapa workload dan di beberapa project. Trusted Cloud

Buat workload identity pool

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.

Buat penyedia workload identity pool

1. 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 panduan ini. Misalnya, google.subject=assertion.subject.dn.cn.
   • CONDITIONS: Opsional. Kondisi atribut yang Anda buat sebelumnya dalam panduan ini. Hapus parameter jika Anda tidak memiliki kondisi atribut.

Mengautentikasi workload

Langkah ini harus dilakukan satu kali untuk setiap workload.

Mengizinkan workload eksternal Anda mengakses resource Trusted Cloud

Untuk memberikan akses workload Anda ke resource Trusted Cloud , sebaiknya Anda memberikan akses resource langsung ke principal. Dalam hal ini, pokoknya adalah pengguna gabungan. Beberapa produk Trusted Cloud memiliki batasan Google Cloud API. Jika beban kerja Anda memanggil endpoint API yang memiliki batasan, Anda dapat menggunakan peniruan identitas akun layanan. Dalam hal ini, akun utama adalah akun layananTrusted Cloud , yang bertindak sebagai identitas. Anda memberikan akses ke akun layanan pada resource.

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"

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"

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"

Mendownload atau membuat konfigurasi kredensial

Library Klien Cloud dan gcloud CLI dapat otomatis memperoleh kredensial eksternal dan menggunakan kredensial ini untuk meniru identitas akun layanan. Agar library dan alat dapat menyelesaikan proses ini, Anda harus menyediakan file konfigurasi kredensial. File ini memberikan informasi berikut:

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

Selain itu, untuk federasi sertifikat X.509, file konfigurasi sertifikat diperlukan. File ini berisi jalur ke file sertifikat klien X.509 dan kunci pribadi.

Buat file konfigurasi kredensial dan sertifikat yang memungkinkan library memperoleh token akses menggunakan sertifikat X.509.

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 \
    --output-file=FILEPATH.json

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_KEY_PATH \
    --credential-cert-trust-chain-path=TRUST_CHAIN_PATH \
    --output-file=FILEPATH.json

Menggunakan konfigurasi kredensial untuk mengakses Trusted 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. 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.

2. Pastikan library klien dapat menemukan file konfigurasi sertifikat. File konfigurasi sertifikat terletak di salah satu jalur berikut:

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

3. Gunakan Library Klien Cloud berikut yang mendukung Workload Identity Federation dengan sertifikat X.509.

   Go

   Library klien untuk Go mendukung X.509 Workload Identity Federation 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 X.509 Workload Identity Federation 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.

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

5. 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 X.509 Workload Identity Federation di gcloud CLI tersedia di gcloud CLI versi 519.0 dan versi yang lebih baru.

Mendapatkan token akses menggunakan permintaan biasa untuk mengakses Trusted 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 leaf yang digunakan untuk handshake mTLS harus ditentukan sebagai item pertama. Setiap sertifikat dalam paket harus berupa string berenkode base64.

1. Simpan sertifikat leaf dan sertifikat perantara 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 dokumen 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.s3nsapis.fr/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 leaf, setidaknya harus menyertakan CLIENT_CERT sebagai item pertama. Jika Anda mengikuti petunjuk di bagian Memformat sertifikat, ganti TRUST_CHAIN dengan '"${TRUST_CHAIN}"'

2. Gunakan token akses pembawa yang dibuat pada langkah sebelumnya untuk mengakses Trusted Cloud resource—misalnya:

   curl -X GET 'https://storage.s3nsapis.fr/my_object' -H "Authorization: Bearer $ACCESS_TOKEN"
   

Batas

Tabel berikut mencantumkan batas.

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.