使用 PingOne AIC 配置员工身份联合

本文档介绍了如何使用 PingOne Advanced Identity Cloud (AIC) 作为身份提供方 (IdP) 来配置员工身份联合，以及如何管理对Google Cloud的访问权限。配置 PingOne AIC IdP 后，联合用户可以使用 SAML 2.0 协议访问支持员工身份联合的 Google Cloud 服务。

准备工作

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

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

   gcloud init

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

   注意：如果您之前安装了 gcloud CLI，请确保通过运行 gcloud components update 来获得最新版本。
3. 如需登录，您的 IdP 必须提供已签名的身份验证信息：SAML IdP 响应必须经过签名。
4. 如需接收有关贵组织或Google Cloud 产品的变更的重要信息，您必须提供必要的联系人。如需了解详情，请参阅员工身份联合概览。

费用

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

所需的角色

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

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

如果您是在开发或测试环境（而非生产环境）中配置权限，则可以授予 Identity and Access Management (IAM) Owner (roles/owner) 基本角色。此角色还包括员工身份联合所需的权限。

创建员工身份池

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 必须在 Google Cloud中的所有员工身份池范围内具有全局唯一性。如需了解如何设置 ID 的格式，请参阅 API 文档中的查询参数部分。
• ORGANIZATION_ID：员工身份池所属 Google Cloud 组织的数字形式组织 ID。员工身份池可在组织中的所有项目和文件夹中使用。
• DISPLAY_NAME：可选。您的员工身份池的显示名称。
• DESCRIPTION：可选。员工身份池说明。
• SESSION_DURATION：可选。会话时长，以在后面附加 s 的数字表示，例如 3600s。会话时长，用于确定来自此员工池的 Google Cloud 访问令牌、控制台（联合）登录会话和 gcloud CLI 登录会话的有效时长。会话时长默认为 1 小时（3600 秒）。会话时长值必须介于 15 分钟（900 秒）到 12 小时（43200 秒）之间。

提示：运行 gcloud iam workforce-pools create --help 以查找您可以为此命令自定义的其他参数。

控制台

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

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

   转到“员工身份池”

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

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

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

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

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

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

创建 PingOne AIC 应用

本部分介绍如何创建 PingOne AIC 应用集成。

创建托管的 IdP

1. 在原生控制台 > 访问权限管理中，依次前往Realm > REALM_NAME > 信息中心，然后点击 SAML 应用。
2. 依次点击添加实体提供方> 托管。

3. 输入实体 ID。记录此值以备日后使用。

   注意： 在实体 ID 等值中，Advanced Identity Cloud 会将多个空格截断为单个空格。例如，如果存在 MyEntityID 值（一个空格），则添加名为 My Entity ID（多个空格）的新实体会导致错误，因为 Advanced Identity Cloud 会将它们视为相同。
   1. 验证实体提供方基本网址值是否正确。Advanced Identity Cloud 会将此值用于所有与 SAML 2.0 相关的端点。
   2. 在 Meta Aliases（元别名）部分，在 Identity Provider Meta Alias（身份提供方元别名）属性中提供一个适合用作网址的值。此别名在信任圈中必须是唯一的。
   3. 点击创建。
   4. 在 Assertion Processing（断言处理）标签页的 Attribute Mapper（属性映射器）部分，将 SAML 属性名称映射到本地属性名称。SAML 属性名称是指在断言中使用的名称。
   5. 点击每个映射的添加或更新。
   6. 点击保存更改。

使用属性

本部分介绍了如何使用 SAML 断言中的属性。

在以下示例中，SAML 断言中的属性会映射到本地属性：

SAML 属性	本地属性
IDPEmail	mail
FirstName	givenName
groups	groups

在属性映射部分中设置必需的属性。在本指南的后面部分，您将在创建员工身份池提供方时映射这些属性。

导出提供方元数据

您可以通过以下任一方式访问托管提供商的 SAML 2.0 元数据：

• 通过 REST

  运行以下命令：

  curl --output METADATA_XML \
      "https://TENANT_ENV_FQDN/am/ExportSamlMetadata?entityid=ENTITY_ID&realm=/REALM"
  

• 在浏览器中

  在浏览器中打开租户环境的元数据网址，下载 XML 文件： https://TENANT_ENV_FQDN/am/ExportSamlMetadata?entityid=ENTITY_ID&realm=/REALM

1. 将 XML 文件保存到本地机器。

将 Google 作为远程 SP 导入

1. 准备 Google Cloud SP 元数据 XML。使用以下模板，替换占位值：

   <?xml version="1.0" encoding="UTF-8"?>
   <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="https://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID">
      <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
         <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
         <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
         <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID" index="0" isDefault="true"/>
      </md:SPSSODescriptor>
   </md:EntityDescriptor>
   

2. 您可以通过以下任一方式导入元数据：

   • 在控制台中

     1. 在 PingOne AIC 管理控制台中，前往 SAML Applications（SAML 应用）。
     2. 依次点击添加实体提供程序 > 远程。
     3. 上传您刚刚创建的 Google Cloud SP 元数据 XML 文件。
     4. 点击创建。

   • 通过 REST

     1. 将 XML 元数据转换为 base64url 编码的字符串。
     2. 获取访问令牌。

     3. 运行以下命令：

        curl --request POST \
            --header 'authorization: Bearer ACCESS_TOKEN' \
            --header 'Content-Type: application/json' \
            --header 'Accept-API-Version: resource=1.0' \
            --data-raw '{"standardMetadata": "BASE64URL_ENCODED_METADATA"}' \
            'https://TENANT_ENV_FQDN/am/json/realms/root/realms/alpha/realm-config/saml2/remote?_action=importEntity'
        

创建信任圈 (CoT)

1. 依次前往大区 > REALM_NAME > 应用 > 联盟 > 信任圈。
2. 点击添加信任圈。
3. 输入名称，然后点击创建。
4. 在 Circle of Trust 页面上，在 Entity Providers 属性中，选择您的托管 IdP 和 Google Cloud 远程 SP。
5. 点击保存更改。

创建 PingOne AIC 员工身份池提供方

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

创建 SAML 员工身份池提供方

1. 如需创建 SAML 员工身份池提供方，您需要确保身份提供方元数据至少包含 SAML 实体 ID、单点登录网址和一个签名公钥。请按以下步骤进行此操作：

   gcloud

   1. 保存 PingOne AIC 应用中的 SAML 元数据。

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

      gcloud iam workforce-pools providers create-saml WORKFORCE_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
      

      替换以下内容：

      • WORKFORCE_PROVIDER_ID：提供方 ID。
      • WORKFORCE_POOL_ID：员工身份池 ID。
      • DISPLAY_NAME：显示名称。
      • DESCRIPTION：说明。
      • XML_METADATA_PATH：您从 PingOne AIC 导出的 XML 格式元数据文件的路径。
      • ATTRIBUTE_MAPPING：属性映射；例如，google.subject=assertion.subject,google.groups=assertion.attributes.groups,attribute.department=assertion.attributes.department[0]。
      • ATTRIBUTE_CONDITION：可选属性条件；例如，如需将 ipaddr 属性限制为特定 IP 范围，您可以设置条件 assertion.ipaddr.startsWith('98.11.12.')。

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

      此命令会将 SAML 断言中的 subject、groups 和 department 分别分配给 google.subject、google.groups 和 attribute.department 属性。该属性条件还可确保只有特定 IP 范围内的用户才能使用此员工提供方登录。

   控制台

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

   1. 在 Google Cloud 控制台中，前往员工身份池页面： 前往“员工身份池”
   2. 在员工身份池表中，选择要为其创建提供方的池。
   3. 在提供方部分中，点击 添加提供方。
   4. 在选择提供方供应商列表中，选择通用身份提供方。
   5. 在选择身份验证协议中，选择 SAML。
   6. 在创建提供方部分中，执行以下操作：
      1. 在名称中，输入提供方的名称。
      2. 可选：在说明中，输入提供方的说明。
      3. 在 IDP 元数据文件 (XML) 中，选择您从 PingOne AIC 导出的元数据 XML 文件。
      4. 如需创建状态为已启用的提供方，请确保启用提供方处于开启状态。
      5. 点击继续。
   7. 在分享提供方信息部分中，点击继续。
   8. 可选：如需启用详细审核日志记录，请在配置提供方部分的详细日志记录中，点击启用属性值审核日志记录切换开关。

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

      如需为员工身份池提供方停用详细审核日志记录，请在创建提供方时将启用属性值审核日志记录切换开关保持在关闭状态。如需停用详细审核日志记录，您还可以更新提供方。

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

   创建提供方后，系统会将您重定向到提供方属性页面。

   如需配置属性映射和条件，请执行以下操作：

   1. 系统提示时，登录您的外部 IdP 以验证默认属性映射。

   2. 在提供方属性页面上，查看和修改属性映射和条件：

      1. 如需添加或修改属性映射，请执行以下操作：

         1. 点击添加映射以添加新映射，或修改现有映射。
         2. 在 Google n 字段中（其中 n 为数字），选择一个 Google Cloud支持的密钥。

         3. 在相应的 SAML n 字段中，输入 IdP 属性名称或 CEL 表达式，例如：

            google.subject=assertion.subject,
            google.groups=assertion.attributes['https://example.com/aliases'],
            attribute.costcenter=assertion.attributes.costcenter[0]
            

      2. 如需添加属性条件，请执行以下操作：

         警告：如果您的多租户 IdP 具有单个颁发者 URI，您必须使用属性条件来确保访问权限仅限于正确的租户。如需了解详情，请参阅与 GitHub 或其他多租户身份提供方联合时使用属性条件。
         1. 点击添加条件。
         2. 在属性条件字段中，以 CEL 格式输入条件，例如 assertion.attributes.ipaddr.startsWith('98.11.12.')。

   3. 如需验证映射，请点击保存并重新获取令牌。

   4. 如需完成设置，请点击保存并退出。

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

本部分介绍了如何管理 PingOne AIC 用户对 Google Cloud 资源的访问权限。

本指南中使用的示例项目可能与您设置员工身份联合时使用的项目不同。

您可以管理单个身份、一组身份或整个池的角色。如需了解详情，请参阅允许政策的员工主账号标识符。

使用映射的部门属性

如需向 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 员工身份联合控制台（也称为控制台 [联合]），请执行以下操作：

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

   前往控制台（联合）

2. 输入提供方名称，格式如下：

   locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID

出现提示时，输入您的 PingOne AIC 凭据。

基于浏览器的 Google Cloud CLI 登录

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

运行以下命令以创建登录配置文件：

Linux 和 macOS

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

Windows (PowerShell)

gcloud iam workforce-pools create-login-config `
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID `
    --output-file=LOGIN_CONFIG_PATH

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

替换以下内容：

• WORKFORCE_POOL_ID：员工身份联合身份池 ID。
• WORKFORCE_PROVIDER_ID：员工身份联合提供方 ID。
• LOGIN_CONFIG_PATH：要写入登录配置文件的路径。例如 login-config.json。

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

登录配置文件内容类似于以下内容：

{
  "universe_domain": "googleapis.com",
  "universe_cloud_web_domain": "cloud.google",
  "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"
}

注意：我们建议您先确保此文件的内容正确无误，然后保护该文件（例如，将其设为只读并使用 ACL 限制访问权限）。该文件未经过验证；怀有恶意的操作者如果拥有该文件写入权限，就可以更改端点和拦截凭据。

通过环境变量、有效 gcloud CLI 配置中的属性指向登录配置文件，或直接将其与 gcloud auth login 命令搭配使用：

环境变量

如需使用环境变量来使用登录配置文件，请完成以下说明：

1. 将 CLOUDSDK_AUTH_LOGIN_CONFIG_FILE 环境变量设置为登录配置文件的路径。

2. 运行以下命令：

   gcloud auth login

3. gcloud CLI 会引用该环境变量来查找登录配置文件，然后启动身份验证流程。按照基于浏览器的流程操作，以便对 gcloud CLI 进行身份验证和授权，使其能够代表您访问资源以供日后执行命令。

如需停止为 gcloud auth login 命令使用登录配置文件，请清除 CLOUDSDK_AUTH_LOGIN_CONFIG_FILE 环境变量。

gcloud CLI 配置

如需将登录配置文件与 gcloud CLI 配置属性搭配使用，请完成以下说明：

1. 使用以下命令将有效 gcloud CLI 配置的 auth/login_config_file 属性设置为登录配置文件的路径：

   gcloud config set auth/login_config_file LOGIN_CONFIG_PATH

2. 运行以下命令：

   gcloud auth login

3. gcloud CLI 会引用配置属性来查找登录配置文件，然后启动身份验证流程。按照基于浏览器的流程操作，以便对 gcloud CLI 进行身份验证和授权，使其能够代表您访问资源以供日后执行命令。

如需停止将登录配置文件用于 gcloud auth login 命令，请使用以下命令取消设置相应属性：

gcloud config unset auth/login_config_file

gcloud auth login

如需直接将登录配置文件与 gcloud auth login 命令搭配使用，请完成以下说明：

• 如果您在创建登录配置文件时使用了 --activate 标志，请运行以下命令：

  gcloud auth login

• 如果您在创建登录配置文件时未使用 --activate 标志，请运行以下命令：

  Linux 和 macOS

  gcloud auth login \
      --login-config=LOGIN_CONFIG_PATH

  Windows (PowerShell)

  gcloud auth login `
      --login-config=LOGIN_CONFIG_PATH

  将 LOGIN_CONFIG_PATH 替换为登录配置文件的路径。

gcloud auth login 命令会将访问凭据存储在您的主目录中。经过身份验证的主账号将成为活跃 gcloud CLI 配置中的活跃主账号。除非被替换，否则 gcloud CLI 会使用这些存储的凭据来访问 Google Cloud。

警告：有权访问文件系统的任何用户都可以使用 gcloud auth login 创建的已存储的访问凭据。为减少系统被入侵的后果，请严格区分人工使用和工作负载使用，并且不要在具有持久性存储的远程系统上为自动化工作负载使用 gcloud auth login。请尽可能将 Secret 管理器与环境变量搭配使用。

如需详细了解如何强化远程系统，请参阅 缓解 Google Cloud CLI 的 OAuth 令牌被盗用。

gcloud CLI 无头登录

如需使用 SAML 协议通过 gcloud CLI 登录 PingOne AIC，请执行以下操作：

1. 让用户登录您的 PingOne AIC 应用并获取 SAML 响应。
2. 将 PingOne AIC 返回的 SAML 响应保存到本地机器上的安全位置。将该路径存储在环境变量中，例如：SAML_ASSERTION_PATH=/tmp/saml_assertion.xml。

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
   

   替换以下内容：

   • SAML_ASSERTION_PATH：SAML 断言文件的路径。
   • PROJECT_ID：项目 ID。

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

   {
     "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"
   }
   

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

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

   然后，gcloud 会以透明方式将您的 PingOne AIC 凭据交换为临时的 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].

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

   gcloud auth list
   

测试访问权限

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

控制台（联合）登录

如需在控制台（联合）中验证您的访问权限，请执行以下操作：

1. 转到 Cloud Storage 页面。
2. 验证您是否可以看到项目 TEST_PROJECT_ID 的现有存储分区列表。

gcloud CLI

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

gcloud alpha storage ls --project="TEST_PROJECT_ID"

主账号必须具有 gcloud CLI 会话中设置的项目的 serviceusage.services.use 权限：PROJECT_ID。

后续步骤

• 删除员工身份联合用户及其数据。
• 了解哪些 Google Cloud 产品支持员工身份联合。
• 设置用户对控制台（联合）的访问权限。