使用 Microsoft Entra ID 配置员工身份联合并让用户登录

本指南介绍了如何使用 Microsoft Entra ID 配置员工身份联合并管理对 Google Cloud 的访问权限。然后，Microsoft Entra ID 身份的用户可以访问支持员工身份联合的 Google Cloud 服务。

准备工作

  1. 您必须设置一个 Google Cloud 组织。

  2. Install the Google Cloud CLI, then initialize it by running the following command: 

    gcloud init

  3. 在 Microsoft Entra ID 中，确保已为隐式流启用 ID 令牌。如需了解详情，请参阅启用隐式流。

  4. 如需登录，您的 IdP 必须提供已签名的身份验证信息：OIDC IdP 必须提供 JWT，而 SAML IdP 响应必须经过签名。

  5. 如需接收有关贵组织或 Google Cloud 产品的变更的重要信息，您必须提供必要的联系人。如需了解详情，请参阅员工身份联合概览。

所需的角色

如需获得配置员工身份联合所需的权限，请让您的管理员向您授予组织的 IAM Workforce Pool Admin (roles/iam.workforcePoolAdmin) IAM 角色。 如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

此外，IAM Owner (roles/owner) 基本角色还具有配置身份联合的权限。您不应在生产环境中授予基本角色，但可以在开发或测试环境中授予这些角色。

创建员工身份池

控制台

如需创建员工身份池，请执行以下操作：

  1. 在 Google Cloud 控制台中，转到员工身份池页面：

    转到“员工身份池”

  2. 点击创建池，然后执行以下操作：

    1. 在名称字段中，输入池的显示名称。池 ID 是根据您输入的名称自动派生的，并显示在名称字段下方。您可以点击池 ID 旁边的修改来更新池 ID。

    2. 可选：在说明中，输入池的说明。

    3. 默认情况下已设置会话时长。如需输入自定义会话时长，请点击修改。会话时长，用于确定来自此员工池的 Google Cloud 访问令牌、控制台（联合）登录会话和 gcloud CLI 登录会话的有效时长。时长必须大于 15 分钟（900 秒）且小于 12 小时（43200 秒）。如果未设置会话时长，则默认为 1 小时（3600 秒）。

    4. 如需创建状态为已启用的池，请确保已启用池处于开启状态。

    5. 如需创建员工身份池，请点击下一步。

gcloud

如需创建员工身份池，请运行以下命令：

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

替换以下内容：

  • WORKFORCE_POOL_ID：您选择用于表示 Google Cloud 员工池的 ID。如需了解如何设置 ID 的格式，请参阅 API 文档中的查询参数部分。
  • ORGANIZATION_ID：您的 Google Cloud 组织的数字 ID。
  • DISPLAY_NAME：可选。您的员工身份池的显示名称。
  • DESCRIPTION：可选。员工身份池说明。
  • SESSION_DURATION：可选。会话时长，用于确定来自此员工池的 Google Cloud 访问令牌、控制台（联合）登录会话和 gcloud CLI 登录会话的有效时长。时长必须大于 15 分钟（900 秒）且小于 12 小时（43200 秒）。如果未设置会话时长，则默认为 1 小时（3600 秒）。

创建 Microsoft Entra ID 应用

本部分介绍了使用 Microsoft Entra 管理员门户创建 Microsoft Entra ID 应用的步骤。如需了解更多详情，请参阅什么是身份验证。

员工身份池支持使用 OIDC 和 SAML 协议进行联合。

OIDC

如需创建使用 OIDC 协议的 Microsoft 应用注册，请执行以下步骤：

  1. 登录 Microsoft Entra 管理员门户。
  2. 依次前往身份 > 应用 > 应用注册。

  3. 如需开始配置应用注册，请执行以下操作：

    1. 点击 New registration（新注册）。
    2. 输入应用的名称。
    3. 在 Supported account types（支持的账号类型）中，选择一个选项。

    4. 在 Redirect URI（重定向 URI）部分的 Select a platform（选择平台）下拉列表中，选择 Web。在文本字段中输入重定向网址。用户成功登录后，系统会将用户重定向到此网址。如果您要配置对控制台（联合）的访问权限，请使用以下网址格式：

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

      替换以下内容：

      • WORKFORCE_POOL_ID：您在本指南前面部分创建的员工池的 ID。
      • WORKFORCE_PROVIDER_ID：您选择的员工身份提供方 ID，例如：azure-ad-oidc-provider。如需了解如何设置 ID 的格式，请参阅 API 文档中的查询参数部分。

    5. 如需创建应用注册，请点击 Register（注册）。

  4. 可选：如需配置群组声明，请执行以下操作：

    1. 前往 Microsoft Entra ID 应用注册。
    2. 点击令牌配置。
    3. 点击添加群组声明。如需使用本指南后面提供的示例属性映射，您必须创建自定义 department 属性。
    4. 选择要返回的群组类型。如需了解详情，请参阅配置群组可选声明。

SAML

如需创建使用 SAML 协议的 Microsoft 应用，请执行以下步骤：

  1. 登录 Microsoft Azure 门户。
  2. 依次前往 Azure Active Directory > Enterprise applications（Azure Active Directory > 企业应用）。

  3. 如需开始配置企业应用，请执行以下操作：

    1. 点击 New application > Create your own application（新建应用 > 创建您自己的应用）。
    2. 输入应用的名称。
    3. 点击创建。
    4. 依次前往 Single sign-on > SAML（单点登录 > SAML）。

    5. 按照如下所示更新 Basic SAML Configuration（基本 SAML 配置）。

      1. 在 Identifier (Entity ID)（标识符 [实体 ID]）字段中，输入以下值：

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

      2. 在 Reply URL (Assertion Consumer Service URL)（回复网址 [断言消费者服务网址]）字段中，输入重定向网址。用户成功登录后，系统会将用户重定向到此网址。如果您要配置对控制台（联合）的访问权限，请使用以下网址格式：

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

        替换以下内容：

        • WORKFORCE_POOL_ID：您在本指南前面部分创建的员工身份池的 ID。
        • WORKFORCE_PROVIDER_ID：您选择的员工身份提供方 ID：例如：azure-ad-oidc-provider。如需了解如何设置 ID 的格式，请参阅 API 文档中的查询参数部分。

      3. 如果您要启用 IdP 发起的登录，请将 Relay State（中继状态）字段设置为以下值：

        https://console.cloud.google/

      4. 如需保存 SAML 应用配置，请点击 Save（保存）。

  4. 如需配置群组声明，请执行以下操作。如需使用本指南后面提供的示例属性映射，您必须创建自定义 department 属性。

    1. 前往 Microsoft Entra ID 应用。
    2. 点击 Single sign-on（单点登录）。
    3. 在 Attributes & Claims（属性和声明）部分中，点击 Edit（修改）。
    4. 点击添加群组声明。
    5. 选择要返回的群组类型。如需了解详情，请参阅使用单点登录配置向 SAML 应用的令牌添加群组声明。

创建 Microsoft Entra ID 员工身份池提供方

本部分介绍如何创建员工身份池提供方，以便您的 IdP 用户能够访问 Google Cloud。您可以将提供方配置为使用 OIDC 或 SAML 协议。

创建 OIDC 员工池提供方

如需使用 OIDC 协议为 Microsoft Entra ID 应用集成创建员工身份池提供方，请执行以下操作：

  1. 如需获取 Microsoft Entra ID 应用的颁发者 URI，请执行以下操作：

    1. 前往 Microsoft Entra ID 应用注册。
    2. 点击端点。
    3. 在新标签页中打开 OpenID Connect metadata document（OpenID Connect 元数据文档）。
    4. 在 JSON 中，复制 issuer 的值。

  2. 如需获取 Microsoft Entra ID 应用的客户端 ID，请执行以下操作：

    1. 前往 Microsoft Entra ID 应用注册。
    2. 在应用 [客户端] ID 中，复制该值。

  3. 如需创建 OIDC 员工身份池提供方以基于网络进行登录，请执行以下操作：

    控制台

    代码流

    如需创建使用授权代码流程基于网络进行登录的 OIDC 提供方，请执行以下操作：

    1. 如需获取 Microsoft Entra ID 客户端密钥，请执行以下操作：

      1. 前往 Microsoft Entra ID 应用注册。

      2. 在证书和密钥中，点击客户端密钥标签页。

      3. 如需添加客户端密钥，请点击 + 新建客户端密钥。

      4. 在添加客户端密钥对话框中，根据需要输入信息。

      5. 如需创建客户端密钥，请点击添加。

      6. 在客户端密钥标签页中，找到新的客户端密钥。

      7. 在新客户端密钥的值列中，点击复制。

    2. 在 Google Cloud 控制台中，如需创建使用授权代码流程的 OIDC 提供方，请执行以下操作：

      1. 在 Google Cloud 控制台中，转到员工身份池页面：

        进入“员工身份池”

      2. 在员工身份池表中，选择要为其创建提供方的池。

      3. 在提供方表中，点击添加提供方。

      4. 在选择协议中，选择 OpenID 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。

          对于使用 OIDC 身份验证的 Microsoft Entra ID，我们建议使用以下属性映射：

          google.subject=assertion.sub,
google.groups=assertion.groups,
google.display_name=assertion.preferred_username

          此示例将 IdP 属性 subject、groups 和 preferred_username 分别映射到 Google Cloud 属性 google.subject、google.groups 和 google.display_name。

        2. 可选：如需添加其他属性映射，请执行以下操作：

          1. 点击添加映射。
          2. 在 Google n（其中 n 为数字）中，输入一个 Google Cloud 支持的密钥。
          3. 在相应的 OIDC n 字段中，以 CEL 格式输入要映射的 IdP 特定字段的名称。

        3. 如需创建属性条件，请执行以下操作：

          1. 点击添加条件。
          2. 在属性条件中，输入 CEL 格式的条件；例如，要将 ipaddr 属性限制为特定的 IP 范围，您可以设置条件 assertion.ipaddr.startsWith('98.11.12.')。

      8. 如需创建提供方，请点击提交。

    隐式流

    如需创建使用隐式流基于网络进行登录的 OIDC 提供方，请执行以下操作：

    1. 在 Google Cloud 控制台中，转到员工身份池页面：

      进入“员工身份池”

    2. 在员工身份池表中，选择要为其创建提供方的池。

    3. 在提供方表中，点击添加提供方。

    4. 在选择协议中，选择 OpenID 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。

        对于使用 OIDC 身份验证的 Microsoft Entra ID，我们建议使用以下属性映射：

        google.subject=assertion.sub,
google.groups=assertion.groups,
google.display_name=assertion.preferred_username

        此示例将 IdP 属性 subject、groups 和 preferred_username 分别映射到 Google Cloud 属性 google.subject、google.groups 和 google.display_name。

      2. 可选：如需添加其他属性映射，请执行以下操作：

        1. 点击添加映射。
        2. 在 Google n（其中 n 为数字）中，输入一个 Google Cloud 支持的密钥。
        3. 在相应的 OIDC n 字段中，以 CEL 格式输入要映射的 IdP 特定字段的名称。

      3. 如需创建属性条件，请执行以下操作：

        1. 点击添加条件。

        2. 在属性条件中，输入 CEL 格式的条件；例如，要将 ipaddr 属性限制为特定的 IP 范围，您可以设置条件 assertion.ipaddr.startsWith('98.11.12.')。

    8. 如需创建提供方，请点击提交。

    gcloud

    如需创建支持 OIDC 协议的提供方，请执行以下操作：

    代码流

    如需创建使用授权代码流程基于网络进行登录的 OIDC 提供方，请执行以下操作：

    1. 在 Microsoft Entra ID 应用中，如需获取客户端密钥，请执行以下操作：

      1. 前往 Microsoft Entra ID 应用注册。

      2. 在证书和密钥中，点击客户端密钥标签页。

      3. 如需添加客户端密钥，请点击 + 新建客户端密钥。

      4. 在添加客户端密钥对话框中，根据需要输入信息。

      5. 如需创建客户端密钥，请点击添加。

      6. 在客户端密钥标签页中，找到新的客户端密钥。

      7. 在新客户端密钥的值列中，点击复制。

    2. 在 Google Cloud 控制台中，如需创建使用代码流的 OIDC 提供方，请执行以下操作：

      gcloud iam workforce-pools providers create-oidc 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" \
    --location=global

      请替换以下内容：

      • 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：属性映射。 对于使用 OIDC 身份验证的 Microsoft Entra ID，我们建议使用以下属性映射：

        google.subject=assertion.sub,
google.groups=assertion.groups,
google.display_name=assertion.preferred_username

        此示例将 IdP 属性 subject、groups 和 preferred_username 分别映射到 Google Cloud 属性 google.subject、google.groups 和 google.display_name。

      • ATTRIBUTE_CONDITION：属性条件；例如，如需将 ipaddr 属性限制为特定 IP 范围，您可以设置条件 assertion.ipaddr.startsWith('98.11.12.')。
      • JWK_JSON_PATH：本地上传的 OIDC JWK 的可选路径。如果未提供此参数，Google Cloud 会改用您的 IdP 的 /.well-known/openid-configuration 路径来寻找包含公钥的 JWK。如需详细了解本地上传的 OIDC JWK，请参阅管理 OIDC JWK。
      在命令响应中，POOL_RESOURCE_NAME 是池的名称；例如 locations/global/workforcePools/enterprise-example-organization-employees。

    隐式流

    如需创建使用隐式流进行 Web 登录的 OIDC 提供方，请执行以下操作：

    1. 如需在 Microsoft Entra ID 应用中启用 ID 令牌，请执行以下操作：

      1. 前往 Microsoft Entra ID 应用注册。
      2. 在身份验证中，选中 ID 令牌复选框。
      3. 点击保存。

    2. 如需创建提供方，请运行以下命令：

      gcloud iam workforce-pools providers create-oidc 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" \
    --location=global

      请替换以下内容：

      • 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：属性映射。 对于使用 OIDC 身份验证的 Microsoft Entra ID，我们建议使用以下属性映射：

        google.subject=assertion.sub,
google.groups=assertion.groups,
google.display_name=assertion.preferred_username

        此示例将 IdP 属性 subject、groups 和 preferred_username 分别映射到 Google Cloud 属性 google.subject、google.groups 和 google.display_name。

      • ATTRIBUTE_CONDITION：属性条件；例如，如需将 ipaddr 属性限制为特定 IP 范围，您可以设置条件 assertion.ipaddr.startsWith('98.11.12.')。
      • JWK_JSON_PATH：本地上传的 OIDC JWK 的可选路径。如果未提供此参数，Google Cloud 会改用您的 IdP 的 /.well-known/openid-configuration 路径来寻找包含公钥的 JWK。如需详细了解本地上传的 OIDC JWK，请参阅管理 OIDC JWK。
      在命令响应中，POOL_RESOURCE_NAME 是池的名称；例如 locations/global/workforcePools/enterprise-example-organization-employees。

创建 SAML 员工池提供方

  1. 在您的 SAML IdP 中，为 Google Cloud 员工身份联合注册一个新应用。

  2. 设置 SAML 断言的目标对象。它通常是 IdP 配置中的 SP Entity ID 字段。您必须将其设置为以下网址：

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

  3. 如果您打算设置对控制台的用户访问权限，请在 SAML IdP 中将重定向网址或断言消费者服务 (ACS) 网址字段设置为以下网址：

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

    如需详细了解如何配置控制台登录，请参阅设置用户对控制台的访问权限。

  4. 在 Google Cloud 中，使用 IdP 的 SAML 元数据文档创建 SAML 员工身份池提供方。您可以从 IdP 下载 SAML 元数据 XML 文档。该文档必须至少包含以下内容：

    • 您的 IdP 的 SAML 实体 ID。
    • 您的 IdP 的单点登录网址。
    • 至少一个签名公钥。 如需详细了解签名密钥，请参阅本指南后面部分的密钥要求。

控制台

如需使用 Google Cloud 控制台配置 SAML 提供方，请执行以下操作：

  1. 在 Google Cloud 控制台中，转到员工身份池页面：

    转到“员工身份池”

  2. 在员工身份池表中，选择要为其创建提供方的池。

  3. 在提供方表中，点击添加提供方。

  4. 在选择协议中，选择 SAML。

  5. 在创建池提供方中，执行以下操作：

    1. 在名称中，输入提供方的名称。

    2. 可选：在说明中，输入提供方的说明。

    3. 在 IDP 元数据文件 (XML) 中，选择您在本指南前面部分生成的元数据 XML 文件。

    4. 确保已启用提供方处于启用状态。

    5. 点击继续。

  6. 在配置提供方中，执行以下操作：

    1. 在属性映射中，输入 google.subject 的 CEL 表达式。

    2. 可选：如需输入其他映射，请点击添加映射，然后输入其他映射，例如：

      google.subject=assertion.subject,
google.groups=assertion.attributes['https://example.com/aliases'],
attribute.costcenter=assertion.attributes.costcenter[0]
       此示例将 IdP 属性 assertion.subject、assertion.attributes['https://example.com/aliases'] 和 assertion.attributes.costcenter[0] 分别映射到 Google Cloud 属性 google.subject、google.groups 和 google.costcenter。

    3. 可选：如需添加属性条件，请点击添加条件，然后输入表示属性条件的 CEL 表达式。 例如，要将 ipaddr 属性限制为特定 IP 范围，您可以设置条件 assertion.attributes.ipaddr.startsWith('98.11.12.')。此示例条件可确保只有 IP 地址以 98.11.12. 开头的用户才能使用此员工提供方登录。

    4. 点击继续。

  7. 如需创建提供方，请点击提交。

gcloud

如需保存 Microsoft Entra ID 应用的 SAML 元数据，请执行以下操作：

  1. 前往 Microsoft Entra ID 应用。
  2. 点击 Single sign-on（单点登录）。
  3. 在 SAML Certificates（SAML 证书）部分中，下载 Federation Metadata XML（联合元数据 XML）。
  4. 将元数据保存为本地 XML 文件。

如需创建 SAML 员工身份池提供方，请运行以下命令：

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

替换以下内容：

  • PROVIDER_ID：提供方 ID。
  • WORKFORCE_POOL_ID：员工身份池 ID。
  • DISPLAY_NAME：显示名称。
  • DESCRIPTION：说明。
  • XML_METADATA_PATH：XML 格式的元数据文件的路径，该文件包含 SAML 身份提供方的配置元数据。

  • ATTRIBUTE_MAPPING：属性映射，例如：

    google.subject=assertion.subject,
google.groups=assertion.attributes['https://example.com/aliases'],
attribute.costcenter=assertion.attributes.costcenter[0]
     此示例将 IdP 属性 assertion.subject、assertion.attributes['https://example.com/aliases'] 和 assertion.attributes.costcenter[0] 分别映射到 Google Cloud 属性 google.subject、google.groups 和 google.costcenter。

  • ATTRIBUTE_CONDITION：可选的属性条件。例如，要将 ipaddr 属性限制为特定 IP 范围，您可以设置条件 assertion.attributes.ipaddr.startsWith('98.11.12.')。此示例条件可确保只有 IP 地址以 98.11.12. 开头的用户才能使用此员工提供方登录。

可选：接受来自 IdP 的加密 SAML 断言

如需让您的 SAML 2.0 IdP 能够生成员工身份联合可接受的加密 SAML 断言，请执行以下操作：

  • 在员工身份联合中，执行以下操作：
    • 为您的员工身份池提供方创建非对称密钥对。
    • 下载包含公钥的证书文件。
    • 配置您的 SAML IdP，以使用公钥加密颁发的 SAML 断言。
  • 在 IdP 中，执行以下操作：
    • 启用断言加密（也称为令牌加密）。
    • 上传您在员工身份联合中创建的公钥。
    • 确认您的 IdP 生成加密的 SAML 断言。
请注意，即使配置了 SAML 加密提供方密钥，员工身份联合仍然可以处理明文断言。

创建员工身份联合 SAML 断言加密密钥

本部分将指导您创建非对称密钥对，使员工身份联合能够接受加密的 SAML 断言。

Google Cloud 使用私钥来解密 IdP 发出的 SAML 断言。如需创建用于 SAML 加密的非对称密钥对，请运行以下命令。如需了解详情，请参阅支持的 SAML 加密算法。

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

请替换以下内容：

  • KEY_ID：您选择的键名称
  • WORKFORCE_POOL_ID：池 ID
  • PROVIDER_ID：提供方 ID
  • KEY_SPECIFICATION：密钥规范，可以是 rsa-2048、rsa-3072 和 rsa-4096 之一。

创建密钥对后，如需将公钥下载到证书文件中，请执行以下命令。只有员工身份联合可以访问私钥。 

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

替换以下内容：

  • KEY_ID：密钥名称
  • WORKFORCE_POOL_ID：池 ID
  • PROVIDER_ID：提供方 ID
  • CERTIFICATE_PATH：要将证书写入的路径，例如 saml-certificate.cer 或 saml-certificate.pem

配置符合 SAML 2.0 标准的 IdP，以发出加密的 SAML 断言

如需将 Microsoft Entra ID 配置为加密 SAML 令牌，请参阅配置 Azure Active Directory SAML 令牌加密。

将 IdP 配置为加密 SAML 断言后，我们建议您检查以确保其生成的断言确实已加密。即使配置了 SAML 断言加密，员工身份联合仍然可以处理明文断言。

删除员工身份联合加密密钥

如需删除 SAML 加密密钥，请运行以下命令：
  gcloud iam workforce-pools providers keys delete KEY_ID \
      --workforce-pool WORKFORCE_POOL_ID \
      --provider PROVIDER_ID \
      --location global

请替换以下内容：

  • KEY_ID：密钥名称
  • WORKFORCE_POOL_ID：池 ID
  • PROVIDER_ID：提供方 ID

支持的 SAML 加密算法

员工身份联合支持以下密钥传输算法：

员工身份联合支持以下块加密算法：

管理对 Google Cloud 资源的访问权限

本部分提供的示例展示了如何管理员工身份联合用户对 Google Cloud 资源的访问权限。

在此示例中，您需要授予对示例项目的 Identity and Access Management (IAM) 角色。然后，用户可以登录并使用此项目访问 Google Cloud 产品。

您可以管理单个身份、一组身份或整个池的 IAM 角色。如需了解详情，请参阅在 IAM 政策中表示员工身份池用户。

对于单个身份

如需向单个身份授予项目 TEST_PROJECT_ID 的 Storage Admin (roles/storage.admin) 角色，请运行以下命令：

gcloud projects add-iam-policy-binding TEST_PROJECT_ID \
    --role="roles/storage.admin" \
    --member="principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_VALUE"

替换以下内容：

  • TEST_PROJECT_ID：项目的 ID
  • WORKFORCE_POOL_ID：员工身份池 ID
  • SUBJECT_VALUE：用户身份

使用映射的部门特性

如需向项目 TEST_PROJECT_ID 的特定部门中的所有身份授予 Storage Admin (roles/storage.admin) 角色，请运行以下命令：

gcloud projects add-iam-policy-binding TEST_PROJECT_ID \
    --role="roles/storage.admin" \
    --member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/attribute.department/DEPARTMENT_VALUE"

替换以下内容：

  • TEST_PROJECT_ID：项目的 ID
  • WORKFORCE_POOL_ID：员工身份池 ID
  • DEPARTMENT_VALUE：映射的 attribute.department 值

使用映射群组

如需向项目 TEST_PROJECT_ID 的群组 GROUP_ID 中的所有身份授予 Storage Admin (roles/storage.admin) 角色，请运行以下命令：

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

替换以下内容：

  • TEST_PROJECT_ID：项目的 ID
  • WORKFORCE_POOL_ID：员工身份池 ID
  • GROUP_ID：映射的 google.groups 声明中的群组。

登录并测试访问权限

在本部分中，您将以员工身份池用户的身份登录，并测试您是否有权访问 Google Cloud 产品。

登录

本部分介绍了如何以联合用户身份登录并访问 Google Cloud 资源。

控制台（联合）登录

如需登录 Google Cloud 员工身份联合控制台（也称为控制台 [联合]），请执行以下操作：

  1. 前往控制台（联合）登录页面。

    前往控制台（联合）

  2. 输入提供方名称，格式如下： 
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID

    1. 出现提示时，请在 Microsoft Entra ID 中输入用户凭据。

基于浏览器的 gcloud CLI 登录

如需使用基于浏览器的登录流程登录 gcloud CLI，请执行以下操作：

创建配置文件

如需创建登录配置文件，请运行以下命令。您可以选择使用 --activate 标志激活文件，以作为 gcloud CLI 的默认设置。 

gcloud iam workforce-pools create-login-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=LOGIN_CONFIG_FILE

替换以下内容：

  • WORKFORCE_POOL_ID：员工池 ID
  • PROVIDER_ID：提供方 ID
  • LOGIN_CONFIG_FILE：您指定的配置文件的路径，例如 login.json

该文件包含 gcloud CLI 用于启用基于浏览器的身份验证流程的端点，并将受众群体设置为您在本指南前面部分中创建的提供方。该文件不含机密信息。

输出类似于以下内容：

{
  "type": "external_account_authorized_user_login_config",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "auth_url": "https://auth.cloud.google/authorize",
  "token_url": "https://sts.googleapis.com/v1/oauthtoken",
  "token_info_url": "https://sts.googleapis.com/v1/introspect",
}

使用基于浏览器的身份验证登录

如需使用基于浏览器的登录身份验证来验证身份，您可以使用以下方法之一：

  • 如果您在创建配置文件时使用了 --activate 标志，或者使用 gcloud config set auth/LOGIN_CONFIG_FILE 激活了配置文件，gcloud CLI 会自动使用配置文件： 

    gcloud auth login

  • 如需通过指定配置文件的位置进行登录，请运行以下命令： 

    gcloud auth login --login-config=LOGIN_CONFIG_FILE
  • 如需使用环境变量来指定配置文件的位置，请将 CLOUDSDK_AUTH_LOGIN_CONFIG_FILE 设置为配置文件的路径。

停用基于浏览器的登录

如需停止使用登录配置文件，请执行以下操作：

  • 如果您在创建配置文件时使用了 --activate 标志，或者使用 gcloud config set auth/LOGIN_CONFIG_FILE 激活了配置文件，则必须运行以下命令以取消设置： 

    gcloud config unset auth/login_config_file
  • 清除 CLOUDSDK_AUTH_LOGIN_CONFIG_FILE 环境变量（如果已设置）。

gcloud CLI 无头登录

如需使用 gcloud CLI 登录 Microsoft Entra ID，请执行以下操作：

OIDC

  1. 按照发送登录请求中的步骤操作。 让用户使用 OIDC 通过 Microsoft Entra ID 登录您的应用。

  2. 从重定向网址的 id_token 参数中复制 ID 令牌，并将其保存到本地机器上某个安全位置的文件中。在后面的步骤中，您需要将 PATH_TO_OIDC_ID_TOKEN 设置为此文件的路径。

  3. 通过运行以下命令生成类似于以下内容的配置服务文件：

    gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
    --credential-source-file=PATH_TO_OIDC_ID_TOKEN \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file=config.json

    替换以下内容：

    • WORKFORCE_POOL_ID：员工池 ID。
    • PROVIDER_ID：提供方 ID。
    • PATH_TO_OIDC_ID_TOKEN：存储 IdP 令牌的文件的路径。
    • WORKFORCE_POOL_USER_PROJECT：用于配额和结算的项目编号或 ID。主账号必须具有此项目的 serviceusage.services.use 权限。

    命令完成后，Microsoft Entra ID 会创建以下配置文件：

    {
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "file": "PATH_TO_OIDC_CREDENTIALS"
  }
}

  4. 打开 gcloud CLI 并运行以下命令：

    gcloud auth login --cred-file=PATH_TO_OIDC_CREDENTIALS

    将 PATH_TO_OIDC_CREDENTIALS 替换为上一步中的输出文件的路径。

    gcloud CLI 会以透明方式将您的凭据发布到 Security Token Service 端点；之后在该端点交换临时的 Google Cloud 访问令牌。

    您现在可以对 Google Cloud 运行 gcloud CLI 命令。

SAML

  1. 让用户登录您的 Microsoft Entra ID 应用并获取 SAML 响应。

  2. 将 Microsoft Entra ID 返回的 SAML 响应保存到本地机器上的安全位置，然后存储该路径，如下所示：

    SAML_ASSERTION_PATH=SAML_ASSERTION_PATH

  3. 生成配置文件，如下所示。运行以下命令：

    gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \
    --credential-source-file=SAML_ASSERTION_PATH  \
    --workforce-pool-user-project=PROJECT_ID  \
    --output-file=config.json

    替换以下内容：

    • WORKFORCE_PROVIDER_ID：您在本指南前面部分创建的员工身份池提供方 ID
    • WORKFORCE_POOL_ID：您在本指南前面部分创建的员工身份池 ID
    • SAML_ASSERTION_PATH：SAML 断言文件的路径
    • PROJECT_ID：项目 ID

    生成的配置文件类似于以下内容：

    {
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "credential_source": {
    "file": "SAML_ASSERTION_PATH"
  },
  "workforce_pool_user_project": "PROJECT_ID"
}

  4. 如需使用令牌交换登录 gcloud，请运行以下命令：

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

    然后，gcloud 会以透明方式将您的 Microsoft Entra ID 凭据交换为临时的 Google Cloud 访问令牌，以便您对 Google Cloud 进行其他 gcloud 调用。

    您将看到类似如下所示的输出：

    Authenticated with external account user credentials for:
[principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/USER_ID].

  5. 如需列出凭据账号和您的活跃账号，请运行以下命令：

    gcloud auth list

测试访问权限

您现在可以访问支持员工身份联合并且您有权访问的 Google Cloud 服务。在本指南的前面部分中，您向特定部门中的所有身份授予了项目 TEST_PROJECT_ID 的 Storage Admin 角色。现在，您可以通过列出 Cloud Storage 存储桶来测试您是否具有访问权限。

控制台（联合）

您现在可以对 Google Cloud 执行 gcloud CLI 命令。

  • 进入 Cloud Storage 页面。
  • 验证您是否可以看到 TEST_PROJECT_ID 的现有存储桶列表。

gcloud CLI

如需列出您有权访问的项目的 Cloud Storage 存储桶和对象，请运行以下命令：

gcloud storage ls --project="TEST_PROJECT_ID"

主账号必须具有指定项目的 serviceusage.services.use 权限。

删除用户

员工身份联合为联合用户身份创建用户元数据和资源。例如，如果您选择在您的 IdP 中删除用户，则还必须在 Google Cloud 中明确删除这些资源。为此，请参阅删除员工身份联合用户及其数据。

您可能会看到资源仍与已删除的用户关联。这是因为删除用户元数据和资源需要长时间运行的操作。在您启动用户身份删除后，用户在删除操作之前启动的进程可以继续运行，直到这些进程完成或取消。

后续步骤