使用 X.509 憑證設定 Workload Identity Federation

本指南說明如何搭配使用工作負載身分聯盟與憑證授權單位 (CA) 核發的 X.509 憑證，向 Trusted Cloud 驗證身分並存取 Trusted Cloud 資源。

如果工作負載擁有 mTLS 用戶端憑證，您可以向 Workload Identity Federation 註冊一或多個 CA 做為信任錨點，藉此向Trusted Cloud 進行驗證。您也可以註冊中繼憑證授權單位。

使用 Workload Identity 聯盟，即可讓這些工作負載透過相互傳輸層安全標準 (mTLS) 連線取得短期 Trusted Cloud 憑證。工作負載可使用這些短期憑證存取Trusted Cloud API。

概念

以 X.509 憑證為基礎的同盟概念包括：

• 信任錨點是視為信任根的 CA 憑證。所有用戶端憑證鏈結都應鏈結至其中一個信任錨點。

• 中繼 CA 是選用的憑證授權單位憑證，可協助建立用戶端憑證鏈結。

• 信任儲存庫包含信任錨點憑證和中繼 CA 憑證，用於驗證用戶端憑證鏈結。CA 會為用戶端核發信任的憑證。

  您可以將下列類型的用戶端憑證上傳至信任儲存區：

  • 由您選擇的第三方 CA 核發的憑證
  • 私人憑證授權單位核發的憑證
  • 已簽署的憑證，如「建立自行簽署的憑證」一文所述

事前準備

如要開始設定 Workload Identity 聯盟，請按照下列步驟操作：

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

   Go to project selector

建議您 使用專案管理工作負載身分集區和供應商。

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

必要的角色

如要取得設定 Workload Identity 聯盟所需的權限，請要求管理員授予您專案的下列 IAM 角色：

• Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin)
• 服務帳戶管理員 (roles/iam.serviceAccountAdmin)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

或者，IAM 擁有者 (roles/owner) 基本角色也包含設定身分同盟的權限。您不應在正式版環境中授予基本角色，但可以在開發或測試環境中授予。

建立信任儲存區

本節說明如何建立信任儲存區。大致步驟如下：

• 產生自行簽署的憑證
• 設定憑證格式
• 建立信任儲存區

產生自行簽署的憑證

本節說明如何產生金鑰及建立簽署憑證。如果您已建立憑證，可以略過本節，繼續進行「設定憑證格式」。

本節使用 openssl 指令建立根憑證和中繼憑證。

如要產生根憑證和簽署的中繼憑證，並包含有效的 keyUsage 和 extendedKeyUsage 欄位，請按照下列步驟操作：

1. 建立 openssl 設定檔，以建立簽署憑證。檔案至少要類似下列內容，但您可以視需要設定其他欄位。

   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. 建立根憑證。

   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. 建立中繼憑證的簽署要求。

   openssl req \
       -new -sha256 -newkey rsa:2048 -nodes \
       -subj '/CN=int' \
       -config example.cnf \
       -extensions ca_exts \
       -keyout int.key -out int.req
   

4. 建立中繼憑證。

   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. 建立葉子憑證的簽署要求。

   openssl req -new -sha256 -newkey rsa:2048 -nodes \
       -subj '/CN=example' \
       -config example.cnf \
       -extensions leaf_exts \
       -keyout leaf.key -out leaf.req
   

6. 建立由中繼憑證核發的葉子憑證。

   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
   

設定憑證格式

如要在信任儲存庫中加入新憑證或現有憑證，請將憑證格式設為單行字串，並儲存在環境變數中。憑證必須採用 PEM 格式。如要格式化憑證並儲存在環境變數中，請執行下列操作：

1. 將根憑證儲存為單行字串。

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

2. 將中繼憑證儲存為單行字串。

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

建立信任儲存區

在本節中，您將使用 YAML 格式的檔案建立信任儲存區，其中包含信任錨點和中繼 CA。

這個檔案包含您在「格式化憑證」中建立的環境變數憑證內容。如要新增其他信任錨點，請在 trustStore 下方新增其他 trustAnchors 項目。如要新增其他中繼 CA 憑證，請在 trustStore 下方新增其他 intermediateCas 項目。

如要建立信任儲存區檔案，請執行下列指令：

cat << EOF > trust_store.yaml
trustStore:
  trustAnchors:
  - pemCertificate: "${ROOT_CERT}"
  intermediateCas:
  - pemCertificate: "${INTERMEDIATE_CERT}"
EOF

定義屬性對應和條件

用戶端 X.509 憑證可以包含多個屬性。 您必須對應 google.subject 中的 Trusted Cloud 憑證屬性，選取要做為主體 ID 的屬性。舉例來說，如果憑證中的屬性是主體一般名稱，則對應方式如下： google.subject=assertion.subject.dn.cn

你也可以視需要對應其他屬性。 然後在授予資源存取權時，參照這些屬性。

屬性對應可使用用戶端憑證中的屬性，包括：

• serialNumberHex：序號
• subject.dn.cn：主體慣用名稱
• subject.dn.o：主體機構名稱
• subject.dn.ou：主體最後一個機構單位
• issuer.dn.cn：核發機構通用名稱
• issuer.dn.o：核發機構名稱
• issuer.dn.ou：核發者最後一個機構單位
• san.dns：主體替代名稱的第一個 DNS 名稱
• san.uri：主體別名的第一個 URI
• sha256Fingerprint：SHA256 葉子憑證雜湊 (Base64)

您必須將其中一個屬性對應至 google.subject，以識別主體。為防範偽造威脅，請選擇具有無法變更的專屬值的屬性。根據預設，google.subject ID 會設為用戶端憑證主體一般名稱 assertion.subject.dn.cn。

您可以視需要定義屬性條件。 屬性條件是 CEL 運算式，可檢查判斷結果屬性和目標屬性。如果屬性條件評估為特定憑證的 true，系統就會接受該憑證。否則系統會拒絕認證。

您可以使用屬性條件，限制哪些主體可使用 Workload Identity 聯盟取得短期權杖 Trusted Cloud。

舉例來說，下列條件會限制存取含有 SPIFFE ID spiffe://example/path 的用戶端憑證：

assertion.san.uri=="spiffe://example/path"

設定 Workload Identity 聯盟

本節說明如何設定工作負載身分集區和工作負載身分集區提供者。每個信任儲存區只需執行一次這些步驟。 這樣一來，您就能在多個工作負載和多個 Trusted Cloud 專案中使用相同的工作負載身分識別集區和提供者。

建立工作負載身分集區

1. 如要建立新的工作負載身分集區，請執行下列指令：

   gcloud iam workload-identity-pools create POOL_ID \
       --location="global" \
       --description="DESCRIPTION" \
       --display-name="DISPLAY_NAME"
   

   更改下列內容：

   • POOL_ID：集區的專屬 ID。
   • DISPLAY_NAME：集區名稱。
   • DESCRIPTION：所選集區的說明。授予集區身分的存取權時會顯示這段說明。

建立工作負載身分集區提供者

1. 如要新增 X.509 workload identity pool 提供者，請執行下列指令：

   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"
   

   更改下列內容：

   • PROVIDER_ID：您選擇的專屬 workload identity pool 提供者 ID。
   • POOL_ID：您先前建立的工作負載身分集區 ID。
   • TRUST_STORE_CONFIG：信任儲存區 YAML 檔案。
   • MAPPINGS：以半形逗號分隔的屬性對應清單，這些對應是您在本指南稍早建立的。例如：google.subject=assertion.subject.dn.cn。
   • CONDITIONS：選用。您在本指南稍早建立的屬性條件。如果沒有屬性條件，請移除參數。

驗證工作負載

您必須為每個工作負載執行一次這些步驟。

允許外部工作負載存取 Trusted Cloud 資源

如要授予工作負載資源存取權，建議您直接授予主體資源存取權。 Trusted Cloud 在本例中，主體是聯合使用者。部分 Trusted Cloud 產品有 Google Cloud API 限制。如果工作負載呼叫的 API 端點設有限制，您可以改用服務帳戶模擬功能。在本例中，主體是Trusted Cloud 服務帳戶，也就是身分。您授予資源的服務帳戶存取權。

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"

下載或建立憑證設定

Cloud 用戶端程式庫和 gcloud CLI 可以自動取得外部憑證，並使用這些憑證模擬服務帳戶。如要讓程式庫和工具完成這項程序，您必須提供憑證設定檔。這個檔案提供下列資訊：

• 如何取得外部憑證
• 要使用的 workload identity pool 和提供者
• 要模擬哪個服務帳戶

此外，如果是 X.509 憑證同盟，則需要憑證設定檔。這個檔案包含 X.509 用戶端憑證和私密金鑰檔案的路徑。

建立憑證和憑證設定檔，讓程式庫使用 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

使用憑證設定存取 Trusted Cloud

如要讓工具和用戶端程式庫使用憑證設定，請執行下列步驟。如要進一步瞭解應用程式預設憑證，請參閱「應用程式預設憑證的運作方式」。

1. 初始化環境變數 GOOGLE_APPLICATION_CREDENTIALS，並將其設為憑證設定檔：

   Bash

     export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
     

   將 FILEPATH 替換為憑證設定檔的相對路徑。

   PowerShell

     $env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
     

   將 FILEPATH 替換為憑證設定檔的相對路徑。

2. 確認用戶端程式庫可以找到憑證設定檔。 憑證設定檔位於下列其中一個路徑：

   • 預設 gcloud CLI 路徑：

     • Linux 和 macOS：~/.config/gcloud/certificate_config.json

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

   • GOOGLE_API_CERTIFICATE_CONFIG 環境變數中設定的路徑。

3. 使用下列支援 Workload Identity Federation 的 Cloud 用戶端程式庫，搭配 X.509 憑證。

   Go

   如果 Go 適用的用戶端程式庫使用 cloud.google.com/go/auth 模組 0.16.0 以上版本，以及 google.golang.org/api 模組 0.189.0 版本，即可支援 X.509 Workload Identity Federation。

   如要查看用戶端程式庫使用的模組版本，請在包含模組 go.mod 檔案的目錄中執行下列指令：

     go list -m cloud.google.com/go/auth
     go list -m cloud.google.com/api
   

   Python

   如果 Python 適用的用戶端程式庫使用 google-auth 套件 2.39.0 以上版本，即可支援 X.509 工作負載身分聯盟。

   如要查看用戶端程式庫使用的套件版本，請在安裝套件的環境中執行下列指令：

     pip show google-auth
   

   如要為驗證用戶端指定專案 ID，可以設定 GOOGLE_CLOUD_PROJECT 環境變數，也可以允許用戶端自動尋找專案 ID。如要自動尋找專案 ID，設定檔中的服務帳戶必須在專案中具備「瀏覽器」角色 (roles/browser)，或具備同等權限的角色。詳情請參閱google-auth 套件的使用者指南。

4. 如果工作負載在 macOS 上執行，請設定 CLOUDSDK_PYTHON_SITEPACKAGES=1，將 gcloud CLI 設為使用安裝目錄以外的 Python 程式庫。

5. 如要使用 gcloud CLI 進行驗證，請執行下列指令：

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

   將 FILEPATH 替換為憑證設定檔的路徑。

   gcloud CLI 519.0 以上版本支援 X.509 Workload Identity Federation。

使用純文字要求取得存取權杖，以存取 Trusted Cloud

建立信任鏈結

這個步驟說明如何建立信任鏈結。以純文字要求呼叫 Security Token Service 時，您會在 subject_token 欄位中傳遞信任鏈結。

將鏈結中需要納入的憑證，格式化為 RFC 7515 中指定的 JSON 格式清單。用於 mTLS 握手程序的葉子憑證必須指定為第一個項目。套件中的每個憑證都應為 Base64 編碼的字串。

1. 將葉子憑證和中繼憑證儲存為 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. 建立 JSON 格式的字串清單，可在本文件稍後呼叫 Security Token Service 時做為 subject_token 傳遞

   export TRUST_CHAIN="[\\\"${LEAF_CERT}\\\", \\\"${INTERMEDIATE_CERT}\\\"]"
   

取得存取權杖

如要取得存取權杖，請按照下列步驟操作：

1. 使用 mTLS 和用戶端憑證執行權杖交換：

   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"
   }'
   

   更改下列內容：

   • CLIENT_CERT_KEY：用戶端憑證私密金鑰
   • CLIENT_CERT：用戶端憑證

   • WORKLOAD_IDENTITY_POOL_URI：workload identity pool 提供者的網址，格式如下：

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

   • TRUST_CHAIN：驗證葉子憑證所需的信任鏈結必須至少包含 CLIENT_CERT 做為第一個項目。如果您已按照「設定憑證格式」一節中的指示操作，請將 TRUST_CHAIN 替換成 '"${TRUST_CHAIN}"'。

2. 使用上一個步驟中產生的 Bearer 存取權杖存取Trusted Cloud 資源，例如：

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

限制

下表列出限制。

後續步驟

• 進一步瞭解 Workload Identity 聯盟。
• 瞭解使用 Workload Identity Federation 的最佳做法。
• 瞭解如何管理 workload identity pool 和提供者。