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

OIDC

• IdP 支援 OpenID Connect 1.0。

• IdP 具有核發者 URI。

• 您可以使用下列其中一種方式，提供 IdP 的 JWK，用於驗證 OIDC 聲明權杖：

  • 以 SSL 和 TLS 保護的 OIDC 中繼資料端點。端點網址開頭必須是 https://，且端點可透過網際網路公開存取。 Google Cloud不支援以自行簽署憑證保護的端點。

    Google Cloud 會使用這些端點下載 IdP 的 JWK，並使用這個金鑰集驗證權杖。

  • 直接上傳至 Google Cloud的 OIDC JWKS 檔案。使用這個方法時，端點不必公開存取。系統不支援 JWK 內的 x5c 和 x5t 欄位，因此上傳前必須移除。

SAML

• IdP 支援 SAML 2.0。

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

  Google Cloud 會使用這項憑證驗證 SAML 宣告和回應。

• SAML X.509 簽署金鑰規定如下：

  • 包裝在 X.509 v3 憑證中的 RSA 公開金鑰。

  • 憑證有效性規定：

    • notBefore：時間戳記，不得晚於 7 天後
    • notAfter：時間戳記，不得超過 25 年

  • 建議使用的演算法：

    • RSAwithSHA256 (支援的金鑰大小 (位元)：2048、3072、4096)
    • ECDSAwithSHA256

工作負載身分識別集區提供者一次最多可設定三個簽署金鑰。如果有多個金鑰， Google Cloud會逐一迭代，並嘗試使用每個未過期的金鑰來完成權杖交換要求。

為確保安全，我們強烈建議您不要將同一組金鑰與其他服務共用。

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 的 Google Cloud 專案專案編號。
  • POOL_ID：您選擇的 ID，用於識別 workload identity pool。日後建立工作負載身分集區時，必須使用相同的 ID。
  • WORKLOAD_PROVIDER_ID：您選擇的 ID，用於識別 workload identity pool 提供者。稍後建立 workload identity pool 提供者時，您必須使用相同的 ID。

  或者，您可以將工作負載身分集區提供者設定為預期自訂目標對象。

• 權杖包含未來的 exp 聲明和過去的 iat 聲明。

  exp 的值必須大於 iat 的值，且最多相差 24 小時。

一般來說，執行權杖交換時最好使用 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 元素。
  • Method 設為 urn:oasis:names:tc:SAML:2.0:cm:bearer 的 SubjectConfirmation 元素。
  • 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 的 Google Cloud 專案專案編號。
    • POOL_ID：您選擇的 ID，用於識別 workload identity pool。日後建立工作負載身分集區時，必須使用相同的 ID。
    • WORKLOAD_PROVIDER_ID：您選擇的 ID，用於識別 workload identity pool 提供者。稍後建立 Workload Identity 集區供應商時，必須使用相同的 ID。

• 至少一個 AuthnStatement 元素。

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

如要將 SAML 判斷陳述式封裝在 SAML 回應中，SAML 回應必須包含：

• 正好一個符合 SAML 判斷準則的判斷結果，如本節稍早所述。
• IssueInstant 屬性的值是過去不到 1 小時的時間。
• StatusCode urn:oasis:names:tc:SAML:2.0:status:Success。

SAML 聲明、回應或兩者都必須簽署。

OIDC

屬性對應可以使用外部 IdP 發布的 ID 權杖或存取權杖中內嵌的聲明。

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

許多 IdP 會使用不變的專屬 ID 填入 sub 聲明。對於這些 IdP，請考慮將 sub 聲明對應至 google.subject：

google.subject=assertion.sub

請避免使用「email」等聲明。電子郵件地址通常可以重新指派或變更，因此無法做為使用者的永久唯一識別碼。

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 的屬性。電子郵件地址通常可以重新指派或變更，因此無法做為使用者永久的專屬識別碼。

OIDC

您可以使用屬性條件，限制哪些使用者可透過 Workload Identity 聯盟取得短期 Google Cloud權杖。

舉例來說，下列條件會限制存取權，只允許含有自訂 service_account 聲明且值為 true 的權杖：

assertion.service_account==true

SAML

您可以使用屬性條件，限制哪些使用者可透過 Workload Identity 聯盟取得短期 Google Cloud權杖。

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

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

主控台

1. 前往 Google Cloud 控制台的「New workload provider and pool」(新的工作負載供應商和集區) 頁面。

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

2. 在「建立身分集區」下方，輸入下列資訊：

   • 名稱：集區名稱。這個名稱也會用來做為集區 ID。 集區 ID 設定後即無法變更。
   • 說明：說明集區用途的文字。

3. 按一下「繼續」。

4. 設定提供者設定，步驟如下：

   OIDC

   • 在「選取提供者」中，選取「OpenID Connect (OIDC)」。
   • 在「供應商名稱」中，輸入供應商名稱。這個名稱也會做為供應商 ID。供應商建立完成後，即無法變更供應商 ID。
   • 在「核發者網址」中，輸入 IdP 的核發者網址。網址開頭必須為 https://
   • 選用：在「JWK 檔案 (JSON)」中，選擇要上傳的 JWK 檔案。 如果未提供這個欄位，系統會嘗試從簽發者擷取 JWK。 Google Cloud
   • 允許的目標對象：ID 權杖的預期目標對象。

   SAML

   • 在「選取供應商」中，選取「SAML」。
   • 在「供應商名稱」中，輸入供應商名稱。這個名稱也會做為供應商 ID。供應商建立完成後，即無法變更供應商 ID。
   • 在「IDP Metadata file (XML)」部分，上傳識別資訊提供者提供的 SAML 中繼資料 XML 文件。

5. 按一下「繼續」。

6. 在「設定供應商屬性」下方，新增您在本指南稍早識別的屬性對應。

7. 在「屬性條件」下方，輸入您稍早在本指南中識別的屬性條件。如果沒有屬性條件，請將欄位留空。

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

gcloud

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

   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 工作負載身分集區提供者，請執行下列指令：

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

   更改下列內容：

   • WORKLOAD_PROVIDER_ID：您選擇的專屬 workload identity pool 提供者 ID。
   • POOL_ID：您先前建立的工作負載身分集區 ID。
   • ISSUER：OIDC 中繼資料中定義的核發者 URI。
   • AUDIENCE：ID 權杖的預期目標對象，對許多供應商而言，這與用戶端 ID 相符。
   • MAPPINGS：以半形逗號分隔的屬性對應清單，您已在本指南稍早建立這些對應。
   • CONDITIONS：您在本指南稍早建立的屬性條件 (選用)。如果沒有屬性條件，請移除參數。
   • JWK_JSON_PATH：本機上傳的 OIDC JWK 的選用路徑。如果未提供這個參數， Google Cloud 會改用 IdP 的 /.well-known/openid-configuration 路徑，從中取得含有公開金鑰的 JWK。

   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 產生可供工作負載身分識別聯盟接受的加密 SAML 聲明，請按照下列步驟操作：

   • 在 Workload Identity 聯盟中，請執行下列操作：
   • 為工作負載身分集區提供者建立非對稱金鑰組。
   • 下載內含公開金鑰的憑證檔案。
   • 將 SAML IdP 設為使用公開金鑰，加密發出的 SAML 聲明。
   • 在 IdP 中執行下列操作：
   • 啟用斷言加密，也稱為權杖加密。
   • 上傳您在 Workload Identity 聯盟中建立的公開金鑰。
   • 確認 IdP 會產生加密的 SAML 斷言。

   請注意，即使已設定 SAML 加密提供者金鑰，Workload Identity 聯盟仍可處理明文聲明。

   建立 Workload Identity 聯盟 SAML 聲明加密金鑰

   本節將逐步說明如何建立非對稱金鑰組，讓 Workload Identity 聯盟接受加密的 SAML 聲明。

   Google Cloud 會使用私密金鑰解密 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 聯盟可以存取私密金鑰。

   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 聯盟仍可處理明文聲明。

   刪除 Workload Identity 聯盟加密金鑰

   如要刪除 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 聯盟支援下列金鑰傳輸演算法：

   • http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p
   • http://www.w3.org/2009/xmlenc11#rsa-oaep"
   • http://www.w3.org/2001/04/xmlenc#rsa-1_5"

   Workload Identity 聯盟支援下列區塊加密演算法：

   • http://www.w3.org/2001/04/xmlenc#aes128-cbc
   • http://www.w3.org/2001/04/xmlenc#aes192-cbc
   • http://www.w3.org/2001/04/xmlenc#aes256-cbc
   • http://www.w3.org/2009/xmlenc11#aes128-gcm
   • http://www.w3.org/2009/xmlenc11#aes256-gcm

直接存取資源

您可以使用 Google Cloud 控制台或 gcloud CLI，直接在資源上授予聯盟身分存取權。

服務帳戶模擬

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

   1. Enable the IAM, Security Token Service, and Service Account Credentials APIs.

      Enable the APIs

   2. 建立服務帳戶，代表工作負載。建議您為每個工作負載使用專屬服務帳戶。服務帳戶不必與工作負載身分集區位於同一專案，但您必須參照包含服務帳戶的專案。

   3. 授予服務帳戶存取權，允許外部身分存取資源。

2. 如要允許聯合身分模擬服務帳戶，請執行下列操作：

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"

可執行檔來源憑證

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 \
    --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：工作負載身分集區的 ID。
• WORKLOAD_PROVIDER_ID：工作負載身分集區提供者的 ID。
• SERVICE_ACCOUNT_EMAIL：如果您使用服務帳戶模擬功能，請改用服務帳戶的電子郵件地址。如果您未使用服務帳戶模擬功能，請省略這個旗標。
• SERVICE_ACCOUNT_TOKEN_LIFETIME：如果您使用服務帳戶模擬，請以服務帳戶存取權杖的生命週期 (以秒為單位) 取代；如果未提供，預設為一小時。如果您未使用服務帳戶模擬功能，請省略這個旗標。如要指定超過一小時的生命週期，請設定constraints/iam.allowServiceAccountCredentialLifetimeExtension 機構政策限制。
• FILEPATH：要儲存設定的檔案。
• EXECUTABLE_COMMAND：完整指令，包括要執行的引數，用於擷取 OIDC ID 權杖，例如 --executable-command="/path/to/command --foo=bar"。
• EXECUTABLE_TIMEOUT：等待可執行檔執行的選用時間 (以毫秒為單位)，預設為 30 秒。
• EXECUTABLE_OUTPUT_FILE：指向可執行檔產生的第三方憑證路徑。這對快取憑證很有幫助。指定這個路徑後，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 \
    --output-file=FILEPATH.json \
    --credential-source-file=TOKEN_FILEPATH \
    --credential-source-type=SOURCE_TYPE \
    --credential-source-field-name=FIELD_NAME

更改下列內容：

• PROJECT_NUMBER：包含 workload identity pool 的專案專案編號。
• POOL_ID：工作負載身分集區的 ID。
• WORKLOAD_PROVIDER_ID：工作負載身分集區提供者的 ID。
• SERVICE_ACCOUNT_EMAIL：如果您使用服務帳戶模擬功能，請改用服務帳戶的電子郵件地址。如果您未使用服務帳戶模擬功能，請省略這個旗標。
• SERVICE_ACCOUNT_TOKEN_LIFETIME：如果您使用服務帳戶模擬，請以服務帳戶存取權杖的生命週期 (以秒為單位) 取代；如果未提供，預設為一小時。如果您未使用服務帳戶模擬功能，請省略這個旗標。如要指定超過一小時的生命週期，請設定constraints/iam.allowServiceAccountCredentialLifetimeExtension 機構政策限制。
• FILEPATH：用於儲存設定的檔案。
• TOKEN_FILEPATH：儲存 OIDC ID 權杖的路徑。
• SOURCE_TYPE：OIDC ID 權杖檔案的格式，可設為 text (預設) 或 json。
• FIELD_NAME：文字檔中包含權杖的欄位 (如果 SOURCE_TYPE 為 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 \
    --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：工作負載身分集區的 ID。
• WORKLOAD_PROVIDER_ID：工作負載身分集區提供者的 ID
• SERVICE_ACCOUNT_EMAIL：如果您使用服務帳戶模擬功能，請將此值替換為服務帳戶的郵件地址。如果您未使用服務帳戶模擬功能，請省略這個旗標。
• SERVICE_ACCOUNT_TOKEN_LIFETIME：如果您使用服務帳戶模擬，請以服務帳戶存取權杖的生命週期 (以秒為單位) 取代；如果未提供，預設為一小時。如果您未使用服務帳戶模擬功能，請省略這個旗標。如要指定超過一小時的生命週期，請設定constraints/iam.allowServiceAccountCredentialLifetimeExtension 機構政策限制。
• FILEPATH：要儲存設定的檔案。
• TOKEN_URL：用於擷取 OIDC ID 權杖的網址
• KEY_n、VALUE_n：要納入對 TOKEN_URL 的 HTTP 要求中的自訂標頭
• SOURCE_TYPE：OIDC ID 權杖檔案的格式，請設為 text (預設) 或 json
• FIELD_NAME：文字檔中包含權杖的欄位 (如果 SOURCE_TYPE 為 json)