使用 PingFederate 配置员工身份联合

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

准备工作

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

2. 安装 Google Cloud CLI，然后 使用联合身份登录 gcloud CLI。 登录后， 运行以下命令来初始化 Google Cloud CLI：

   gcloud init

   注意：如果您之前安装了 gcloud CLI，请确保通过运行 gcloud components update 获得最新版本。
如需设置使用 SAML 2.0 协议的 PingFederate 应用，请在 PingFederate 中执行以下操作：
1. 设置 PingFederate IdP 的 SAML 2.0 实体 ID 。如需了解详情，请参阅指定联合信息。

2. 创建 SAML 2.0 SP 连接，请参阅 选择 SP 连接类型 并执行以下操作：

   1. 在连接类型 中，选择 Browser SSO Profiles （浏览器单点登录配置文件）和 SAML 2.0 协议 。
   2. 在导入元数据 中，选择无 。

3. 在常规信息中，将合作伙伴的实体 ID（连接 ID）设置为以下值：

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

4. 在 SAML 配置文件 中，启用 SP 发起的单点登录 。如果您还计划使用 IdP 发起的单点登录 (SSO)，也可以启用它。

5. 在属性合同 中，定义要在断言中传递的自定义属性（例如，电子邮件地址和群组）。您可以在以后使用这些属性来创建访问权限管理政策。 Google Cloud

6. 在属性合同履行 中，确保 SAML_SUBJECT 映射到对每个用户具有唯一值的字段。例如，电子邮件地址通常对每个用户都是唯一的，不会更改，并且通常用于在 Google Cloud 访问权限管理政策中引用特定用户。

7. 如需设置控制台（联合）登录，请在 Assertion Consumer Service 网址（断言使用者服务网址）中添加以下端点网址：

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

   替换以下内容：

   • WORKFORCE_POOL_ID：您之前创建的员工池的 ID。
   • WORKFORCE_PROVIDER_ID：您稍后创建的员工提供方的 ID。

8. 将此端点的绑定 设置为 POST 。

9. 如需启用控制台（联合）登录，请在 Allowable SAML Bindings（允许的 SAML 绑定）中选择 Redirect（重定向）。

10. 对于签名政策 ，请选择 Sign Response As Required （根据需要对响应签名）。

11. 保存并启用连接。

使用属性

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

使用属性合同在生成的 SAML 断言中指定自定义属性。 配置属性后，您可以在 Google Cloud 中使用这些属性来创建访问权限管理政策。如需详细了解属性合同，请参阅 PingFederate 服务器文档中的属性合同。

例如，在本指南中，我们使用 PingOne 作为 PingFederate 的数据存储区，并使用 PingOne 数据存储区中的 用户属性 映射 email、firstName 和 groups 属性合同，如下所示：

属性合同	值
email	email
firstName	name.given
groups	memberOfGroupIDs

创建 PingFederate 员工身份池提供方

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

创建 SAML 2.0 员工身份池提供方

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

   gcloud

   如需创建 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：PingFederate 中的 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. 在 IDP 元数据文件 (XML) 中，选择 PingFederate 中的元数据 XML 文件。
      3. 点击继续 。
   7. 在分享您的提供方信息 部分中，点击继续 。

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

      1. 在属性映射 中，输入 google.subject 的 CEL 表达式（例如，assertion.subject）。

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

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

   9. 如需启用详细审核日志记录，请在详细日志记录 中点击启用属性值审核日志记录 切换开关。

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

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

本部分介绍了如何管理 PingFederate 用户对 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

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

基于浏览器的 gcloud 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": "",
  "universe_cloud_web_domain": "",
  "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./authorize",
  "token_url": "https://sts./v1/oauthtoken",
  "token_info_url": "https://sts./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 无头登录

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

1. 让用户登录您的 PingFederate 应用并获取 SAML 响应。
2. 将 PingFederate 返回的 SAML 响应保存到本地机器上的安全位置。将路径存储在环境变量中，例如：SAML_ASSERTION_PATH=/path/to/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 会以透明方式将您的 PingFederate 凭据交换为临时的 Google Cloud 访问令牌，以便您对进行其他 gcloud 调用 Google Cloud。输出类似于以下内容：

   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 产品 支持员工身份联合。
• 设置用户对控制台（联合）的访问权限。