使用 Active Directory 設定 Workload Identity Federation

本指南說明如何使用 Workload Identity Federation，讓工作負載使用 Active Directory 憑證向 Google Cloud進行驗證。

如果您在 Active Directory 環境中執行 Windows Server 工作負載，這些工作負載可能可以存取 Active Directory 憑證。例如：

  • Windows 服務可能已設定為以網域使用者身分登入。
  • IIS 應用程式可能會設定為以群組代管服務帳戶 (gMSA) 執行。

結合使用 Workload Identity 聯盟和 Active Directory 同盟服務 (AD FS)，即可讓這些工作負載將 Active Directory Kerberos 憑證換成短期 Google Cloud 憑證。工作負載可使用這些短期憑證存取 Google CloudAPI。

如要使用 Active Directory 憑證換取短期憑證，請 Google Cloud串連兩個權杖交換作業：

  1. 工作負載會使用 OpenID Connect (OIDC)、SAML-POST 或 WS-Trust，向 AD FS 要求 OIDC 憑證或 SAML 聲明。如要向 AD FS 進行驗證，工作負載會使用整合式 Windows 驗證 (IWA) 和現有的 Active Directory 憑證。
  2. 然後，工作負載會使用 Workload Identity Federation，將 OIDC 權杖或 SAML 聲明與 Security Token Service 權杖交換，並視需要模擬 Google Cloud 服務帳戶。

本文說明如何使用 Windows 適用的工作負載驗證器，自動執行這項程序，且不需要變更應用程式。

準備 AD FS

這些步驟只需要執行一次。

選取通訊協定

準備 AD FS 的方式取決於您要使用的通訊協定：

  • SAML：您可以允許工作負載使用 SAML 或 WS-Trust 取得 SAML 宣告。

    如要使用 SAML 或 WS-Trust，請在 AD FS 中建立「信賴憑證者」，並設定工作負載身分集區，以信任為這個信賴憑證者核發的聲明。

    工作負載可以使用 Active Directory 使用者，透過 SAML-POST 繫結或 WS-Trust 向 AD FS 進行驗證。AD FS 接著會發出 SAML 判斷，其中包含工作負載的 Active Directory 使用者資訊，以及群組成員資格等其他資訊。

    如要使用 SAML 或 WS-Trust，必須使用 AD FS 3.0、適用於 Windows Server 2016 的 AD FS，或更新版本的 AD FS。

  • OIDC：您可以讓工作負載使用 OIDC 取得 OIDC 權杖。

    如要使用 OIDC，請在 AD FS 中建立 OIDC 用戶端 (原生應用程式) 和 OIDC 資源 (Web API)。然後設定工作負載身分集區，信任為 Web API 發行的存取權杖。

    工作負載可以使用 Active Directory 使用者和 OAuth 授權，向 AD FS 進行驗證。client_credentialsAD FS 接著會核發存取權杖，但不會核發 ID 權杖。

    存取權杖包含 OIDC 用戶端應用程式的相關資訊，但不包含工作負載的 Active Directory 使用者或群組成員資格資訊。

    由於存取權權杖不含 Active Directory 使用者資訊，因此使用 OIDC 可能不如使用 SAML 或 WS-Trust 靈活。

    如要使用 OIDC，必須使用 Windows Server 2016 版 AD FS，或更新版本的 AD FS。

如要登入，您的 IdP 必須提供已簽署的驗證資訊：OIDC IdP 必須提供 JWT，且 SAML IdP 回應必須經過簽署。

IWA 必備條件

本節說明使用本指南的必要 IWA 前提條件。

如果您先前未使用 AD FS 搭配 IWA，請確認您符合下列先決條件：

註冊工作負載

如要在 AD FS 中註冊工作負載，請按照下列步驟操作：

OIDC

如要讓工作負載使用 OIDC，您需要在 AD FS 中進行兩項應用程式註冊：

  • 類型為「原生應用程式」或「伺服器應用程式」的應用程式註冊。

  • 類型為「Web API」的應用程式註冊，對應於 Google Cloud上的工作負載身分集區提供者。

註冊用戶端應用程式

建立代表工作負載的用戶端應用程式。如果您有多個工作負載需要存取 Google Cloud，可能需要建立多個用戶端應用程式。

如要在 AD FS 中註冊用戶端應用程式，請按照下列步驟操作：

  1. 開啟 AD FS MMC 嵌入式管理單元，然後前往「應用程式群組」。
  2. 按一下「新增應用程式群組」。

  3. 在「歡迎」頁面中，執行下列操作：

    1. 在文字欄位中輸入用戶端名稱。
    2. 選取「伺服器應用程式」。
    3. 點選「下一步」。

  4. 在「伺服器應用程式」頁面中，執行下列操作：

    1. 在文字欄位中，輸入用戶端 ID 和重新導向 URI。

      如果您只打算使用 client_credentials 授權類型，系統不會使用重新導向 URI，您可以採用 http://localhost/ 等 URI。

    2. 點選「下一步」。

  5. 在「設定應用程式憑證」頁面中，執行下列操作：

    1. 選擇用戶端的驗證方式。如要使用 IWA，請將「Windows 整合式驗證」設為「已啟用」。
    2. 選取應用程式設定要以哪個網域使用者身分執行。
    3. 點選「下一步」。

  6. 在「摘要」頁面中檢查設定，然後按一下「下一步」。

  7. 按一下「關閉」即可關閉對話方塊。

為工作負載身分集區建立 Web API 應用程式

建立另一個「Web API」類型的應用程式註冊。這個應用程式對應於 workload identity pool 提供者，您可以使用這個應用程式設定與 Google Cloud的信任關係。

如要在 AD FS 中建立應用程式，請按照下列步驟操作：

  1. 開啟 AD FS MMC 嵌入式管理單元，然後前往「應用程式群組」。
  2. 按一下「新增應用程式群組」。
  3. 在「歡迎」頁面中輸入名稱 (例如 Workload Identity Federation (test environment))，然後選取「Web API」。然後點選「下一步」。

  4. 在「設定 Web API」頁面中，輸入 Web API 的信賴方 ID。

    您可以將下列 URI 做為信賴方 ID，不必定義自訂信賴方 ID：

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

    更改下列內容：

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

    以這種方式設定 URI 格式，可確保信賴憑證者 ID 能夠唯一識別工作負載身分集區提供者。

    稍後設定 workload identity pool 提供者時，需要使用依賴方 ID。

  5. 點選「下一步」。

  6. 在「套用存取控管政策」頁面中，選取適當的存取政策，然後按一下「下一步」。

  7. 在「設定應用程式權限」頁面中，新增您先前建立的用戶端應用程式。然後點選「下一步」。

  8. 在「摘要」頁面中檢查設定，然後按一下「下一步」。

  9. 按一下「關閉」即可關閉對話方塊。

SAML 或 WS-Trust

在 AD FS 中建立信賴憑證者信任：

  1. 開啟 AD FS MMC 嵌入式管理單元。
  2. 前往「信賴憑證者信任」。
  3. 按一下「新增信賴憑證者信任」。
  4. 在「新增信賴憑證者信任」精靈的「歡迎」頁面中，執行下列操作：
    1. 選取「已瞭解著作權聲明」
    2. 按一下「啟動」。
  5. 在「選取資料來源」頁面中，執行下列操作：
    1. 選取「Enter data about the relying party manually」(手動輸入這個信賴憑證者的相關資料)。
    2. 點選「下一步」。

  6. 在「指定顯示名稱」頁面中，執行下列操作：

    1. 輸入信任關係的名稱。
    2. 點選「下一步」。

  7. 在「設定憑證」頁面中，按一下「下一步」。工作負載身分聯盟支援加密的 SAML，但本程序未說明相關步驟。詳情請參閱本指南後續章節「建立身分識別集區和提供者」中的 gcloud CLI 指令。

  8. 在「設定網址」頁面中，執行下列操作：

    SAML

    請使用下列設定：

    • 將「Enable support for the SAML 2.0 WebSSO protocol」設為「enabled」

    • 在「Relying party SAML 2.0 SSO service URL」(信賴方 SAML 2.0 單一登入服務網址) 欄位中，輸入下列網址：

      https://sts.googleapis.com/v1/token

    WS-Trust

    保留預設設定

  9. 點選「下一步」。

  10. 在「設定 ID」頁面中，輸入信賴方 ID。

    您可以將下列 URI 做為信賴方 ID，不必定義自訂信賴方 ID：

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

    更改下列內容：

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

    以這種方式設定 URI 格式，可確保信賴憑證者 ID 能夠唯一識別工作負載身分集區提供者。

    稍後設定 workload identity pool 提供者時，需要使用依賴方 ID。

  11. 點選「下一步」。

  12. 在「選擇存取控管政策」頁面中，選取適當的存取控管政策，然後按一下「下一步」。

  13. 在「Ready to add trust」(準備新增信任) 頁面，檢查設定並按一下「Next」(下一步)。

  14. 在「完成」頁面中，按一下「關閉」即可關閉對話方塊。

如要與 Workload Identity Federation 相容，SAML 判斷必須包含至少一項聲明，用來識別 Active Directory 使用者。一般來說，您會使用名稱 ID 宣告來達成這個目的，這對應於 SAML 宣告中 NameID 元素的值。

如要自訂 SAML 判斷的聲明集，請編輯信賴憑證者信任的聲明發行政策。如要編輯兌換憑證發放政策，請按照下列步驟操作：

  1. 在信賴憑證者信任清單中，選取您剛建立的信任，然後點選「編輯宣告發行原則」。
  2. 按一下「新增規則」
  3. 在「新增轉換宣告規則」精靈的「選擇規則類型」頁面，執行下列操作：
    1. 選取「轉換收到的著作權聲明」。
    2. 點選「下一步」。

  4. 在「設定宣告規則」頁面中，設定下列項目：

    • 宣告規則名稱：Name Identifier。
    • 傳入的聲明類型：選取「主要 SID」、「UPN」或不同聲明，以唯一識別主體。
    • 傳出宣告類型：名稱 ID。
    • 傳出名稱 ID 格式：未指定。

  5. 選取「Pass through all claim values」(傳遞所有聲明值)，然後按一下「Finish」(完成)。

  6. 視需要設定其他規則，在 SAML 聲明中納入更多屬性。

  7. 按一下「確定」關閉聲明核發政策對話方塊。

設定 Workload Identity 聯盟

針對要與其同盟的每個 Microsoft Active Directory 網域，這些步驟只需要執行一次。然後，您就能將相同的工作負載身分識別集區和提供者用於多個工作負載，以及多個專案。Google Cloud

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

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

    Go to project selector

    2. 建議您 使用專案管理 workload identity pool 和提供者。

  2. Make sure that billing is enabled for your Google Cloud project.

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

    Enable the APIs

定義屬性對應和條件

Active Directory 工作負載的環境專屬憑證包含多個屬性，您必須決定要將哪個屬性做為 google.subject 中的主體 ID ( Google Cloud)。

你也可以視需要對應其他屬性。 授予資源存取權時，您可以參考這些額外屬性。

OIDC

屬性對應可以使用AD FS 存取權杖中內嵌的聲明做為來源屬性。

如要驗證應用程式，可以使用下列屬性對應：

google.subject=assertion.appid

這項對應會將 google.subject 設為 appid 聲明的值，其中包含 AD FS 應用程式的用戶端 ID。

SAML 或 WS-Trust

如本指南先前所述，屬性對應可使用 AD FS 發出的聲明中內嵌的聲明。

使用下列對應，讓 Workload Identity 聯盟使用 SAML 判斷中的「名稱 ID」聲明，以專屬方式識別使用者：

google.subject=assertion.subject

如果您已將聲明核發政策設為在 SAML 判斷中加入額外聲明，可以新增其他對應。例如：

google.groups=assertion.attributes['http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid']
attribute.userip=['http://schemas.microsoft.com/2014/09/requestcontext/claims/userip'][0]

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

OIDC

您可以使用屬性條件，限制哪些用戶端可使用 Workload Identity 聯盟取得短期存留期權杖。Google Cloud

舉例來說，下列條件定義應用程式必須使用 IWA 向 AD FS 進行驗證：

assertion.authmethod=='http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/windows'

如要控管可取得 Google Cloud短期憑證的應用程式清單，請勿定義屬性條件。請改用 AD FS 中的用戶端權限，定義允許的應用程式。

SAML 或 WS-Trust

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

舉例來說，下列條件只允許包含特定群組成員資格聲明的 SAML 判斷：

"S-1-5-6" in google.groups

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

必要的角色

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

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

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

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

主控台

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

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

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

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

  3. 按一下「繼續」。

  4. 設定提供者設定：

    OIDC

    • 選取供應商：OpenID Connect (OIDC)。
    • 供應商名稱：供應商的名稱。這個名稱也會做為提供者 ID。供應商 ID 設定後即無法變更。
    • 核發者網址：https://ADFS_DOMAIN/adfs，其中 ADFS_DOMAIN 是 AD FS 伺服器或伺服器陣列的公開網域名稱。

    SAML

    如要從 SAML 2.0 相容的 IdP 設定 Workload Identity Federation，請使用 gcloud CLI 指令。

  5. 按一下「繼續」。

  6. 在「設定供應商屬性」下方，新增先前識別的屬性對應。

  7. 在「屬性條件」下方，輸入先前識別的屬性條件。 如果沒有屬性條件，請將這個欄位留空。

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

gcloud

  1. 建立新的 workload identity pool：

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

    更改下列內容：

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

  2. 新增工作負載身分集區提供者：

    OIDC 

    gcloud iam workload-identity-pools providers create-oidc WORKLOAD_PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="WORKLOAD_POOL_ID" \
    --issuer-uri="https://ADFS_DOMAIN/adfs" \
    --allowed-audiences="RELYING_PARTY_ID" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"

    更改下列內容：

    前置字串「gcp-」為預留字串，不得用於工作團隊身分集區或工作團隊身分集區提供者 ID。

    SAML 或 WS-Trust 

    curl -O https://ADFS_DOMAIN/federationmetadata/2007-06/federationmetadata.xml

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

    更改下列內容：

    • WORKLOAD_PROVIDER_ID：供應商的專屬 ID。
    • ADFS_DOMAIN：AD FS 伺服器或伺服器叢集的網域名稱。
    • WORKLOAD_POOL_ID：集區的 ID。
    • MAPPINGS：以半形逗號分隔的屬性對應清單 (先前已識別)。
    • CONDITIONS：選用：您在本指南稍早建立的屬性條件。

    前置字串「gcp-」為預留字串，不得用於工作團隊身分集區或工作團隊身分集區提供者 ID。

    範例：

    gcloud iam workload-identity-pools providers create-saml example-provider \
    --location="global" \
    --workload-identity-pool="pool-1" \
    --idp-metadata-path="federationmetadata.xml" \
    --attribute-mapping=google.subject=assertion.subject"

    選用：接受來自 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 聲明

    1. 將憑證檔案移至 AD FS 伺服器。
    2. 在 AD FS 伺服器上，以滑鼠右鍵按一下「開始」按鈕 (或按下 Win+X)，然後按一下「Windows PowerShell (系統管理員)」。
    3. 在 PowerShell 中執行下列指令，啟用加密功能： 
              Set-AdfsRelyingPartyTrust `
        -TargetName NAME `
        -SamlResponseSignature MessageAndAssertion `
        -EncryptionCertificate PATH `
        -EncryptClaims $True

      取代下列項目：

      • NAME：信賴方信任的名稱
      • PATH：憑證檔案的路徑

    WS-Trust 使用者：這項功能僅適用於 SAML。

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

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

選用：啟用 SAML 加密

AD FS 核發的 SAML 聲明會經過加密簽署，並透過加密的 TLS 管道交換。不過，SAML 聲明本身並未加密。使用 SAML 加密功能，您可以設定 AD FS 來加密聲明，這樣一來，只有工作負載身分集區可以解密及讀取聲明。

OIDC

這項功能僅適用於 SAML。

SAML 或 WS-Trust

  1. 為工作負載身分集區提供者建立加密金鑰：

    gcloud iam workload-identity-pools providers keys create rsa2048 \
    --workload-identity-pool=POOL_ID \
    --provider=WORKLOAD_PROVIDER_ID \
    --location=global \
    --use=ENCRYPTION \
    --spec=RSA_2048

    更改下列內容：

    • WORKLOAD_PROVIDER_ID：供應商 ID。
    • POOL_ID：集區的 ID。

    金鑰配對由 Workload Identity 聯盟儲存及管理。您可以匯出公開金鑰，但只有 Workload Identity Federation 可以存取私密金鑰。

  2. 匯出包含公開金鑰的憑證：

    gcloud iam workload-identity-pools providers keys describe rsa2048 \
    --workload-identity-pool=POOL_ID \
    --provider=WORKLOAD_PROVIDER_ID \
    --location=global \
    --format="value(keyData.key)" > workload-identity-federation.cer

  3. 將憑證檔案移至 AD FS 伺服器。

  4. 在 AD FS 伺服器上，以滑鼠右鍵按一下「開始」，然後按一下「Windows PowerShell (系統管理員)」。

  5. 在 PowerShell 中修改信賴憑證者信任，使其使用加密功能：

    Set-AdfsRelyingPartyTrust `
  -TargetName NAME `
  -SamlResponseSignature MessageAndAssertion `
  -EncryptionCertificate PATH `
  -EncryptClaims $True

    更改下列內容：

    • NAME：信賴方信任的名稱
    • PATH：憑證檔案的路徑

驗證工作負載

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

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

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

直接存取資源

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

控制台

如要使用 Google Cloud 控制台直接在資源上授予 IAM 角色，請前往資源頁面，然後授予角色。下列範例說明如何前往 Cloud Storage 頁面，並直接在 Cloud Storage bucket 上，將「Storage 物件檢視者」(roles/storage.objectViewer) 角色授予同盟身分。

  1. 在 Google Cloud 控制台，前往「Cloud Storage bucket」頁面。

    前往「Buckets」(值區) 頁面

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

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

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

    系統會顯示「新增主體」對話方塊。

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

    依科目

    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
    • ：從 IdP 對應的群組，例如： administrator-group@example.comGROUP

    依屬性

    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. 按一下 [儲存]。

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：要授予存取權的值區
    • PROJECT_NUMBER：含有 workload identity pool 的專案專案編號。
    • POOL_ID：工作負載身分集區的集區 ID
    • SUBJECT：您已對應至 google.subject 的屬性預期值
    • GROUP：您已對應至 google.groups 的屬性預期值
    • ATTRIBUTE_NAME：屬性對應中的自訂屬性名稱
    • ATTRIBUTE_VALUE：屬性對應中自訂屬性的值

    您可以在任何支援 IAM 允許政策的 Google Cloud 資源上授予角色。

服務帳戶模擬

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

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

      Enable the APIs

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

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

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

控制台

如要使用 Google Cloud 控制台，將 IAM 角色授予具有服務帳戶的同盟身分，請按照下列步驟操作：

同一專案中的服務帳戶

  1. 如要使用服務帳戶模擬功能，為同一專案中的服務帳戶授予存取權，請執行下列步驟：

    1. 前往「Workload Identity Pools」(工作負載身分集區) 頁面。

      前往「Workload Identity Pools」(工作負載身分集區)

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

    3. 在「授予服務帳戶存取權」對話方塊中，選取「透過服務帳戶模擬功能授予存取權」。

    4. 在「服務帳戶」清單中，選取要讓外部身分模擬的服務帳戶，然後執行下列操作：

    5. 如要選擇集區中的哪些身分可以模擬服務帳戶，請執行下列其中一項操作：

      • 如要只允許工作負載身分識別集區的特定身分模擬服務帳戶，請選取「只顯示符合篩選條件的身分」。

      • 在「屬性名稱」清單中，選取要篩選的屬性。

      • 在「屬性值」欄位中，輸入屬性的預期值；舉例來說，如果您使用屬性對應 google.subject=assertion.sub，請將「屬性」名稱設為 subject，並將「屬性值」設為外部身分識別提供者核發的權杖中 sub 聲明的值。

    6. 如要儲存設定，請依序按一下「儲存」和「關閉」。

其他專案中的服務帳戶

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

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

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

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

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

    4. 按一下「新增主體」。

    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
      • ：從 IdP 對應的群組，例如： administrator-group@example.comGROUP

      依屬性

      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 User 角色 (roles/iam.workloadIdentityUser)。

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

gcloud

如要將 Workload Identity 使用者角色 (roles/iam.workloadIdentityUser) 授予已同盟主體或主體集，請執行下列指令。如要進一步瞭解 Workload Identity 聯盟主體 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：工作負載身分集區的集區 ID
  • SUBJECT：您已對應至 google.subject 的屬性預期值
  • GROUP：您已對應至 google.groups 的屬性預期值
  • ATTRIBUTE_NAME：屬性對應中的自訂屬性名稱
  • ATTRIBUTE_VALUE：屬性對應中自訂屬性的值

建立憑證設定

您可以透過 Windows 適用的工作負載驗證器，讓 Cloud 用戶端程式庫和 gcloud CLI 與 Terraform 等工具使用 Active Directory 憑證向 Google Cloud 進行驗證。

Windows 適用的 Workload Authenticator 是一種開放原始碼工具，可做為 Cloud Client Libraries 和 gcloud CLI 等工具的外掛程式：

  1. 當工具或程式庫需要新憑證時，會在背景啟動 Workload Authenticator。
  2. Workload Authenticator 會使用 OIDC、SAML 或 WS-Trust，從 AD FS 取得新的權杖或 SAML 聲明，然後傳回給工具或程式庫。
  3. 然後，工具或程式庫會使用 Workload Identity Federation，以權杖或 SAML 宣告換取短期 Google Cloud 憑證。

如要在 Windows 上使用 Workload Authenticator，您必須建立憑證設定檔。這個檔案定義了下列項目：

  • Windows 可執行檔 (wwauth.exe) 的 Workload Authenticator 所在位置，以及執行時使用的參數
  • 要使用的 workload identity pool 和提供者
  • 要模擬哪個服務帳戶

如要建立憑證設定檔，請在執行工作負載的 Windows Server 上執行下列操作：

  1. 在「開始」按鈕上按一下滑鼠右鍵 (或按下 Win+X 鍵)，然後按一下「Windows PowerShell」。

  2. 下載 Windows 適用的工作負載驗證器，並儲存至工作負載可存取的位置：

    (New-Object Net.WebClient).DownloadFile(
  "https://github.com/GoogleCloudPlatform/iam-windows-authenticator/releases/latest/download/wwauth.exe",
  "${env:ProgramData}\wwauth.exe")

    如果您使用 Windows 適用的 Workload Authenticator 建立憑證設定檔，該檔案會包含可執行檔的路徑。如果之後刪除或移動可執行檔，工作負載就無法找到並使用該檔案。

  3. 啟動 wwauth.exe：

    & ${env:ProgramData}\wwauth.exe

    系統會開啟設定對話方塊：

    Workload Authenticator

  4. 選取「AD FS」分頁標籤，然後輸入下列設定：

    • AD FS 伺服器的簽發者 URI：AD FS 伺服器或伺服器陣列的公開 URI。

      https://ADFS_DOMAIN/adfs/

      將 ADFS_DOMAIN 替換為 AD FS 伺服器或伺服器陣列的公開網域名稱。

    接下來的設定取決於您想使用的通訊協定：

    OIDC

    • 「Protocol」(通訊協定)：AdfsOidc
    • 信賴憑證者 ID：保留預設值。
    • 用戶端 ID：AD FS 中伺服器應用程式的用戶端 ID。

    SAML

    • 「Protocol」(通訊協定)：AdfsSamlPost
    • 宣告消費者服務網址：https://sts.googleapis.com/v1/token。
    • 使用憑證簽署要求：已停用

    WS-Trust

    • 「Protocol」(通訊協定)：AdfsWsTrust

  5. 選取「Workload Identity」分頁標籤，然後輸入下列設定：

    • 專案編號：包含工作負載身分集區的專案編號
    • 集區 ID：workload identity pool 的 ID
    • 提供者 ID：工作負載身分集區提供者的 ID
    • 模擬服務帳戶：已啟用 (如果您使用服務帳戶模擬功能)
    • 電子郵件地址：服務帳戶的電子郵件地址 (如果您使用服務帳戶模擬功能)

  6. 選取「AD FS」分頁，並確認「Relying Party ID」欄位現在包含 workload identity pool 提供者的網址。

  7. 按一下「套用」，然後選擇檔案位置，將憑證設定檔案儲存至該處。

    與服務帳戶金鑰不同，憑證設定檔不含任何密鑰，也不需要保密。如要進一步瞭解憑證設定檔，請參閱 https://google.aip.dev/auth/4117。

現在可以測試設定：

  1. 選取要測試的 Active Directory 使用者。這可以是工作負載的 Active Directory 使用者，也可以是您目前登入的使用者。

  2. 如要使用目前使用者測試設定，請按一下「測試」。

    如要使用其他使用者進行測試，請依序選取「測試」>「以使用者身分測試設定」，然後輸入該使用者的憑證。

    這項工具現在會嘗試驗證 Google Cloud ，方法是執行下列步驟：

    1. 從 AD FS 取得 OIDC 權杖或 SAML 聲明。
    2. 取得 Google Security Token Service 權杖。
    3. 如果您使用服務帳戶模擬功能，請模擬服務帳戶。

    如果驗證成功，畫面會顯示「測試已順利完成」訊息：

    測試結果

使用憑證設定存取 Google Cloud

如要讓工具和用戶端程式庫使用您的憑證設定，請在執行工作負載的 Windows Server 上執行下列操作：

  1. 在「開始」按鈕上按一下滑鼠右鍵，然後點選「執行」。
  2. 輸入 sysdm.cpl，然後按一下 [OK] (確定)。
  3. 在「進階」分頁標籤中，按一下「環境變數」。

  4. 在「系統變數」部分，新增兩個變數：

    名稱 值
    GOOGLE_APPLICATION_CREDENTIALS 憑證設定檔的路徑
    GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES 1

  5. 按一下 [確定]。

  6. 使用支援 Workload Identity 聯盟且可自動尋找憑證的用戶端程式庫或工具：

    C++

    自 v2.6.0 版起，Google Cloud C++ 用戶端程式庫支援 Workload Identity Federation。如要使用 Workload Identity 聯盟，您必須使用 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 適用的用戶端程式庫使用 com.google.auth:google-auth-library-oauth2-http構件 0.24.0 以上版本，即可支援 Workload Identity 聯盟。

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

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

    Node.js

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

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

    npm list google-auth-library

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

    Python

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

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

    pip show google-auth

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

    gcloud

    如要使用 Workload Identity 聯盟進行驗證，請使用 gcloud auth login 指令：

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

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

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

    Terraform

    如果您使用 3.61.0 以上版本，Google Cloud 供應商支援工作負載身分聯盟：

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

    bq

    如要使用 Workload Identity 聯盟進行驗證，請使用 gcloud auth login 指令，如下所示：

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

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

    如要在 bq 中使用 Workload Identity Federation，請使用 gcloud CLI 390.0.0 以上版本。

後續步驟