設定 Workload Identity Federation 與其他身分提供者

本指南說明如何搭配其他識別資訊提供者 (IdP) 使用 Workload Identity Federation。

如要向 Cloud de Confiance驗證身分,您可以使用 Workload Identity Federation,讓工作負載將環境專屬憑證,交換為短期 Cloud de Confiance憑證。

在 Cloud de Confiance 外部執行的工作負載,可能可以存取現有的環境專屬憑證,例如:

  • 工作負載或許能從 IdP 取得 OpenID Connect (OIDC) 宣告權杖。

  • 工作負載或許能從識別資訊提供者 (IdP) 取得 SAML 斷言權杖。

使用 Workload Identity Federation 有助於減少需要輪替的憑證數量。

以下各節說明如何搭配使用 Workload Identity Federation 與支援 OpenID Connect (OIDC) 或 SAML 驗證通訊協定的 IdP。

準備外部 IdP

您必須為每個 IdP 執行一次這些步驟。

開始之前,請確認外部 IdP 符合下列規定:

OIDC

  • IdP 支援 OpenID Connect 1.0。

  • IdP 具有核發者 URI。

  • Cloud de Confiance 可以存取包含 JSON Web 金鑰 (JWK) 的 JSON Web 金鑰集 (JWKS)。JWK 用於驗證 OIDC 宣告權杖。您可以透過下列任一方法提供 JWKS 存取權:

    • Cloud de Confiance 透過公開、知名且可透過網際網路存取的導覽網址,從 IdP 下載 OIDC 中繼資料。在中繼資料內,JWKS 網址必須使用 SSL 和 TLS 保護。JWKS 網址開頭必須是 https://。 Cloud de Confiance 不支援以自行簽署憑證保護的 JWKS 網址。

      根據預設, Cloud de Confiance 會將 /.well-known/openid-configuration 附加至核發者 URI,以找出導覽網址。如果 IdP 將探索中繼資料託管在自訂端點,您可以指定自訂探索 URI (--discovery-uri) (預先發布版)。

      自訂探索 URI 必須符合下列規定:

      • URI 開頭必須是 https://。
      • URI 不得超過 2,000 個字元。
      • 配置、主機和通訊埠必須與核發者 URI 相符。
      • URI 路徑必須包含 /.well-known/<suffix> (其中 <suffix> 不得為空白,例如 openid-configuration),並符合下列其中一種核發者網址拓撲:
      • 系統會在核發者路徑前插入 well-known 路徑區段 (例如 https://example.com/tenant1 核發者的 https://example.com/.well-known/openid-configuration/tenant1)。
      • 已知路徑區隔會附加在核發者路徑下方 (例如 https://example.com/tenant1 核發者的 https://example.com/tenant1/.well-known/openid-configuration)。

      Cloud de Confiance 會使用這些端點網址下載 IdP 的 JSON Web Key (JWK),並使用這些金鑰驗證權杖。Cloud de Confiance 不會限制可下載的金鑰數量。

    • 建立或更新 OIDC workload identity pool 提供者時,您可以直接將 OIDC JWKS 檔案上傳至 Cloud de Confiance 。如要這麼做,請使用 --jwk-json-path 旗標提供 JWKS 檔案的路徑。如果 IdP 的 OIDC 中繼資料端點網址不公開,您可以使用這個方法。 Cloud de Confiance最多可上傳 8 個金鑰。建議的最佳做法是更新 JWKS 檔案,定期輪替 JWKS 金鑰。

  • 如果您使用 AWS 傳出身分聯盟,從 AWS 聯合工作負載,AWS 會做為 OIDC IdP。如要準備 AWS 環境,請按照下列步驟操作:

    1. 在 AWS 帳戶設定中啟用傳出身分聯盟,即可產生專屬的 OIDC 核發者網址。

    2. 確保 AWS 工作負載 (例如 EC2 執行個體設定檔或 ECS 任務角色) 具備必要的 AWS IAM 政策,可授予取得 JSON Web Token (JWT) 的權限。

SAML

  • IdP 支援 SAML 2.0。

  • IdP 會提供 SAML SP 中繼資料文件,說明 SAML 服務供應商設定,並包含 IdP 的簽署憑證。

    Cloud de Confiance 會使用這個憑證驗證 SAML 宣告和回應。

  • IdP 簽署憑證必須包含 X.509 v3 憑證中的 ECDSA 或 RSA 金鑰。

  • 建議的簽署演算法包括:

  • 簽署憑證必須符合下列效期規定:

    • notBefore:時間戳記,不得超過未來 7 天
    • notAfter:時間戳記,不得超過未來 25 年

設定 SAML workload identity pool 提供者時,最多可同時使用三個 SAML 簽署憑證。這項限制不適用於其他 workload identity pool 提供者類型,例如 OIDC 和 X.509。如果有多個憑證, Cloud de Confiance 會逐一檢查,並嘗試使用每個未過期的憑證來完成權杖交換要求。

為確保安全性,強烈建議您不要與其他服務重複使用相同的金鑰組。

如果 IdP 符合上述條件,請按照下列步驟操作:

OIDC

設定 IdP,讓工作負載取得符合下列條件的 ID 權杖:

  • 權杖會使用 RS256 或 ES256 演算法簽署。
  • 權杖包含 aud 宣告,其值如下:

    https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/WORKLOAD_PROVIDER_ID
    

    更改下列內容:

    • PROJECT_NUMBER:用於建立 workload identity pool 的 Cloud de Confiance 專案編號。
    • POOL_ID:您選擇用來識別 workload identity pool 的 ID。稍後建立 workload identity pool 時,必須使用相同的 ID。
    • WORKLOAD_PROVIDER_ID:您選擇的 ID,用於識別 workload identity pool 提供者。稍後建立 workload identity pool 提供者時,必須使用相同的 ID。

    或者,您也可以將 workload identity pool 提供者設定為預期自訂目標對象。

  • 權杖包含未來的 exp 宣告和過去的 iat 宣告。

    exp 的值必須大於 iat 的值,且最多只能大於 24 小時。

  • 憑證繫結權杖 (預先發布版):權杖可選擇包含 cnf (確認) 宣告,其中含有 SHA-256 憑證指紋 (x5t#S256):

    "cnf": {
      "x5t#S256": "BASE64URL_SHA256_CERT_FINGERPRINT"
    }
    

    x5t#S256 的值必須是用戶端 X.509 憑證 DER 編碼的 base64url 編碼 SHA-256 雜湊。當包含這項聲明的權杖透過相互 TLS (mTLS) 連線 (sts.mtls.googleapis.com) 提交至 Workload Identity Federation 時,Security Token Service 會驗證指紋是否與 TLS 握手期間提供的用戶端憑證相符,並核發以加密方式繫結至憑證的短期存取權杖。

    如要保護資源,防範權杖竊取和重送攻擊,請設定情境感知存取權政策,強制執行繫結憑證的權杖。

一般來說,執行權杖交換時,最好使用 ID 權杖,因為 ID 權杖會反映使用者身分。如果決定改用存取權杖,請確認存取權杖符合下列額外規定:

  • 存取權杖採用 JSON Web Token 格式。
  • 存取權杖包含 ISSUER 宣告,因此網址 ISSUER/.well-known/openid-configuration 會指向 IdP 的 OIDC 中繼資料端點。

  • 如要上傳本機 JWK 金鑰,請參閱「管理 OIDC JWK」。

SAML

設定 IdP,讓 SAML 斷言包含符合下列條件的元素:

  • Issuer 元素,設為 workload identity pool 提供者中設定的實體 ID。必須省略核發者格式,或設為 urn:oasis:names:tc:SAML:2.0:nameid-format:entity。
  • Subject 元素,包含:
    • NameID 元素。
    • 一個 SubjectConfirmation 元素,且 Method 設為 urn:oasis:names:tc:SAML:2.0:cm:bearer。
    • SubjectConfirmationData 元素,其中 NotOnOrAfter 設為未來時間戳記,且沒有 NotBefore 值。
  • Conditions 元素,包含:

    • NotBefore 遭省略或已過期。
    • NotOnOrAfter已省略或在未來。
    • Audience,格式如下:

      https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/WORKLOAD_PROVIDER_ID
      

      更改下列內容:

      • PROJECT_NUMBER:用於建立 workload identity pool 的 Cloud de Confiance 專案編號。
      • POOL_ID:您選擇用來識別 workload identity pool 的 ID。稍後建立 workload identity pool 時,必須使用相同的 ID。
      • WORKLOAD_PROVIDER_ID:您選擇的 ID,用於識別 workload identity pool 提供者。稍後建立 workload identity pool 提供者時,必須使用相同的 ID。
  • 至少一個 AuthnStatement 元素。

  • SessionNotOnOrAfter 元素的時間戳記在未來。或者,您也可以省略這個元素。

對於 SAML 回應中包含的 SAML 斷言,SAML 回應必須包含:

  • 只有一個符合本節稍早所述 SAML 斷言條件的斷言。
  • IssueInstant 屬性的值小於 1 小時。
  • StatusCode urn:oasis:names:tc:SAML:2.0:status:Success。

SAML 斷言和/或回應必須經過簽署。

設定 Workload Identity Federation

每個 IdP 只需要執行一次這些步驟。接著,您可以在多個工作負載和多個 Cloud de Confiance 專案中,使用相同的 workload identity pool 和提供者。

如要開始設定 Workload Identity Federation,請按照下列步驟操作:

  1. 在 Cloud de Confiance 控制台的專案選取器頁面中,選取或建立 Cloud de Confiance 專案。

    選取或建立專案所需的角色

    • 選取專案:選取專案時,不需具備特定 IAM 角色,只要您在專案中獲派角色,即可選取該專案。
    • 建立專案:如要建立專案,您必須具備專案建立者角色 (roles/resourcemanager.projectCreator),其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

    前往專案選取器

  2. 建議您使用專屬專案管理 workload identity pool 和提供者。
  3. 確認 Cloud de Confiance 專案已啟用計費功能。

  4. 啟用 IAM、Resource Manager、服務帳戶憑證和 Security Token Service API (如有尚未啟用的項目)。

    啟用 API 所需的角色

    如要啟用 API,您必須具備 serviceusage.services.enable 權限。如果您建立了專案,可能已透過擁有者角色 (roles/owner) 取得這項權限。否則,您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

    啟用 API

管理自行上傳的 OIDC JWK (選用)

本節說明如何在 workload identity pool OIDC 提供者中,管理自行上傳的 OIDC JWK。

建立提供者並上傳 OIDC JWK

如要建立 OIDC JWK,請參閱「JWT、JWS、JWE、JWK 和 JWA 實作」。

如要在建立 workload identity pool 提供者時上傳 OIDC JWK 檔案,請執行 gcloud iam workload-identity-pools providers create-oidc 指令,並加上 --jwk-json-path="JWK_JSON_PATH"。將 JWK_JSON_PATH 替換為 JWK JSON 檔案的路徑。

這項作業會使用檔案中的金鑰建立上傳的金鑰。

更新 OIDC JWK

如要更新 OIDC JWK,請使用 --jwk-json-path="JWK_JSON_PATH" 執行 gcloud iam workload-identity-pools providers update-oidc 指令。將 JWK_JSON_PATH 替換為 JWK JSON 檔案的路徑。

這項作業會將所有已上傳的金鑰替換為檔案中的金鑰。您無法還原已取代的金鑰。

刪除所有上傳的 OIDC JWK

如要刪除所有上傳的 OIDC JWK,並改回使用核發者 URI 擷取金鑰,請執行 gcloud iam workload-identity-pools providers update-oidc 指令,並加上 --jwk-json-path="JWK_JSON_PATH"。將 JWK_JSON_PATH 替換為空白檔案的路徑。使用 --issuer-uri 旗標設定核發者 URI。

這項操作會刪除所有已上傳的金鑰。刪除的金鑰無法還原。

定義屬性對應和條件

IdP 核發的 OIDC 權杖或 SAML 聲明可能包含多個屬性,您必須決定要使用哪個屬性做為 Cloud de Confiance中的主體 ID (google.subject)。

您也可以視需要對應其他屬性。授予資源存取權時,您就可以參照這些屬性。

OIDC

屬性對應可以使用外部 IdP 核發的 ID 權杖或存取權杖中嵌入的宣告。

您必須將其中一項要求對應至 google.subject,才能識別不重複的使用者。為防範假冒威脅,請選擇具有不變唯一值的聲明。

許多 IdP 會在 sub 憑證附加資訊中填入不重複且不可變更的 ID。對於這些 IdP,建議將 sub 宣告對應至 google.subject:

google.subject=assertion.sub

請避免使用「email」這類聲明。電子郵件地址通常可以重新指派或變更,因此無法永久識別不重複的使用者。

使用身分委派功能對應執行者屬性 (預先發布版): 使用身分委派功能時,Security Token Service 會合併主體宣告和執行者宣告,並在 act 宣告物件下公開執行者宣告。您可以使用 assertion.act.<claim_name>,在屬性對應中參照執行者聲明。

執行委派權杖交換時,系統只會評估及套用主體提供者的屬性對應和屬性條件。系統會忽略在執行者提供者上設定的所有屬性對應或屬性條件。

舉例來說,您可以將執行者的主體 ID 和核發者 URI 對應至自訂 Google 屬性:

attribute.actor_subject=assertion.act.sub,attribute.actor_issuer=assertion.act.iss

如果使用多躍點委派,上游執行者會以巢狀結構置於 assertion.act.act 中。不過,巢狀聲明的順序不一定。

SAML

屬性對應可以使用外部 IdP 核發的斷言中嵌入的 <Subject> 和 <Attribute> 元素。您可以使用下列關鍵字參照 SAML 屬性:

  • assertion.subject 包含在 <Subject> 元素中找到的已驗證使用者 NameID。
  • assertion.attributes['ATTRIBUTE_NAME'] 包含同名 <Attribute> 的值清單。

您必須將其中一項要求對應至 google.subject,才能識別不重複的使用者。為防範假冒威脅,請選擇具有不重複且無法變更值的憑證。

許多 IdP 會在 NameId 中填入不重複且不可變更的 ID。對於這些 IdP,請考慮將 NameId 屬性對應至 google.subject:

google.subject=assertion.subject

請避免使用 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress 等屬性。電子郵件地址通常可以重新指派或變更,因此無法永久且唯一地識別使用者。

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

OIDC

您可以使用屬性條件,限制哪些使用者可以透過 Workload Identity Federation 取得短期 Cloud de Confiance權杖。

舉例來說,下列條件會限制存取權,只允許存取包含自訂 service_account 宣告且值為 true 的權杖:

assertion.service_account==true

身分委派 (執行者權杖) 條件 (預先發布版): 使用身分委派時,您可以透過 CEL 屬性條件,限制哪些執行者可以代表主體執行作業,或對執行者權杖強制執行特定要求。

舉例來說,下列條件要求必須有執行者權杖,且執行者來自預期的簽發者:

has(assertion.act) && assertion.act.iss == 'https://actor-idp.example.com'

如要限制特定執行者主體 ID 的存取權,請按照下列步驟操作:

assertion.act.sub == 'authorized-agent-worker'

SAML

您可以使用屬性條件,限制哪些使用者可以透過 Workload Identity Federation 取得短期 Cloud de Confiance權杖。

舉例來說,下列條件會限制存取包含自訂 https://example.com/SAML/Attributes/AllowGcpFederation 屬性且值為 true 的斷言:

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

建立 workload identity pool 和提供者

必要的角色

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

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

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

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

您現在已收集建立 workload identity pool 和提供者所需的所有資訊:

控制台

  1. 前往 Cloud de Confiance 控制台的「New workload provider and pool」(新增工作負載提供者和集區) 頁面。

    前往「New workload provider and pool」(新增工作負載提供者和集區)

  2. 在「Create an identity pool」(建立身分集區) 下方,輸入下列資訊:

    • 名稱:集區名稱。這個名稱也會做為集區 ID。集區 ID 設定後即無法變更。
    • 說明:說明集區用途的文字。
  3. 按一下「繼續」。

  4. 按照下列方式設定提供者:

    OIDC

    • 在「Select a provider」(選取提供者) 中,選取「OpenID Connect (OIDC)」。
    • 在「Provider name」(供應商名稱) 中,輸入供應商名稱。這個名稱也會做為供應商 ID。提供者建立後,即無法變更提供者 ID。
    • 在「Issuer URL」中,輸入 IdP 的核發者網址。網址開頭必須是 https://
    • 選用:在「JWK file (JSON)」中,選擇要上傳的 JWK 檔案。如未提供這個欄位, Cloud de Confiance 會嘗試從核發者擷取 JWK。
    • 允許的目標對象:ID 權杖的預期目標對象。

    SAML

    • 在「Select a provider」部分,選取「SAML」。
    • 在「Provider name」(供應商名稱) 中,輸入供應商名稱。這個名稱也會做為供應商 ID。提供者建立後,即無法變更提供者 ID。
    • 在「IDP Metadata file (XML)」中,上傳 IdP 提供的 SAML 中繼資料 XML 文件。
  5. 按一下「繼續」。

  6. 在「Configure provider attributes」(設定提供者屬性) 下方,新增您在本指南稍早確定的屬性對應。

  7. 在「Attribute conditions」(屬性條件) 下方,輸入您稍早在本指南中找到的屬性條件。如果沒有屬性條件,請將欄位留空。

  8. 如要建立 workload identity pool 和提供者,請按一下「Save」(儲存)。

gcloud

  1. 如要建立新的 workload identity pool,請執行下列指令:

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

    更改下列內容:

    • POOL_ID:集區的專屬 ID。
    • DISPLAY_NAME:集區名稱。
    • DESCRIPTION:所選集區的說明。授予集區身分的存取權時,會顯示這段說明。
  2. 如要新增 workload identity pool 提供者,請按照下列步驟操作:

    OIDC

    如要新增 OIDC workload identity pool 提供者,請執行下列指令:

    gcloud iam workload-identity-pools providers create-oidc WORKLOAD_PROVIDER_ID \
        --location="global" \
        --workload-identity-pool="POOL_ID" \
        --issuer-uri="ISSUER" \
        --discovery-uri="DISCOVERY_URI" \
        --allowed-audiences="AUDIENCE" \
        --attribute-mapping="MAPPINGS" \
        --attribute-condition="CONDITIONS" \
        --jwk-json-path="JWK_JSON_PATH" \
        --actor-providers="ACTOR_PROVIDERS"
    

    更改下列內容:

    • WORKLOAD_PROVIDER_ID:您選擇的不重複 workload identity pool 提供者 ID。
    • POOL_ID:您先前建立的 workload identity pool ID。
    • ISSUER:OIDC 中繼資料中定義的核發者 URI。
    • DISCOVERY_URI 預先發布版:如果 IdP 未在 https://<issuer_url>/.well-known/openid-configuration 託管已知的 OIDC 探索端點,則可選用自訂探索網址來擷取 OIDC 中繼資料。配置、主機和通訊埠必須與 ISSUER 相符,路徑則必須符合核發者網址拓撲 (包含 /.well-known/<suffix>)。
    • AUDIENCE:ID 權杖的預期目標對象,對許多供應商來說,這與用戶端 ID 相同。
    • MAPPINGS:以半形逗號分隔的屬性對應清單,這些對應是您在本指南稍早建立的。
    • CONDITIONS:您在本指南稍早建立的選用屬性條件。如果沒有屬性條件,請移除參數。
    • JWK_JSON_PATH:在本機上傳的 OIDC JWK 選用路徑。如未提供這項參數, Cloud de Confiance 會改用導覽網址 (DISCOVERY_URI 或 IdP 的 /.well-known/openid-configuration 路徑),尋找包含公開金鑰的 JWK。
    • ACTOR_PROVIDERS 預先發布版:選用清單,以逗號分隔相同集區中,有權為這個提供者核發 actor 權杖的 workload identity pool 提供者完整資源名稱 (例如 projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/ACTOR_PROVIDER_ID)。資源名稱中的專案容器 ID 必須與主體提供者使用的格式相符 (兩者皆使用數字專案編號,或皆使用專案 ID)。最多可以指定三個動作提供者。詳情請參閱「設定身分委派和執行者權杖」。

    SAML

    如要新增 SAML workload identity pool 提供者,請執行下列指令:

    gcloud iam workload-identity-pools providers create-saml WORKLOAD_PROVIDER_ID \
        --location="global" \
        --workload-identity-pool="POOL_ID" \
        --idp-metadata-path="IDP_METADATA_PATH" \
        --attribute-mapping="MAPPINGS" \
        --attribute-condition="CONDITIONS"
    

    更改下列內容:

    • POOL_ID:集區 ID
    • IDP_METADATA_PATH:SAML IdP 中繼資料文件的本機路徑
    • MAPPINGS:以半形逗號分隔的清單,列出您先前在本指南中建立的屬性對應
    • CONDITIONS:選用:您在本指南稍早建立的屬性條件

    前置字元 gcp- 為保留字,不得用於員工身分集區或員工身分集區提供者 ID。

    選用:接受來自 IdP 的加密 SAML 宣告

    如要讓 SAML 2.0 IdP 產生 Workload Identity Federation 可接受的加密 SAML 斷言,請按照下列步驟操作:

    • 在 Workload Identity Federation 中,執行下列操作:
      • 為 workload identity pool 提供者建立非對稱金鑰組。
      • 下載內含公開金鑰的憑證檔案。
      • 設定 SAML IdP,使用公開金鑰加密其核發的 SAML 宣告。
    • 在 IdP 中執行下列操作:
      • 啟用斷言加密 (也稱為權杖加密)。
      • 上傳您在 Workload Identity Federation 建立的公開金鑰。
      • 確認 IdP 會產生加密的 SAML 宣告。
    請注意,即使已設定 SAML 加密提供者金鑰,Workload Identity Federation 仍可處理明文宣告。

    建立 Workload Identity Federation SAML 斷言加密金鑰

    本節將引導您建立非對稱金鑰組,讓 Workload Identity Federation 接受加密的 SAML 斷言。

    Cloud de Confiance by S3NS 會使用私密金鑰解密 IdP 核發的 SAML 宣告。如要建立非對稱金鑰組,用於 SAML 加密,請執行下列指令。詳情請參閱「支援的 SAML 加密演算法」。

    gcloud iam workload-identity-pools providers keys create KEY_ID \
        --workload-identity-pool WORKLOAD_POOL_ID \
        --provider WORKLOAD_PROVIDER_ID \
        --location global \
        --use encryption \
        --spec KEY_SPECIFICATION

    替換下列內容:

    • KEY_ID:您選擇的金鑰名稱
    • WORKLOAD_POOL_ID:集區 ID
    • WORKLOAD_PROVIDER_ID:員工身分集區提供者 ID
    • KEY_SPECIFICATION:金鑰規格,可以是 rsa-2048、rsa-3072 和 rsa-4096 其中之一。

    建立金鑰組後,請執行下列指令,將公開金鑰下載至憑證檔案。只有 Workload Identity Federation 才能存取私密金鑰。

    gcloud iam workload-identity-pools providers keys describe KEY_ID \
        --workload-identity-pool WORKLOAD_POOL_ID \
        --provider WORKLOAD_PROVIDER_ID \
        --location global \
        --format "value(keyData.key)" \
        > CERTIFICATE_PATH

    替換下列內容:

    • KEY_ID:金鑰名稱
    • WORKLOAD_POOL_ID:集區 ID
    • WORKLOAD_PROVIDER_ID:員工身分集區提供者 ID
    • CERTIFICATE_PATH:憑證的寫入路徑,例如 saml-certificate.cer 或 saml-certificate.pem

    設定符合 SAML 2.0 規範的 IdP,以便核發加密的 SAML 宣告

    設定 SAML IdP,使用上一步下載的公開憑證,加密其發出的 SAML 斷言。如需具體操作說明,請洽詢 IdP 團隊。

    將 IdP 設為加密 SAML 斷言後,建議您檢查並確認 IdP 產生的斷言確實已加密。即使設定了 SAML 斷言加密,Workload Identity Federation 仍可處理明文斷言。

    刪除 Workload Identity Federation 加密金鑰

    如要刪除 SAML 加密金鑰,請執行下列指令:
      gcloud iam workload-identity-pools providers keys delete KEY_ID \
          --workload-identity-pool WORKLOAD_POOL_ID \
          --provider WORKLOAD_PROVIDER_ID \
          --location global

    替換下列內容:

    • KEY_ID:金鑰名稱
    • WORKLOAD_POOL_ID:集區 ID
    • WORKLOAD_PROVIDER_ID:員工身分集區提供者 ID

    支援的 SAML 加密演算法

    Workload Identity Federation 支援下列金鑰傳輸演算法:

    Workload Identity Federation 支援下列區塊加密演算法:

設定 Workload Identity Federation 的情境感知存取權強制執行

只有在使用繫結憑證的權杖時,系統才會強制執行情境感知存取權政策。您可以啟用情境感知存取權,強制對存取要求執行 mTLS 驗證和憑證繫結,強化資源安全性,防範權杖重送和竊取攻擊。為繫結憑證的權杖設定情境感知存取權政策後, Cloud de Confiance 會評估傳輸情境和傳入要求的用戶端憑證,確保工作負載提供的存取權杖,以加密方式繫結至受信任的 mTLS 用戶端憑證工作階段。情境感知存取權政策不適用於標準未繫結權杖。

設定身分委派和執行者權杖

在 RFC 8693:OAuth 2.0 權杖交換定義的身分委派情境中,執行方 (執行者) 會代表主體身分執行作業。

如要設定及授權身分委派,請符合下列需求條件:

  1. 執行者提供者授權:在主體提供者的執行者提供者設定 (--actor-providers) 中,加入核發執行者權杖的提供者完整資源名稱。演員供應商必須符合下列條件:

    • 必須與主體提供者位於同一個 workload identity pool。
    • 資源名稱中的專案容器 ID 必須與主體提供者使用的格式相符 (例如,如果您使用 Google Cloud CLI 建立主體提供者,則必須是英數字元專案 ID)。
    • 每個供應商最多可授權 3 個執行者供應商。
  2. 主體權杖中的 may_act 宣告:主體 ID 權杖必須包含 may_act 宣告:

    "may_act": {
      "sub": "ACTOR_SUBJECT",
      "iss": "ACTOR_ISSUER"
    }
    

    更改下列內容:

    • ACTOR_SUBJECT:授權執行者的主體 ID (必須與執行者權杖中的 sub 宣告相符)。
    • ACTOR_ISSUER:選用。執行者身分識別資訊提供者的核發者 URI (必須與執行者權杖中的 iss 宣告相符)。如果省略,則 actor 應與主體權杖共用相同的核發者。
  3. 權杖交換參數:使用 Workload Identity Federation 執行權杖交換時,用戶端會提供 subject_token 和 actor_token,以及各自的權杖類型 (subject_token_type 和 actor_token_type):

    • subject_token:代表提出要求身分的安全性權杖。
    • subject_token_type:表示主體權杖類型的 ID (例如 urn:ietf:params:oauth:token-type:jwt 或 urn:ietf:params:oauth:token-type:id_token)。
    • actor_token:代表執行方身分的安全性權杖。執行者權杖必須符合下列規定:
      • 目標對象 (aud) 宣告:必須包含核發 actor_token 的特定執行者提供者完整資源 URI://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/ACTOR_PROVIDER_ID。aud 宣告只能包含一個 workload identity pool 提供者資源 URI。如果同一個 workload identity pool 中有多個 actor 提供者,請僅加入核發 actor_token 的提供者資源 URI。
      • 授權執行者提供者:aud 宣告中識別的執行者提供者,必須與主體提供者位於同一個 workload identity pool,並列在主體提供者的執行者提供者設定 (--actor-providers) 中。
      • 比對 sub 和 iss 宣告:actor 權杖的 sub 宣告和選用的 iss 宣告,必須與主體權杖 may_act 宣告中宣告的 sub 和 iss 值相符。
    • actor_token_type:表示執行者權杖類型的 ID (urn:ietf:params:oauth:token-type:jwt 或 urn:ietf:params:oauth:token-type:id_token)。如果提供 actor_token,則必須提供這個參數。
    • 具有委派功能的憑證繫結權杖:如果 subject_token 是憑證繫結 (包含 cnf 確認宣告),則 actor_token 也必須是憑證繫結 (包含 cnf 宣告)。透過 mTLS (sts.mtls.googleapis.com) 執行權杖交換時,mTLS 握手中提供的用戶端憑證必須與 actor_token 的憑證指紋相符。

驗證工作負載

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

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

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

直接存取資源

您可以使用 Cloud de Confiance 控制台或 gcloud CLI,直接授予聯合身分資源存取權。

控制台

如要使用 Cloud de Confiance 控制台直接對資源授予 IAM 角色,請前往資源頁面,然後授予角色。以下範例說明如何前往 Cloud Storage 頁面,並直接在 Cloud Storage bucket 上,將 Storage 物件檢視者角色 (roles/storage.objectViewer) 授予聯合身分。

  1. 前往 Cloud de Confiance 控制台的「Cloud Storage bucket」頁面。

    前往「Buckets」(值區) 頁面

  2. 在 bucket 清單中,點選要授予角色的 bucket 名稱。

  3. 選取靠近頁面上方的 [Permissions] (權限) 分頁標籤。

  4. 按一下 「Grant access」(授予存取權) 按鈕。

    系統會隨即顯示「Add principals」(新增主體) 對話方塊。

  5. 在「New principals」(新增主體) 欄位中,輸入一或多個需要存取 bucket 的身分。

    依科目

    principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT
    

    更改下列內容:

    • PROJECT_NUMBER:專案編號
    • POOL_ID:工作負載集區 ID
    • SUBJECT:從 IdP 對應的個別主體,例如 administrator@example.com

    依群組

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

    更改下列內容:

    • PROJECT_NUMBER:專案編號
    • WORKLOAD_POOL_ID:工作負載集區 ID
    • GROUP:從 IdP 對應的群組,例如:administrator-group@example.com

    依屬性

    principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
    

    更改下列內容:

    • PROJECT_NUMBER:專案編號
    • WORKLOAD_POOL_ID:工作負載集區 ID
    • ATTRIBUTE_NAME:從 IdP 對應的其中一個屬性
    • ATTRIBUTE_VALUE:屬性的值
  6. 從「Select a role」(選取角色) 下拉式選單中選取一或多個角色。 面板中會顯示選取的角色,並針對這些角色授予的權限提供簡短說明。

  7. 按一下「Save」(儲存)。

gcloud

如要使用 gcloud CLI 授予專案中資源的 IAM 角色,請按照下列步驟操作:

  1. 取得定義資源的專案編號。

    gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\)
    
  2. 授予資源存取權。

    如要使用 gcloud CLI,將 Storage 物件檢視者角色 (roles/storage.objectViewer) 授予符合特定條件的外部身分,請執行下列指令。

    依主題

    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"

    依群組

    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"

    依屬性

    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"

    更改下列內容:

    • BUCKET_ID:要授予存取權的 bucket
    • PROJECT_NUMBER:workload identity pool 所在專案的專案編號。
    • POOL_ID:workload identity pool 的集區 ID
    • SUBJECT:您對應至 google.subject 的屬性預期值
    • GROUP:您對應至 google.groups 的屬性預期值
    • ATTRIBUTE_NAME:屬性對應中的自訂屬性名稱
    • ATTRIBUTE_VALUE:屬性對應中的自訂屬性值

    您可以對任何支援 IAM 允許政策的 Cloud de Confiance 資源授予角色。

服務帳戶模擬

  1. 如要為外部工作負載建立服務帳戶,請按照下列步驟操作:

    1. 啟用 IAM、Security Token Service 和 Service Account Credentials API (如果尚未啟用)。

      啟用 API 所需的角色

      如要啟用 API,您必須具備 serviceusage.services.enable 權限。如果您建立了專案,可能已透過擁有者角色 (roles/owner) 取得這項權限。否則,您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

      啟用 API

    2. 建立代表工作負載的服務帳戶。建議您為每項工作負載使用專屬服務帳戶。服務帳戶不一定要與 workload identity pool 位於相同專案,但您必須參照含有服務帳戶的專案。

    3. 授予服務帳戶存取權,讓外部身分存取所需資源。

  2. 如要允許聯合身分模擬服務帳戶,請按照下列步驟操作:

控制台

如要使用 Cloud de Confiance 控制台,將 IAM 角色授予具備服務帳戶的聯合身分,請按照下列步驟操作:

相同專案中的服務帳戶

  1. 如要使用服務帳戶模擬功能,為同一專案中的服務帳戶授予存取權,請按照下列步驟操作:

    1. 前往「Workload Identity Pools」頁面。

      前往「Workload Identity Pools」頁面

    2. 選取「授予存取權」。

    3. 在「Grant access to service account」(授予服務帳戶存取權) 對話方塊中,選取「Grant access using Service Account impersonation」(透過服務帳戶模擬功能授予存取權)。

    4. 在「Service accounts」(服務帳戶) 清單中,選取要讓外部身分模擬的服務帳戶,然後執行下列操作:

    5. 如要選擇集區中哪些身分可以模擬服務帳戶,請執行下列任一操作:

      • 如要僅允許 workload identity pool 的特定身分模擬服務帳戶,請選取「Only identities matching the filter」(僅限符合篩選條件的身分)。

      • 在「Attribute name」(屬性名稱) 清單中,選取要篩選的屬性。

      • 在「Attribute value」(屬性值) 欄位中,輸入預期的屬性值。舉例來說,如果您使用屬性對應 google.subject=assertion.sub,請將「Attribute name」(屬性名稱) 設為 subject,並將「Attribute value」(屬性值) 設為外部身分識別資訊提供者所核發權杖中的 sub 權杖附加資訊值。

    6. 如要儲存設定,請依序點選「Save」(儲存) 和「Dismiss」(關閉)。

其他專案中的服務帳戶

  1. 如要使用服務帳戶模擬功能,為其他專案中的服務帳戶授予存取權,請按照下列步驟操作:

    1. 前往「Service Accounts」(服務帳戶) 頁面

      前往「Service Accounts」(服務帳戶) 頁面

    2. 選取要模擬的服務帳戶。

    3. 按一下「管理存取權」。

    4. 按一下「Add principal」(新增主體)。

    5. 在「New principal」(新增主體) 欄位中,輸入下列其中一個主體 ID,代表集區中要模擬服務帳戶的身分。

      依科目

      principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT
      

      更改下列內容:

      • PROJECT_NUMBER:專案編號
      • POOL_ID:工作負載集區 ID
      • SUBJECT:從 IdP 對應的個別主體,例如 administrator@example.com

      依群組

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

      更改下列內容:

      • PROJECT_NUMBER:專案編號
      • WORKLOAD_POOL_ID:工作負載集區 ID
      • GROUP:從 IdP 對應的群組,例如:administrator-group@example.com

      依屬性

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
      

      更改下列內容:

      • PROJECT_NUMBER:專案編號
      • WORKLOAD_POOL_ID:工作負載集區 ID
      • ATTRIBUTE_NAME:從 IdP 對應的其中一個屬性
      • ATTRIBUTE_VALUE:屬性的值

      依集區

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

      更改下列內容:

      • PROJECT_NUMBER:專案編號
      • WORKLOAD_POOL_ID:工作負載集區 ID
    6. 在「Select a role」(選取角色) 中,選取 Workload Identity 使用者角色 (roles/iam.workloadIdentityUser)。

    7. 如要儲存設定,請按一下「儲存」。

gcloud

如要將 Workload Identity 使用者角色 (roles/iam.workloadIdentityUser) 授予聯合主體或主體集,請執行下列指令。如要進一步瞭解 Workload Identity Federation 主體 ID,請參閱「主體類型」。

依主題

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"

更改下列內容:

  • SERVICE_ACCOUNT_EMAIL:服務帳戶的電子郵件地址
  • PROJECT_NUMBER:workload identity pool 所在專案的專案編號。
  • POOL_ID:workload identity pool 的集區 ID
  • SUBJECT:您對應至 google.subject 的屬性預期值
  • GROUP:您對應至 google.groups 的屬性預期值
  • ATTRIBUTE_NAME:屬性對應中的自訂屬性名稱
  • ATTRIBUTE_VALUE:屬性對應中的自訂屬性值

下載憑證設定

本節說明如何使用Cloud de Confiance 控制台下載憑證設定。

如要讓工作負載存取用戶端程式庫,您必須先下載並設定應用程式預設憑證 (ADC),步驟如下:

  1. 前往 Cloud de Confiance 控制台的「Workload Identity Pools」頁面。

    前往「Workload Identity Pools」頁面
  2. 在表格中選取集區,前往集區的詳細資料頁面。

  3. 按一下「授予存取權」。

  4. 選取「使用聯合身分授予存取權 (建議)」。

  5. 如要下載應用程式預設憑證 (ADC),讓工作負載存取用戶端程式庫,請按照下列步驟操作:

    1. 按一下「下載設定檔」。

    2. 在「Configure your application」(設定應用程式) 對話方塊中,執行下列操作:

      1. 在「Provider」(供應商) 下拉式選單中,選取您的供應商。

      2. 在「OIDC token path」(OIDC 權杖路徑) 或「SAML assertion path」(SAML 斷言路徑) 中,輸入權杖或斷言所在的路徑。

      3. 在「Format type」(格式類型) 下拉式選單中,選取格式。

    3. 按一下「Download configuration」(下載設定),並記下檔案儲存路徑。

建立憑證設定

Cloud 用戶端程式庫、gcloud CLI 和 Terraform 可自動取得外部憑證,並使用這些憑證存取 Cloud de Confiance。如要讓程式庫和工具完成這項程序,您必須提供憑證設定檔。這個檔案定義了以下內容:

  • 外部憑證的取得來源
  • 要使用的 workload identity pool 和提供者
  • 要模擬的服務帳戶 (如果您使用服務帳戶模擬功能)

Cloud 用戶端程式庫會透過執行本機執行檔,從本機檔案、HTTP 網址取得外部憑證:

  • 可執行檔來源憑證:每當需要新憑證時,程式庫就會啟動可執行檔。如果執行檔成功取得新的外部憑證,就必須將 JSON 文件寫入 STDOUT,如下所示:

    OIDC

    {
      "version": 1,
      "success": true,
      "token_type": "urn:ietf:params:oauth:token-type:id_token",
      "id_token": "HEADER.PAYLOAD.SIGNATURE",
      "expiration_time": 1620499962
    }
    

    如果執行檔無法取得新憑證,則必須將 JSON 文件寫入 STDOUT,如下所示:

    {
      "version": 1,
      "success": false,
      "code": "401",
      "message": "Caller not authorized."
    }
    

    JSON 文件會使用下列欄位:

    • version:JSON 輸出的版本。僅支援第 1 版。
    • success:回應狀態。

      true 時,回應必須包含 id_token 和 token_type 欄位。 執行檔必須以結束代碼 0 結束。

      false 時,回應必須包含 code 和 message 欄位,並以非零值結束。

    • token_type:外部憑證的權杖類型。支援的值包括

      • urn:ietf:params:oauth:token-type:id_token
      • urn:ietf:params:oauth:token-type:jwt
    • id_token:外部憑證。

    • expiration_time:OIDC 權杖到期時間,以秒為單位 (Unix 紀元時間)。只有在憑證設定中指定輸出檔案時,才需要填寫這個欄位。

    • code:錯誤代碼字串。

    • message:錯誤訊息。

    SAML

    {
      "version": 1,
      "success": true,
      "token_type": "urn:ietf:params:oauth:token-type:saml2",
      "saml_response": "...",
      "expiration_time": 1620499962
    }
    

    如果執行檔無法取得新憑證,則必須將 JSON 文件寫入 STDOUT,如下所示:

    {
      "version": 1,
      "success": false,
      "code": "401",
      "message": "Caller not authorized."
    }
    

    JSON 文件會使用下列欄位:

    • version:JSON 輸出的版本。僅支援第 1 版。
    • success:回應狀態。

      true 時,回應必須包含 id_token 和 token_type 欄位。 執行檔必須以結束代碼 0 結束。

      false 時,回應必須包含 code 和 message 欄位,並以非零值結束。

    • token_type:外部憑證的權杖類型。必須為 urn:ietf:params:oauth:token-type:saml2。

    • saml_response:SAML 回應或以 Base64 編碼的 SAML 宣告。

    • expiration_time:斷言到期時間,以秒為單位 (Unix 紀元時間)。只有在憑證設定中指定輸出檔案時,才需要填寫這個欄位。

    • code:錯誤代碼字串。

    • message:錯誤訊息。

    啟動執行檔時,用戶端程式庫會設定下列環境變數:

    • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE:憑證設定中的目標對象。一律存在。
    • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE:預期的主體權杖類型。一律存在。
    • GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL:服務帳戶電子郵件地址。只有在使用服務帳戶模擬功能時,才會顯示這個欄位。
    • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE:憑證設定的輸出檔案位置。只有在憑證設定中指定時才會顯示。

    如要使用可執行檔來源憑證,您必須將環境變數 GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES 設為 1。

  • 檔案來源憑證:程式庫會從本機純文字或 JSON 檔案讀取外部憑證。例如:

    JSON

    {
      "mytoken": "ey...
    }
    

    如果您使用執行者委派 (預先發布版),JSON 檔案必須包含主體權杖和執行者權杖的個別欄位:

    {
      "subject_token": "ey...",
      "actor_token": "ey..."
    }
    

    使用執行者委派 (actor_token_field_name 和 actor_token_type) 的憑證設定,僅支援 Java 專用 Google Auth 程式庫。

    文字

    ey...
    

    外部憑證可以是:

    • OIDC 權杖
    • SAML 回應
    • Base64 編碼的 SAML 聲明

    您必須定期更新檔案,確保檔案一律包含有效的憑證。舉例來說,如果 OIDC 權杖或 SAML 斷言的有效期限為一小時,您必須至少每小時重新整理一次檔案。

  • 網址來源憑證:每當程式庫需要新憑證時,就會向 HTTP 端點執行 GET 要求。端點必須傳回純文字或 JSON 回應,格式與檔案來源憑證使用的格式相同。

如要建立憑證設定檔,請按照下列步驟操作:

可執行檔來源憑證

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

更改下列內容:

  • PROJECT_NUMBER:workload identity pool 所在專案的專案編號。
  • POOL_ID:workload identity pool 的 ID。
  • WORKLOAD_PROVIDER_ID:workload identity pool 提供者的 ID。
  • SERVICE_ACCOUNT_EMAIL:如果您使用服務帳戶模擬功能,請替換為服務帳戶的電子郵件地址。如果不使用服務帳戶模擬功能,請省略這個旗標。
  • SERVICE_ACCOUNT_TOKEN_LIFETIME:如果使用服務帳戶模擬功能,請替換為服務帳戶存取權杖的生命週期 (以秒為單位);如未提供,則預設為一小時。如果不使用服務帳戶模擬功能,請省略這個旗標。如要指定超過一小時的效期,您必須設定 constraints/iam.allowServiceAccountCredentialLifetimeExtension 組織政策限制。
  • REGION:選用。指定區域 Security Token Service 端點的區域 (如有)。
  • FILEPATH:要儲存設定的檔案。
  • EXECUTABLE_COMMAND:要執行以擷取 OIDC ID 權杖的完整指令 (包括引數),例如 --executable-command="/path/to/command --foo=bar"。
  • EXECUTABLE_TIMEOUT:等待執行檔執行的時間長度 (選用,以毫秒為單位,預設為 30 秒)。
  • EXECUTABLE_OUTPUT_FILE:指向執行檔產生的 3PI 憑證的路徑。這項功能適合用於快取憑證。指定這個路徑後,Auth 程式庫會先檢查路徑是否存在,再執行可執行檔。

檔案來源憑證

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/WORKLOAD_PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --sts-location=REGION \
    --output-file=FILEPATH.json \
    --credential-source-file=TOKEN_FILEPATH \
    --credential-source-type=SOURCE_TYPE \
    --credential-source-field-name=FIELD_NAME \
    --actor-token-field-name=ACTOR_FIELD_NAME \
    --actor-token-type=ACTOR_TOKEN_TYPE \
    --credential-cert-path=WORKLOAD_CERTIFICATE_PATH \
    --credential-cert-private-key-path=WORKLOAD_KEY_PATH \
    --credential-cert-configuration-output-file=CERT_CONFIG_FILEPATH

更改下列內容:

  • PROJECT_NUMBER:workload identity pool 所在專案的專案編號。
  • POOL_ID:workload identity pool 的 ID。
  • WORKLOAD_PROVIDER_ID:workload identity pool 提供者的 ID。
  • SERVICE_ACCOUNT_EMAIL:如果您使用服務帳戶模擬功能,請替換為服務帳戶的電子郵件地址。如果您不使用服務帳戶模擬功能,請省略這個旗標。
  • SERVICE_ACCOUNT_TOKEN_LIFETIME:如果使用服務帳戶模擬功能,請替換為服務帳戶存取權杖的生命週期 (以秒為單位);如未提供,則預設為一小時。如果不使用服務帳戶模擬功能,請省略這個旗標。如要指定超過一小時的效期,您必須設定 constraints/iam.allowServiceAccountCredentialLifetimeExtension 組織政策限制。
  • REGION:選用。指定區域 Security Token Service 端點的區域 (如有)。
  • FILEPATH:要儲存設定的檔案。
  • TOKEN_FILEPATH:儲存 OIDC ID 權杖的路徑。
  • SOURCE_TYPE:OIDC ID 權杖檔案的格式,設為 text (預設) 或 json。如果指定 --actor-token-field-name 旗標,則必須設為 json。
  • FIELD_NAME:文字檔案中包含權杖的欄位 (如果 SOURCE_TYPE 為 json)。
  • ACTOR_FIELD_NAME (預先發布版):選用。如果您使用執行者委派,請在 JSON 檔案 (TOKEN_FILEPATH) 中指定包含執行者權杖的欄位。必須與 FIELD_NAME 不同。如果不使用執行者委派,請省略這個旗標。
  • ACTOR_TOKEN_TYPE (預先發布版):選用。指定 --actor-token-field-name 旗標時,執行者權杖的權杖類型。預設值為 urn:ietf:params:oauth:token-type:jwt。如果不使用執行者委派,請省略這個旗標。
  • WORKLOAD_CERTIFICATE_PATH (預先發布版):選用。如果使用憑證繫結權杖,請指定工作負載的 PEM 編碼 X.509 分葉憑證檔案路徑。指定這個旗標後,gcloud CLI 會設定 mTLS 端點 (sts.mtls.googleapis.com 和 iamcredentials.mtls.googleapis.com),並產生憑證設定檔。
  • WORKLOAD_KEY_PATH (預先發布版):選用。工作負載 X.509 憑證的 PEM 編碼私密金鑰檔案路徑。如果指定 --credential-cert-path 旗標,則必須提供這個旗標。
  • CERT_CONFIG_FILEPATH (預先發布版):選用。產生的憑證設定檔自訂輸出路徑。如果省略這個旗標並指定 --credential-cert-path 旗標,gcloud CLI 會將 certificate_config.json 寫入預設的 gcloud CLI 設定位置 (Linux 和 macOS 上的 ~/.config/gcloud/certificate_config.json,或 Windows 上的 %APPDATA%\gcloud\certificate_config.json)。

只有 Java 專用 Google Auth 程式庫支援使用 --actor-token-field-name 和 --actor-token-type 旗標,產生包含執行者委派作業的憑證設定。

網址來源憑證

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

更改下列內容:

  • PROJECT_NUMBER:含有 workload identity pool 的專案編號。
  • POOL_ID:workload identity pool 的 ID。
  • WORKLOAD_PROVIDER_ID:workload identity pool 提供者的 ID
  • SERVICE_ACCOUNT_EMAIL:如果您使用服務帳戶模擬功能,請替換為服務帳戶的電子郵件地址。如果您不使用服務帳戶模擬功能,請省略這個旗標。
  • SERVICE_ACCOUNT_TOKEN_LIFETIME:如果使用服務帳戶模擬功能,請替換為服務帳戶存取權杖的生命週期 (以秒為單位);如未提供,則預設為一小時。如果不使用服務帳戶模擬功能,請省略這個旗標。如要指定超過一小時的效期,您必須設定 constraints/iam.allowServiceAccountCredentialLifetimeExtension 組織政策限制。
  • REGION:選用。指定區域 Security Token Service 端點的區域 (如有)。
  • FILEPATH:要儲存設定的檔案。
  • TOKEN_URL:用於擷取 OIDC ID 權杖的網址
  • KEY_n、VALUE_n:要加入 TOKEN_URL HTTP 要求的自訂標頭
  • SOURCE_TYPE:OIDC ID 權杖檔案的格式,設為 text (預設) 或 json
  • FIELD_NAME:文字檔案中包含權杖的欄位 (如果 SOURCE_TYPE 為 json)

使用憑證設定存取 Cloud de Confiance

如要讓工具和用戶端程式庫使用您的憑證設定,請按照下列步驟操作:

  1. 初始化環境變數 GOOGLE_APPLICATION_CREDENTIALS,並指向憑證設定檔:

    Bash

      export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
      
    其中 FILEPATH 是憑證設定檔的相對路徑。

    PowerShell

      $env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
      
    其中 FILEPATH 是憑證設定檔的相對路徑。
  2. 使用支援 Workload Identity Federation 且可自動尋找憑證的用戶端程式庫或工具:

    C++

    Cloud de Confiance C++ 適用的用戶端程式庫自 v2.6.0 版起支援 Workload Identity Federation。如要使用 Workload Identity Federation,您必須使用 1.36.0 以上版本的 gRPC 建構用戶端程式庫。

    Go

    如果 Go 的用戶端程式庫使用 golang.org/x/oauth2 模組的 v0.0.0-20210218202405-ba52d332ba99 以上版本,則支援 Workload Identity Federation。

    如要查看用戶端程式庫使用的模組版本,請執行下列指令:

    cd $GOPATH/src/cloud.google.com/go
    go list -m golang.org/x/oauth2
    

    Java

    如果 Java 用戶端程式庫使用 0.24.0 以上版本的 com.google.auth:google-auth-library-oauth2-http 構件,則支援 Workload Identity Federation。

    如要查看用戶端程式庫使用的構件版本,請在應用程式目錄中執行下列 Maven 指令:

    mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http
    

    Node.js

    如果 Node.js 用戶端程式庫使用 7.0.2 以上版本的 google-auth-library 套件,則支援 Workload Identity Federation。

    如要查看用戶端程式庫使用的套件版本,請在應用程式目錄中執行下列指令:

    npm list google-auth-library
    

    建立 GoogleAuth 物件時,您可以指定專案 ID,也可以讓 GoogleAuth 自動尋找專案 ID。如要自動尋找專案 ID,設定檔中的服務帳戶必須具備專案的瀏覽器角色 (roles/browser),或具備同等權限的角色。詳情請參閱 google-auth-library 套件的 README。

    Python

    如果 Python 用戶端程式庫使用 1.27.0 以上版本的 google-auth 套件,則支援 Workload Identity Federation。

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

    pip show google-auth
    

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

    gcloud

    如要使用 Workload Identity Federation 進行驗證,請使用 gcloud auth login 指令:

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

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

    363.0.0 以上版本的 gcloud CLI 支援 Workload Identity Federation。

    Terraform

    如果您使用 3.61.0 以上版本,Cloud de Confiance provider 支援 Workload Identity Federation:

    terraform {
      required_providers {
        google = {
          source  = "hashicorp/google"
          version = "~> 3.61.0"
        }
      }
    }
    

    bq

    如要使用 Workload Identity Federation 進行驗證,請使用 gcloud auth login 指令,如下所示:

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

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

    gcloud CLI 390.0.0 以上版本支援 bq 中的 Workload Identity Federation。

後續步驟