設定員工身分聯盟

本指南說明如何使用支援 OIDC 或 SAML 2.0 的身分識別提供者 (IdP) 設定員工身分聯盟。

如需 IdP 專屬操作說明，請參閱下列文章：

• 設定以 Microsoft Entra ID 為基礎的員工身分聯盟
• 設定以 Okta 為基礎的員工身分聯盟

事前準備

1. 確認您已 Google Cloud 設定機構。

2. After installing the Google Cloud CLI, initialize it by running the following command:

   gcloud init

   If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

3. Enable the Identity and Access Management (IAM) and Resource Manager APIs.

   Enable the APIs

4. 如要登入，您的 IdP 必須提供已簽署的驗證資訊：OIDC IdP 必須提供 JWT，且 SAML IdP 回應必須經過簽署。
5. 如要接收貴機構或產品的異動相關重要資訊，請務必提供必要聯絡人。Google Cloud 詳情請參閱「員工身分聯盟總覽」。

費用

員工身分聯盟是免付費功能。不過，員工身分聯盟詳細稽核記錄會使用 Cloud Logging。如要瞭解 Logging 定價，請參閱 Google Cloud Observability 定價。

必要的角色

如要取得設定員工身分聯盟所需的權限，請要求管理員授予您機構的員工身分集區管理員 (roles/iam.workforcePoolAdmin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

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

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

設定員工身分聯盟

如要設定員工身分聯盟，請建立員工身分集區和員工身分集區提供者。

建立工作團隊身分集區

如要建立集區，請執行下列指令：

gcloud iam workforce-pools create WORKFORCE_POOL_ID \
    --organization=ORGANIZATION_ID \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --session-duration=SESSION_DURATION \
    --location=global

建立工作團隊身分集區提供者

本節說明如何建立員工身分識別集區供應商，讓 IdP 使用者存取 Google Cloud。您可以設定提供者使用 OIDC 或 SAML 通訊協定。

建立 OIDC 工作團隊集區提供者

如要使用 OIDC 通訊協定建立工作團隊身分集區提供者，請執行下列步驟：

1. 在 OIDC IdP 中，為 Google Cloud員工身分聯盟註冊新應用程式。請記下 IdP 提供的用戶端 ID 和簽發者 URI。您會在本文中使用這些值。

2. 如要設定使用者存取控制台的權限，請將下列重新導向網址新增至 OIDC IdP：

   https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
   

   更改下列內容：

   • WORKFORCE_POOL_ID：工作團隊身分集區 ID

   • WORKFORCE_PROVIDER_ID：您稍後在本文件中建立的員工身分集區提供者 ID。

   如要瞭解如何設定控制台 (聯盟) 登入，請參閱「設定控制台 (聯盟) 的使用者存取權」。

3. 在 Google Cloud中，如要建立提供者，請執行下列步驟：

   gcloud

   代碼流程

   如要建立使用授權碼流程的 OIDC 提供者，以進行網頁登入，請執行下列指令：

   gcloud iam workforce-pools providers create-oidc WORKFORCE_PROVIDER_ID \
       --workforce-pool=WORKFORCE_POOL_ID \
       --display-name="DISPLAY_NAME" \
       --description="DESCRIPTION" \
       --issuer-uri="ISSUER_URI" \
       --client-id="OIDC_CLIENT_ID" \
       --client-secret-value="OIDC_CLIENT_SECRET" \
       --web-sso-response-type="code" \
       --web-sso-assertion-claims-behavior="merge-user-info-over-id-token-claims" \
       --web-sso-additional-scopes="WEB_SSO_ADDITIONAL_SCOPES" \
       --attribute-mapping="ATTRIBUTE_MAPPING" \
       --attribute-condition="ATTRIBUTE_CONDITION" \
       --jwk-json-path="JWK_JSON_PATH" \
       --detailed-audit-logging \
       --location=global
   

   取代下列項目：

   • WORKFORCE_PROVIDER_ID：工作團隊身分集區供應商的專屬 ID。前置字串「gcp-」為預留字串，不得用於工作團隊身分集區或工作團隊身分集區提供者 ID。
   • WORKFORCE_POOL_ID：要連結 IdP 的工作團隊身分集區 ID。
   • DISPLAY_NAME：供應商的選用簡單顯示名稱，例如 idp-eu-employees。
   • DESCRIPTION：工作團隊提供者說明 (選填)，例如 IdP for Partner Example Organization employees。
   • ISSUER_URI：OIDC 核發者 URI，格式必須為有效的 URI，且開頭為 https，例如 https://example.com/oidc。注意：基於安全考量，ISSUER_URI 必須使用 HTTPS 通訊協定。
   • OIDC_CLIENT_ID：向 OIDC IdP 註冊的 OIDC 用戶端 ID；這個 ID 必須與 IdP 發行的 JWT 的 aud 聲明相符。
   • OIDC_CLIENT_SECRET：OIDC 用戶端密碼。
   • WEB_SSO_ADDITIONAL_SCOPES：要傳送至 OIDC IdP 的選用額外範圍，適用於主控台 (已連結) 或 gcloud CLI 瀏覽器型登入。
   • ATTRIBUTE_MAPPING：屬性對應。 以下是屬性對應的範例：

     google.subject=assertion.sub,
     google.groups=assertion.group1,
     attribute.costcenter=assertion.costcenter

     這個範例會將 OIDC 聲明中的 IdP 屬性 subject、group1 和 costcenter 分別對應至 google.subject、google.groups 和 attribute.costcenter 屬性。
   • ATTRIBUTE_CONDITION：屬性條件，例如 assertion.role == 'gcp-users'。這個範例條件可確保只有具備 gcp-users 角色的使用者，才能使用這個供應商登入。
   • JWK_JSON_PATH：本機上傳的 OIDC JWK 的選用路徑。 如果未提供這個參數， Google Cloud 會改用 IdP 的 /.well-known/openid-configuration 路徑，取得含有公開金鑰的 JWK。如要進一步瞭解本機上傳的 OIDC JWK，請參閱管理 OIDC JWK。

   • 員工身分聯盟詳細稽核記錄會將從 IdP 收到的資訊記錄到 Logging。詳細稽核記錄有助於排解工作團隊身分識別集區提供者設定問題。如要瞭解如何透過詳細的稽核記錄排解屬性對應錯誤，請參閱「一般屬性對應錯誤」。如要瞭解 Logging 定價，請參閱 Google Cloud Observability 定價。

     如要為工作團隊身分集區提供者停用詳細稽核記錄，請在執行 gcloud iam workforce-pools providers create 時省略 --detailed-audit-logging 旗標。如要停用詳細稽核記錄，您也可以更新供應商。

   在指令回應中，POOL_RESOURCE_NAME 是集區的名稱，例如 locations/global/workforcePools/enterprise-example-organization-employees。

   隱含流程

   如要建立使用隱含流程的 OIDC 提供者，以供網頁登入，請執行下列指令：

   gcloud iam workforce-pools providers create-oidc WORKFORCE_PROVIDER_ID \
       --workforce-pool=WORKFORCE_POOL_ID \
       --display-name="DISPLAY_NAME" \
       --description="DESCRIPTION" \
       --issuer-uri="ISSUER_URI" \
       --client-id="OIDC_CLIENT_ID" \
       --web-sso-response-type="id-token" \
       --web-sso-assertion-claims-behavior="only-id-token-claims" \
       --web-sso-additional-scopes="WEB_SSO_ADDITIONAL_SCOPES" \
       --attribute-mapping="ATTRIBUTE_MAPPING" \
       --attribute-condition="ATTRIBUTE_CONDITION" \
       --jwk-json-path="JWK_JSON_PATH" \
       --detailed-audit-logging \
       --location=global
   

   取代下列項目：

   • WORKFORCE_PROVIDER_ID：工作團隊身分集區供應商的專屬 ID。前置字串「gcp-」為預留字串，不得用於工作團隊身分集區或工作團隊身分集區提供者 ID。
   • WORKFORCE_POOL_ID：要連結 IdP 的工作團隊身分集區 ID。
   • DISPLAY_NAME：供應商的選用簡單顯示名稱，例如 idp-eu-employees。
   • DESCRIPTION：工作團隊提供者說明 (選填)，例如 IdP for Partner Example Organization employees。
   • ISSUER_URI：OIDC 核發者 URI，格式必須為有效的 URI，且開頭為 https，例如 https://example.com/oidc。注意：基於安全考量，ISSUER_URI 必須使用 HTTPS 通訊協定。
   • OIDC_CLIENT_ID：向 OIDC IdP 註冊的 OIDC 用戶端 ID；這個 ID 必須與 IdP 發行的 JWT 的 aud 聲明相符。
   • WEB_SSO_ADDITIONAL_SCOPES：要傳送至 OIDC IdP 的選用額外範圍，適用於主控台 (已連結) 或 gcloud CLI 瀏覽器型登入。
   • ATTRIBUTE_MAPPING：屬性對應。 以下是屬性對應的範例：

     google.subject=assertion.sub,
     google.groups=assertion.group1,
     attribute.costcenter=assertion.costcenter

     這個範例會將 OIDC 聲明中的 IdP 屬性 subject、group1 和 costcenter 分別對應至 google.subject、google.groups 和 attribute.costcenter 屬性。
   • ATTRIBUTE_CONDITION：屬性條件，例如 assertion.role == 'gcp-users'。這個範例條件可確保只有具備 gcp-users 角色的使用者，才能使用這個供應商登入。
   • JWK_JSON_PATH：本機上傳的 OIDC JWK 的選用路徑。 如果未提供這個參數， Google Cloud 會改用 IdP 的 /.well-known/openid-configuration 路徑，取得含有公開金鑰的 JWK。如要進一步瞭解本機上傳的 OIDC JWK，請參閱管理 OIDC JWK。

   • 員工身分聯盟詳細稽核記錄會將從 IdP 收到的資訊記錄到 Logging。詳細稽核記錄有助於排解工作團隊身分識別集區提供者設定問題。如要瞭解如何透過詳細的稽核記錄排解屬性對應錯誤，請參閱「一般屬性對應錯誤」。如要瞭解 Logging 定價，請參閱 Google Cloud Observability 定價。

     如要為工作團隊身分集區提供者停用詳細稽核記錄，請在執行 gcloud iam workforce-pools providers create 時省略 --detailed-audit-logging 旗標。如要停用詳細稽核記錄，您也可以更新供應商。

   在指令回應中，POOL_RESOURCE_NAME 是集區的名稱，例如 locations/global/workforcePools/enterprise-example-organization-employees。

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

   如果是 OIDC 聯盟，您可以使用 assertion.NAME：這個字串等同於 ID 權杖酬載中同名聲明的價值。

   控制台

   代碼流程

   在 Google Cloud 控制台中，如要建立使用授權碼流程的 OIDC 提供者，請按照下列步驟操作：

   1. 前往 Google Cloud 控制台的「Workforce Identity Pools」頁面：

      前往工作團隊身分集區

   2. 在「工作團隊身分集區」表格中，選取要建立提供者的集區。

   3. 在「供應商」表格中，按一下「新增供應商」。

   4. 在「選取通訊協定」中，選取「Open ID Connect (OIDC)」。

   5. 在「建立集區提供者」中，執行下列操作：

      1. 在「名稱」中輸入供應商名稱。
      2. 在「核發者 (網址)」中，輸入核發者 URI。OIDC 核發者 URI 必須採用有效的 URI 格式，且開頭為 https，例如 https://example.com/oidc。
      3. 輸入「用戶端 ID」，也就是向 OIDC IdP 註冊的 OIDC 用戶端 ID；這個 ID 必須與 IdP 發行的 JWT 的 aud 聲明相符。
      4. 如要建立已啟用的供應商，請確認「已啟用供應商」已開啟。
      5. 按一下「繼續」。

   6. 在「流程類型」中，執行下列操作。流程類型僅適用於網頁式單一登入流程。

      1. 在「流程類型」中，選取「程式碼」。
      2. 在「用戶端密鑰」中，輸入 IdP 的用戶端密鑰。

      3. 在「聲明主張行為」中，選取下列任一選項：

         • 使用者資訊和 ID 權杖
         • 僅限 ID 權杖

      4. 按一下「繼續」。

   7. 在「設定供應商」中，您可以設定屬性對應和屬性條件。如要建立屬性對應，請按照下列步驟操作。您可以提供 IdP 欄位名稱，也可以提供傳回字串的 CEL 格式運算式。

      1. 必要：在「OIDC 1」中，輸入 IdP 的主體，例如 assertion.sub。

      2. 選用：如要新增其他屬性對應，請按照下列步驟操作：

         1. 按一下 [新增對應]。
         2. 在「Google n」中 (其中 n 是數字)，輸入其中一個Google Cloud支援的按鍵。
         3. 在對應的 OIDC n 欄位中，以 CEL 格式輸入要對應的 IdP 特定欄位名稱。

      3. 如要建立屬性條件，請按照下列步驟操作：

         1. 按一下「新增條件」。
         2. 在「屬性條件」中，以 CEL 格式輸入條件，例如 assertion.role == 'gcp-users'。這個條件範例可確保只有具備 gcp-users 角色的使用者，才能使用這個供應商登入。

      4. 如要啟用詳細稽核記錄，請在「詳細記錄」中，點按「啟用詳細屬性值記錄」切換鈕。

         員工身分聯盟詳細稽核記錄會將從 IdP 收到的資訊記錄到 Logging。詳細稽核記錄有助於排解工作團隊身分識別集區提供者設定問題。如要瞭解如何透過詳細的稽核記錄排解屬性對應錯誤，請參閱「一般屬性對應錯誤」。如要瞭解 Logging 定價，請參閱 Google Cloud Observability 定價。

         如要為工作團隊身分集區提供者停用詳細稽核記錄，請在執行 gcloud iam workforce-pools providers create 時省略 --detailed-audit-logging 旗標。如要停用詳細稽核記錄，您也可以更新供應商。

   8. 如要建立提供者，請按一下「提交」。

   隱含流程

   在 Google Cloud 控制台中，如要建立使用隱含流程的 OIDC 供應商，請執行下列操作：

   1. 前往 Google Cloud 控制台的「Workforce Identity Pools」頁面：

      前往工作團隊身分集區

   2. 在「工作團隊身分集區」表格中，選取要建立提供者的集區。

   3. 在「供應商」表格中，按一下「新增供應商」。

   4. 在「選取通訊協定」中，選取「Open ID Connect (OIDC)」。

   5. 在「建立集區提供者」中，執行下列操作：

      1. 在「名稱」部分，輸入供應商名稱。
      2. 在「核發者 (網址)」中，輸入核發者 URI。OIDC 核發者 URI 必須採用有效的 URI 格式，且開頭為 https，例如 https://example.com/oidc。
      3. 輸入「用戶端 ID」，也就是向 OIDC IdP 註冊的 OIDC 用戶端 ID；這個 ID 必須與 IdP 發行的 JWT 的 aud 聲明相符。
      4. 如要建立已啟用的供應商，請確認「已啟用供應商」已開啟。
      5. 按一下「繼續」。

   6. 在「流程類型」中，執行下列操作。流程類型僅適用於網頁式單一登入流程。

      1. 在「流程類型」中，選取「ID 權杖」。
      2. 按一下「繼續」。

   7. 在「設定供應商」中，您可以設定屬性對應和屬性條件。如要建立屬性對應，請按照下列步驟操作。您可以提供 IdP 欄位名稱，也可以提供傳回字串的 CEL 格式運算式。

      1. 必要：在「OIDC 1」中，輸入 IdP 的主體，例如 assertion.sub。

      2. 選用：如要新增其他屬性對應，請按照下列步驟操作：

         1. 按一下 [新增對應]。
         2. 在「Google n」中 (其中 n 是數字)，輸入其中一個Google Cloud支援的按鍵。
         3. 在對應的 OIDC n 欄位中，以 CEL 格式輸入要對應的 IdP 特定欄位名稱。

      3. 如要建立屬性條件，請按照下列步驟操作：

         1. 按一下「新增條件」。

         2. 在「屬性條件」中，以 CEL 格式輸入條件，例如 assertion.role == 'gcp-users'。這個條件範例可確保只有具備 gcp-users 角色的使用者，才能使用這個供應商登入。

      4. 如要啟用詳細稽核記錄，請在「詳細記錄」中，點按「啟用詳細屬性值記錄」切換鈕。

         員工身分聯盟詳細稽核記錄會將從 IdP 收到的資訊記錄到 Logging。詳細稽核記錄有助於排解工作團隊身分識別集區提供者設定問題。如要瞭解如何透過詳細的稽核記錄排解屬性對應錯誤，請參閱「一般屬性對應錯誤」。如要瞭解 Logging 定價，請參閱 Google Cloud Observability 定價。

         如要為工作團隊身分集區提供者停用詳細稽核記錄，請在執行 gcloud iam workforce-pools providers create 時省略 --detailed-audit-logging 旗標。如要停用詳細稽核記錄，您也可以更新供應商。

   8. 如要建立提供者，請按一下「提交」。

建立 SAML 工作團隊集區提供者

1. 在 SAML IdP 中，為 Google Cloud員工身分聯盟註冊新應用程式。

2. 設定 SAML 宣告的目標對象。 通常是 IdP 設定中的 SP Entity ID 欄位。請務必將其設為下列網址：

   https://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
   

3. 設定重新導向網址，又稱為宣告客戶服務 (ACS) 網址。如要設定重新導向網址，請在 SAML IdP 中找到重新導向網址欄位，然後執行下列任一操作：

   • 如要透過 Google Cloud 主控台或其他瀏覽器登入方法設定瀏覽器登入，請輸入下列網址：

     https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
     

     更改下列內容：

     • WORKFORCE_POOL_ID：工作團隊身分集區 ID

     • WORKFORCE_PROVIDER_ID：您稍後在本文件中建立的員工身分集區提供者 ID。

   • 如要透過 IdP 設定程式輔助登入，請輸入下列網址：

     localhost
     

   如要進一步瞭解如何設定控制台登入，請參閱「設定使用者控制台存取權」。

4. 在 Google Cloud中，使用 IdP 的 SAML 中繼資料文件建立 SAML 工作團隊身分識別集區供應商。您可以從 IdP 下載 SAML 中繼資料 XML 文件。文件至少須包含下列資訊：

   • IdP 的 SAML 實體 ID。
   • IdP 的單一登入網址。
   • 至少一個簽署公開金鑰。如要瞭解簽署金鑰的詳細規定，請參閱本指南稍後的「金鑰規定」。

  gcloud iam workforce-pools providers create-saml WORKFORCE_PROVIDER_ID \
      --workforce-pool=WORKFORCE_POOL_ID \
      --display-name="DISPLAY_NAME" \
      --description="DESCRIPTION" \
      --idp-metadata-path=METADATA_FILE_PATH \
      --attribute-mapping="ATTRIBUTE_MAPPING" \
      --attribute-condition="ATTRIBUTE_CONDITION" \
      --location=global

gcloud iam workforce-pools providers keys create KEY_ID \
    --workforce-pool WORKFORCE_POOL_ID \
    --provider WORKFORCE_PROVIDER_ID \
    --location global \
    --use encryption \
    --spec KEY_SPECIFICATION

gcloud iam workforce-pools providers keys describe KEY_ID \
    --workforce-pool WORKFORCE_POOL_ID \
    --provider WORKFORCE_PROVIDER_ID \
    --location global \
    --format "value(keyData.key)" \
    > CERTIFICATE_PATH

  gcloud iam workforce-pools providers keys delete KEY_ID \
      --workforce-pool WORKFORCE_POOL_ID \
      --provider WORKFORCE_PROVIDER_ID \
      --location global

在 IAM 政策中代表工作團隊集區使用者

下表列出您用來將角色授予單一使用者、使用者群組、具有特定聲明的使用者，或工作人員集區中所有使用者的主體 ID。

如需完整的主體 ID 清單，請參閱「主體 ID」。

將 IAM 角色授予主體

您可以將角色授予主體，例如單一身分、身分群組或整個集區。

如要將專案的角色授予主體，請執行下列指令：

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role="ROLE" \
    --member="PRINCIPAL"

更改下列內容：

• PROJECT_ID：專案 ID
• ROLE：要設定的角色
• PRINCIPAL：主體；請參閱員工身分聯盟的主體 ID。

在下列範例中，指令會將 Storage Admin (roles/storage.admin) 授予群組 GROUP_ID 中的所有身分：

gcloud projects add-iam-policy-binding my-project \
    --role="roles/storage.admin" \
    --member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID"

如要進一步瞭解主體格式，請參閱員工身分聯盟的主體 ID。

刪除使用者

員工身分聯盟會為聯盟使用者身分建立使用者中繼資料和資源。如果您選擇在 IdP 中刪除使用者，也必須在 Google Cloud中明確刪除這些資源。如要這麼做，請參閱「刪除 Workforce Identity Federation 使用者及其資料」。

您可能會發現資源仍與已刪除的使用者相關聯。 這是因為刪除使用者中繼資料和資源需要長時間執行的作業。啟動刪除使用者身分識別程序後，使用者在刪除前啟動的程序會繼續執行，直到完成或取消為止。

後續步驟

• 取得員工身分聯盟的短期憑證
• 管理員工身分集區提供者
• 刪除 Workforce Identity Federation 使用者及其資料
• 瞭解 Google Cloud 支援員工身分聯盟的產品
• 設定使用者對控制台 (聯合) 的存取權