使用 Microsoft Entra ID 配置员工身份联合

本文档介绍了如何使用 Microsoft Entra ID 身份提供方 (IdP) 配置员工身份联合，以及如何使用 Microsoft Graph 将最多 400 个群组从 Microsoft Entra ID 映射到 Google Cloud 。本文档随后会介绍如何向这些群组授予 IAM 角色，以及如何使作为这些群组的成员的 Microsoft Entra ID 用户登录到 Google Cloud。然后，用户可以访问他们通过 IAM 授予了相应访问权限且支持员工身份联合的 Google Cloud 产品。

如需将少于 150 个的群组从 Microsoft Entra ID 映射到 Google Cloud，请参阅使用 Microsoft Entra ID 配置员工身份联合并让用户登录。

主要概念

本部分介绍了本文档后面用于配置员工身份联合的概念。

额外属性

如需映射最多 400 个群组，您可以在创建员工身份池提供方时通过指定 extra-attributes 标志来使用额外属性。您可以将额外属性与以下协议搭配使用：

  • 使用隐式流的 OIDC
  • 使用代码流的 OIDC
  • SAML 2.0 协议

Microsoft Entra ID 应用可在令牌中发出的群组邮箱数量上限对于 SAML 为 150 个，对于 JWT 为 200 个。如需详细了解此限制，请参阅使用 Microsoft Entra ID 为应用配置群组声明。为了检索更多群组，员工身份联合使用 Microsoft Identity 的 OAuth 2.0 客户端凭证流来获取凭证，以便员工身份联合能够查询 Microsoft Graph API 并提取用户的群组。

如需使用额外属性，概括来讲，您需要执行以下步骤：

  • 创建新的 Microsoft Entra ID 应用或更新现有应用，以从 Microsoft Graph API 获取用户的群组成员资格。如需详细了解 Microsoft Graph 如何从 Microsoft Entra ID 中检索大量群组，请参阅群组超额用量。

  • 创建员工身份池提供方时，您可以使用 extra-attributes 标志配置员工身份联合，以便从 Microsoft Graph API 检索用户的群组邮箱。

员工身份联合最多可以从 Microsoft Graph API 检索 999 个群组。如果 Microsoft Graph API 返回的群组数量超过 999 个，登录会失败。

如需减少 Microsoft Graph API 返回的群组数量，您可以在创建员工身份池提供方时使用 --extra-attributes-filter 标志来优化员工身份联合的查询。

员工身份联合从 Microsoft Graph API 检索群组后，会生成访问令牌。员工身份联合最多可向访问令牌添加 400 个群组，因此，如需进一步将群组数量过滤为 400 个或更少，您可以在创建员工身份池提供方时指定包含通用表达式语言 (CEL) 表达式的属性映射。

准备工作

  1. 确保您已设置 Google Cloud 组织。

  2. 安装 Google Cloud CLI。 安装完成后，运行以下命令来初始化 Google Cloud CLI： 

    gcloud init

    如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

  3. 在 Microsoft Entra ID 中，确保已为隐式流启用 ID 令牌。如需了解详情，请参阅启用 ID 令牌隐式授权。
  4. 如需登录，您的 IdP 必须提供已签名的身份验证信息：OIDC IdP 必须提供 JWT，而 SAML IdP 响应必须经过签名。
  5. 如需接收有关贵组织或Google Cloud 产品的变更的重要信息，您必须提供必要的联系人。如需了解详情，请参阅员工身份联合概览。
  6. 您打算映射的所有群组都必须在 Microsoft Entra ID 中标记为安全群组。

费用

员工身份联合是一项免费功能。不过，员工身份联合的详细审核日志记录使用 Cloud Logging。如需了解 Logging 价格，请参阅 Google Cloud Observability 价格。

所需的角色

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

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

如果您是在开发或测试环境（而非生产环境）中配置权限，则可以授予 IAM Owner (roles/owner) 基本角色，该角色也可提供员工身份联合的权限。

创建 Microsoft Entra ID 应用

本部分介绍如何使用 Microsoft Entra 管理员门户创建 Microsoft Entra ID 应用。或者，您也可以更新现有应用。如需了解其他详细信息，请参阅在 Microsoft Entra ID 生态系统中建立应用。

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

OIDC

如需创建使用 OIDC 协议的 Microsoft Entra ID 应用注册，请执行以下操作：

  1. 登录 Microsoft Entra 管理员门户。

  2. 依次前往身份 > 应用 > 应用注册。

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

    1. 点击 New registration（新注册）。

    2. 输入应用的名称。

    3. 在 Supported account types（支持的账号类型）中，选择一个选项。

    4. 在重定向 URI 部分的选择平台下拉列表中，选择 Web。

    5. 在文本字段中输入重定向网址。用户成功登录后，系统会将用户重定向到此网址。如果您要配置对控制台（联合）的访问权限，请使用以下网址格式：

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

      替换以下内容：

      • WORKFORCE_POOL_ID：您在本文档后面部分创建员工身份池时将使用的员工身份池 ID，例如：entra-id-oidc-pool

      • WORKFORCE_PROVIDER_ID：您在本文档后面部分创建员工身份池提供方时将使用的员工身份池提供方 ID，例如：entra-id-oidc-pool-provider

        如需了解如何设置 ID 的格式，请参阅 API 文档中的查询参数部分。

    6. 如需创建应用注册，请点击注册。

    7. 如需使用本指南后面部分提供的示例属性映射，您必须创建自定义 department 属性。

SAML

如需创建使用 SAML 协议的 Microsoft Entra ID 应用注册，请执行以下操作：

  1. 登录 Microsoft Entra 管理员门户。

  2. 在左侧导航菜单中，依次前往 Entra ID > 企业应用。

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

    1. 依次点击新建应用 > 创建您自己的应用。

    2. 在随即显示的创建您自己的应用窗格中，输入应用的名称。

    3. 点击创建。

    4. 依次前往单点登录 > SAML。

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

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

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

        替换以下内容：

        • WORKFORCE_POOL_ID：您在本文档后面部分创建员工身份池时将使用的员工身份池 ID，例如：entra-id-saml-pool

        • WORKFORCE_PROVIDER_ID：您在本文档后面部分创建员工身份池提供方时将使用的员工身份池提供方 ID，例如：entra-id-saml-pool-provider

          如需了解如何设置 ID 的格式，请参阅 API 文档中的查询参数部分。

      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

      3. 如需启用 IdP 发起的登录，请将中继状态字段设置为以下值：

        https://console.cloud.google/

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

    6. 如需使用本指南后面部分提供的示例属性映射，您必须创建自定义 department 属性。

使用 Microsoft Entra ID 配置大量群组

本部分介绍了如何使用 OIDC 和 SAML 协议将最多 400 个群组从 Microsoft Entra ID 映射到员工身份联合。

通过 OIDC 隐式流使用 Microsoft Entra ID 配置大量群组

本部分介绍如何通过隐式流使用 OpenID Connect (OIDC) 协议将最多 400 个群组从 Microsoft Entra ID 映射到员工身份联合。

配置 Microsoft Entra ID 应用

您可以配置现有 Microsoft Entra ID 应用，也可以创建新应用。如需配置应用，请执行以下操作：

  1. 在 Microsoft Entra ID 门户中，执行以下操作：
    • 如需注册新应用，请按照注册新应用中的说明操作。
    • 如需更新现有应用，请执行以下命令：
      • 依次前往身份 > 应用 > 企业应用。
      • 选择要更新的应用。
  2. 按照证书和密钥中的说明在应用中创建新的客户端密钥。请务必记录客户端密钥值，因为该值仅显示一次。

    请记下您创建或更新的应用中的以下值。您在本文档后面部分配置员工身份池提供方时将提供这些值。

    • Client ID
    • Issuer URI
    • Client Secret
    • Tenant ID

  3. 如需检索 Microsoft Entra ID 群组，请添加 API 权限，以允许员工身份联合使用 Microsoft Graph API 从 Microsoft Entra ID 访问用户信息，并授予管理员同意书。 在 Microsoft Entra ID 中，执行以下操作：

    1. 前往 API 权限。
    2. 点击添加权限。
    3. 选择 Microsoft API。
    4. 选择应用权限。
    5. 在搜索字段中，输入 User.ReadBasic.All。
    6. 点击添加权限。

    您可以采用群组对象标识符 (ID) 或群组邮箱（对于启用了邮件的群组）的形式检索 Microsoft Entra ID 群组。

    如果您选择以群组邮箱的形式检索群组，则必须执行下一步。

  4. 如需以群组邮箱的形式检索 Microsoft Entra ID 群组，请执行以下操作。如果您以群组对象标识符的形式检索群组，请跳过此步骤。
    1. 在搜索字段中，输入 GroupMember.Read.All。
    2. 点击添加权限。
    3. 点击您的域名对应的授予管理员同意书。
    4. 在随即显示的对话框中，点击是。
    5. 前往您之前创建或更新的 Microsoft Entra ID 应用的概览页面。
    6. 点击端点。

    颁发者 URI 是 OIDC 元数据文档 URI，省略了路径 /.well-known/openid-configuration。

    例如，如果 OIDC 元数据文档为 https://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/.well-known/openid-configuration，则颁发者 URI 为 https://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/。

创建员工身份池

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：可选。会话时长，以在后面附加 s 的数字表示，例如 3600s。会话时长，用于确定来自此员工池的 Google Cloud 访问令牌、控制台（联合）登录会话和 gcloud CLI 登录会话的有效时长。会话时长默认为 1 小时（3600 秒）。会话时长值必须介于 15 分钟（900 秒）到 12 小时（43200 秒）之间。

控制台

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

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

    转到“员工身份池”

  2. 为员工身份池选择组织。员工身份池可在组织中的所有项目和文件夹中使用。

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

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

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

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

员工身份池的会话时长默认为 1 小时（3600 秒）。会话时长用于确定来自此员工池的 Google Cloud 访问令牌以及控制台（联合）和 gcloud CLI 登录会话的有效时长。创建池后，您可以更新池以设置自定义会话时长。会话时长必须介于 15 分钟（900 秒）到 12 小时（43,200 秒）之间。

配置 OIDC 隐式流员工身份池提供方

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

gcloud iam workforce-pools providers create-oidc PROVIDER_ID \
    --workforce-pool=WORKFORCE_POOL_ID \
    --location=global \
    --display-name=DISPLAY_NAME \
    --issuer-uri=ISSUER_URI \
    --client-id=CLIENT_ID \
    --attribute-mapping=ATTRIBUTE_MAPPING \
    --web-sso-response-type=id-token \
    --web-sso-assertion-claims-behavior=only-id-token-claims \
    --extra-attributes-issuer-uri=EXTRA_ATTRIBUTES_ISSUER_URI \
    --extra-attributes-client-id=EXTRA_ATTRIBUTES_CLIENT_ID \
    --extra-attributes-client-secret-value=EXTRA_ATTRIBUTES_CLIENT_SECRET \
    --extra-attributes-type=EXTRA_ATTRIBUTES_TYPE  \
    --extra-attributes-filter=EXTRA_ATTRIBUTES_FILTER \
    --detailed-audit-logging

请替换以下内容：

  • PROVIDER_ID：提供方的唯一 ID。 前缀 gcp- 已被预留，不能在池或提供方 ID 中使用。
  • WORKFORCE_POOL_ID：员工池 ID。
  • DISPLAY_NAME：提供方的显示名称。
  • ISSUER_URI：您在本文档前面部分创建的 Microsoft Entra ID 应用的颁发者 URI。
  • CLIENT_ID：Microsoft Entra ID 应用中的客户端 ID。
  • ATTRIBUTE_MAPPING：从 Microsoft Entra ID 到 Google Cloud的属性映射。 例如，如需映射 Microsoft Entra ID 中的 groups 和 subject 属性，请使用以下属性映射： 
    --attribute-mapping=”google.groups=assertion.groups, google.subject=assertion.sub"

    如需了解详情，请参阅属性映射。

  • EXTRA_ATTRIBUTES_ISSUER_URI：Microsoft Entra ID 应用中的颁发者 URI。
  • EXTRA_ATTRIBUTES_CLIENT_ID：Microsoft Entra ID 应用中的客户端 ID。
  • EXTRA_ATTRIBUTES_CLIENT_SECRET：Microsoft Entra ID 应用中的额外客户端密钥。
  • EXTRA_ATTRIBUTES_TYPE：使用 azure-ad-groups-mail 可检索群组的邮箱。使用 azure-ad-groups-id 可检索群组的 ID。
  • EXTRA_ATTRIBUTES_FILTER：可选。在查询 Microsoft Graph API 以获取群组时使用的过滤表达式。您可以使用此参数来确保从 IdP 提取的群组数量不超过 400 个群组的上限。

    以下示例会提取邮件 ID 中包含前缀 sales 的群组： 

    --extra-attributes-filter='"mail:sales"'

    以下表达式会提取显示名称中包含字符串 sales 的群组。

    --extra-attributes-filter='"displayName:sales"'

  • 员工身份联合详细审核日志记录会将从 IdP 接收的信息记录到 Logging。详细的审核日志记录有助于排查员工身份池提供方配置的问题。如需了解如何通过详细审核日志记录来排查属性映射错误，请参阅一般属性映射错误。如需了解 Logging 价格，请参阅 Google Cloud Observability 价格。

    如需为员工身份池提供方停用详细审核日志记录，请在运行 gcloud iam workforce-pools providers create 时省略 --detailed-audit-logging 标志。如需停用详细审核日志记录，您还可以更新提供方。

通过 OIDC 代码流在 Microsoft Entra ID 中配置大量群组

本部分介绍了如何通过代码流使用 OIDC 协议将最多 400 个群组从 Microsoft Entra ID 映射到员工身份联合。

配置 Microsoft Entra ID 应用

您可以配置现有 Microsoft Entra ID 应用，也可以创建新应用。如需配置应用，请执行以下操作：

  1. 在 Microsoft Entra ID 门户中，执行以下操作：
    • 如需注册新应用，请按照注册新应用中的说明操作。
    • 如需更新现有应用，请执行以下命令：
      • 依次前往身份 > 应用 > 企业应用。
      • 选择要更新的应用。
  2. 按照证书和密钥中的说明在应用中创建新的客户端密钥。请务必记录客户端密钥值，因为该值仅显示一次。

    请记下您创建或更新的应用中的以下值。您在本文档后面部分配置员工身份池提供方时将提供这些值。

    • Client ID
    • Issuer URI
    • Client Secret
    • Tenant ID

  3. 如需检索 Microsoft Entra ID 群组，请添加 API 权限，以允许员工身份联合使用 Microsoft Graph API 从 Microsoft Entra ID 访问用户信息，并授予管理员同意书。 在 Microsoft Entra ID 中，执行以下操作：

    1. 前往 API 权限。
    2. 点击添加权限。
    3. 选择 Microsoft API。
    4. 选择委托权限。
    5. 在搜索字段中，输入 User.Read。
    6. 点击添加权限。

    您可以采用群组对象标识符 (ID) 或群组邮箱（对于启用了邮件的群组）的形式检索 Microsoft Entra ID 群组。

    如果您选择以群组邮箱的形式检索群组，则必须执行下一步。

  4. 如需以群组邮箱的形式检索 Microsoft Entra ID 群组，请执行以下操作。如果您以群组对象标识符的形式检索群组，请跳过此步骤。
    1. 在搜索字段中，输入 GroupMember.Read.All。
    2. 点击添加权限。
    3. 点击您的域名对应的授予管理员同意书。
    4. 在随即显示的对话框中，点击是。
    5. 前往您之前创建或更新的 Microsoft Entra ID 应用的概览页面。
    6. 点击端点。

    颁发者 URI 是 OIDC 元数据文档 URI，省略了路径 /.well-known/openid-configuration。

    例如，如果 OIDC 元数据文档为 https://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/.well-known/openid-configuration，则颁发者 URI 为 https://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/。

创建员工身份池

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：可选。会话时长，以在后面附加 s 的数字表示，例如 3600s。会话时长，用于确定来自此员工池的 Google Cloud 访问令牌、控制台（联合）登录会话和 gcloud CLI 登录会话的有效时长。会话时长默认为 1 小时（3600 秒）。会话时长值必须介于 15 分钟（900 秒）到 12 小时（43200 秒）之间。

控制台

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

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

    转到“员工身份池”

  2. 为员工身份池选择组织。员工身份池可在组织中的所有项目和文件夹中使用。

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

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

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

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

员工身份池的会话时长默认为 1 小时（3600 秒）。会话时长用于确定来自此员工池的 Google Cloud 访问令牌以及控制台（联合）和 gcloud CLI 登录会话的有效时长。创建池后，您可以更新池以设置自定义会话时长。会话时长必须介于 15 分钟（900 秒）到 12 小时（43,200 秒）之间。

配置 OIDC 代码流员工身份池提供方

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

gcloud iam workforce-pools providers create-oidc PROVIDER_ID \
    --workforce-pool=WORKFORCE_POOL_ID \
    --location=global \
    --display-name=DISPLAY_NAME \
    --issuer-uri=ISSUER_URI \
    --client-id=CLIENT_ID \
    --client-secret-value="OIDC_CLIENT_SECRET" \
    --attribute-mapping=ATTRIBUTE_MAPPING \
    --web-sso-response-type=code \
    --web-sso-assertion-claims-behavior=merge-user-info-over-id-token-claims \
    --extra-attributes-issuer-uri=EXTRA_ATTRIBUTES_ISSUER_URI \
    --extra-attributes-client-id=EXTRA_ATTRIBUTES_CLIENT_ID \
    --extra-attributes-client-secret-value=EXTRA_ATTRIBUTES_CLIENT_SECRET \
    --extra-attributes-type=EXTRA_ATTRIBUTES_TYPE  \
    --extra-attributes-filter=EXTRA_ATTRIBUTES_FILTER \
    --detailed-audit-logging

请替换以下内容：

  • PROVIDER_ID：提供方的唯一 ID。 前缀 gcp- 已被预留，不能在池或提供方 ID 中使用。
  • WORKFORCE_POOL_ID：员工池 ID。
  • DISPLAY_NAME：提供方的显示名称。
  • ISSUER_URI：您在本文档前面部分创建的 Microsoft Entra ID 应用的颁发者 URI。
  • CLIENT_ID：Microsoft Entra ID 应用中的客户端 ID。
  • ATTRIBUTE_MAPPING：从 Microsoft Entra ID 到 Google Cloud的属性映射。 例如，如需映射 Microsoft Entra ID 中的 groups 和 subject 属性，请使用以下属性映射： 
    --attribute-mapping=”google.groups=assertion.groups, google.subject=assertion.sub"

    如需了解详情，请参阅属性映射。

  • EXTRA_ATTRIBUTES_ISSUER_URI：Microsoft Entra ID 应用中的颁发者 URI。
  • EXTRA_ATTRIBUTES_CLIENT_ID：Microsoft Entra ID 应用中的客户端 ID。
  • EXTRA_ATTRIBUTES_CLIENT_SECRET：Microsoft Entra ID 应用中的额外客户端密钥。
  • EXTRA_ATTRIBUTES_TYPE：使用 azure-ad-groups-mail 可检索群组的邮箱。使用 azure-ad-groups-id 可检索群组的 ID。
  • EXTRA_ATTRIBUTES_FILTER：可选。在查询 Microsoft Graph API 以获取群组时使用的过滤表达式。您可以使用此参数来确保从 IdP 提取的群组数量不超过 400 个群组的上限。

    以下示例会提取邮件 ID 中包含前缀 sales 的群组： 

    --extra-attributes-filter='"mail:sales"'

    以下表达式会提取显示名称中包含字符串 sales 的群组。

    --extra-attributes-filter='"displayName:sales"'

  • 员工身份联合详细审核日志记录会将从 IdP 接收的信息记录到 Logging。详细的审核日志记录有助于排查员工身份池提供方配置的问题。如需了解如何通过详细审核日志记录来排查属性映射错误，请参阅一般属性映射错误。如需了解 Logging 价格，请参阅 Google Cloud Observability 价格。

    如需为员工身份池提供方停用详细审核日志记录，请在运行 gcloud iam workforce-pools providers create 时省略 --detailed-audit-logging 标志。如需停用详细审核日志记录，您还可以更新提供方。

通过 SAML 2.0 在 Microsoft Entra ID 中配置大量群组

本部分介绍了如何使用 SAML 2.0 协议将最多 400 个群组从 Microsoft Entra ID 映射到员工身份联合。

配置 Microsoft Entra ID 应用

如需配置应用，请执行以下操作：

  1. 在 Microsoft Entra ID 门户中，执行以下操作：
    • 如需注册新应用，请按照注册新应用中的说明操作。
    • 如需更新现有应用，请执行以下命令：
      • 依次前往身份 > 应用 > 企业应用。
      • 选择要更新的应用。
  2. 按照证书和密钥中的说明在应用中创建新的客户端密钥。请务必记录客户端密钥值，因为该值仅显示一次。

    请记下您创建或更新的应用中的以下值。您在本文档后面部分配置员工身份池提供方时将提供这些值。

    • Client ID
    • Issuer URI
    • Client Secret
    • Tenant ID

  3. 如需检索 Microsoft Entra ID 群组，请添加 API 权限，以允许员工身份联合使用 Microsoft Graph API 从 Microsoft Entra ID 访问用户信息，并授予管理员同意书。 在 Microsoft Entra ID 中，执行以下操作：

    1. 前往 API 权限。
    2. 点击添加权限。
    3. 选择 Microsoft API。
    4. 选择应用权限。
    5. 在搜索字段中，输入 User.ReadBasic.All。
    6. 点击添加权限。

    您可以采用群组对象标识符 (ID) 或群组邮箱（对于启用了邮件的群组）的形式检索 Microsoft Entra ID 群组。

    如果您选择以群组邮箱的形式检索群组，则必须执行下一步。

  4. 如需以群组邮箱的形式检索 Microsoft Entra ID 群组，请执行以下操作。如果您以群组对象标识符的形式检索群组，请跳过此步骤。
    1. 在搜索字段中，输入 GroupMember.Read.All。
    2. 点击添加权限。
    3. 点击您的域名对应的授予管理员同意书。
    4. 在随即显示的对话框中，点击是。
    5. 前往您之前创建或更新的 Microsoft Entra ID 应用的概览页面。
    6. 点击端点。

    颁发者 URI 是 OIDC 元数据文档 URI，省略了路径 /.well-known/openid-configuration。

    例如，如果 OIDC 元数据文档为 https://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/.well-known/openid-configuration，则颁发者 URI 为 https://login.microsoftonline.com/d41ad248-019e-49e5-b3de-4bdfe1fapple/v2.0/。

创建员工身份池

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：可选。会话时长，以在后面附加 s 的数字表示，例如 3600s。会话时长，用于确定来自此员工池的 Google Cloud 访问令牌、控制台（联合）登录会话和 gcloud CLI 登录会话的有效时长。会话时长默认为 1 小时（3600 秒）。会话时长值必须介于 15 分钟（900 秒）到 12 小时（43200 秒）之间。

控制台

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

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

    转到“员工身份池”

  2. 为员工身份池选择组织。员工身份池可在组织中的所有项目和文件夹中使用。

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

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

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

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

员工身份池的会话时长默认为 1 小时（3600 秒）。会话时长用于确定来自此员工池的 Google Cloud 访问令牌以及控制台（联合）和 gcloud CLI 登录会话的有效时长。创建池后，您可以更新池以设置自定义会话时长。会话时长必须介于 15 分钟（900 秒）到 12 小时（43,200 秒）之间。

配置 SAML 2.0 员工身份池提供方

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

gcloud iam workforce-pools providers create-saml PROVIDER_ID \
    --workforce-pool=WORKFORCE_POOL_ID \
    --location=global \
    --display-name=DISPLAY_NAME \
    --idp-metadata-path=XML_METADATA_PATH \
    --attribute-mapping=ATTRIBUTE_MAPPING \
    --extra-attributes-issuer-uri=EXTRA_ATTRIBUTES_ISSUER_URI \
    --extra-attributes-client-id=EXTRA_ATTRIBUTES_CLIENT_ID \
    --extra-attributes-client-secret-value=EXTRA_ATTRIBUTES_CLIENT_SECRET \
    --extra-attributes-type=EXTRA_ATTRIBUTES_TYPE  \
    --extra-attributes-filter=EXTRA_ATTRIBUTES_FILTER \
    --detailed-audit-logging

请替换以下内容：

  • PROVIDER_ID：提供方的唯一 ID。 前缀 gcp- 已被预留，不能在池或提供方 ID 中使用。
  • WORKFORCE_POOL_ID：员工池 ID。
  • DISPLAY_NAME：提供方的显示名称。
  • XML_METADATA_PATH：SAML 2.0 XML 元数据文件的路径。
  • ATTRIBUTE_MAPPING：从 Microsoft Entra ID 到 Google Cloud的属性映射。 例如，如需映射 Microsoft Entra ID 中的 groups 和 subject 属性，请使用以下属性映射： 
    --attribute-mapping=”google.groups=assertion.groups, google.subject=assertion.sub"

    如需了解详情，请参阅属性映射。

  • EXTRA_ATTRIBUTES_ISSUER_URI：Microsoft Entra ID 应用中的颁发者 URI。
  • EXTRA_ATTRIBUTES_CLIENT_ID：Microsoft Entra ID 应用中的客户端 ID。
  • EXTRA_ATTRIBUTES_CLIENT_SECRET：Microsoft Entra ID 应用中的额外客户端密钥。
  • EXTRA_ATTRIBUTES_TYPE：使用 azure-ad-groups-mail 可检索群组的邮箱。使用 azure-ad-groups-id 可检索群组的 ID。
  • EXTRA_ATTRIBUTES_FILTER：可选。在查询 Microsoft Graph API 以获取群组时使用的过滤表达式。您可以使用此参数来确保从 IdP 提取的群组数量不超过 400 个群组的上限。

    以下示例会提取邮件 ID 中包含前缀 sales 的群组： 

    --extra-attributes-filter='"mail:sales"'

    以下表达式会提取显示名称中包含字符串 sales 的群组。

    --extra-attributes-filter='"displayName:sales"'

  • 员工身份联合详细审核日志记录会将从 IdP 接收的信息记录到 Logging。详细的审核日志记录有助于排查员工身份池提供方配置的问题。如需了解如何通过详细审核日志记录来排查属性映射错误，请参阅一般属性映射错误。如需了解 Logging 价格，请参阅 Google Cloud Observability 价格。

    如需为员工身份池提供方停用详细审核日志记录，请在运行 gcloud iam workforce-pools providers create 时省略 --detailed-audit-logging 标志。如需停用详细审核日志记录，您还可以更新提供方。

向群组授予 IAM 角色

在本部分中，您将向群组授予针对 Google Cloud 资源的角色。如需详细了解员工身份联合主账号标识符，请参阅在 IAM 政策中表示员工池用户。

以下示例向 Microsoft Entra ID 群组中的用户授予 Storage Admin 角色 (roles/storage.admin)。 

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

请替换以下内容：

  • PROJECT_ID：项目 ID
  • WORKFORCE_POOL_ID：员工身份池 ID
  • GROUP_ID：群组标识符，具体取决于用于创建员工身份池提供方的 --extra-attributes-type 的值，如下所示：
    • azure-ad-groups-mail：群组标识符是一个邮箱，例如：admin-group@altostrat.com
    • azure-ad-groups-id：群组标识符是群组的 UUID，例如：abcdefgh-0123-0123-abcdef

登录并测试访问权限

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

登录方式

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

控制台（联合）登录

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

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

    前往控制台（联合）

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

    3. 如果系统提示，请在 Microsoft Entra ID 中输入用户凭证。

    如果您启动 IdP 发起的登录，请将以下内容用作中继网址：https://console.cloud.google/。

基于浏览器的 gcloud CLI 登录

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

创建配置文件

如需创建登录配置文件，请运行以下命令。您可以选择添加 --activate 标志来激活文件，将其作为 gcloud CLI 的默认设置。然后，您就可以运行 gcloud auth login，而无需每次都指定配置文件路径。 

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

替换以下内容：

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

该文件包含 gcloud CLI 用于启用基于浏览器的身份验证流程的端点，并将受众设置为在员工身份池提供方中配置的 IdP。该文件不含机密信息。

输出类似于以下内容：

{
  "type": "external_account_authorized_user_login_config",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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",
}

如需阻止 gcloud auth login 自动使用此配置文件，您可以运行 gcloud config unset auth/login_config_file 来取消设置。

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

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

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

    gcloud auth login

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

    gcloud auth login --login-config=LOGIN_CONFIG_FILE_PATH
  • 如需使用环境变量来指定配置文件的位置，请将 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/WORKFORCE_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。
    • WORKFORCE_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/WORKFORCE_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 CLI，请运行以下命令：

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

    然后，gcloud CLI 会以透明方式将您的 Microsoft Entra ID 凭证交换为临时的 Google Cloud 访问令牌。访问令牌使您可以访问 Google Cloud。

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

    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 产品。在本文档的前面部分中，您向在 gcloud projects add-iam-policy-binding 中为 TEST_PROJECT_ID 项目指定的群组标识符中的所有身份授予了 Storage Admin (roles/storage.admin) 角色。

现在，您可以通过列出 Cloud Storage 存储桶来测试您是否具有相应访问权限。

控制台（联合）

如需使用控制台（联合）测试您是否具有相应访问权限，请执行以下操作：

  • 转到 Cloud Storage 页面。

    转到 Cloud Storage

  • 验证您是否可以看到 TEST_PROJECT_ID 的现有存储桶列表。

gcloud CLI

如需测试您是否具有使用 gcloud CLI 的访问权限，您可以列出您有权访问的项目的 Cloud Storage 存储桶和对象。如需执行此操作，请运行以下命令： 主账号必须具有指定项目的 serviceusage.services.use 权限。

gcloud storage ls --project="TEST_PROJECT_ID"

删除用户

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

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

后续步骤