配置使用 Active Directory 的工作负载身份联合

本指南介绍了如何使用工作负载身份联合，让工作负载通过 Active Directory 凭据向 Google Cloud 进行身份验证。

如果您在 Active Directory 环境中运行 Windows Server 工作负载，则这些工作负载可能有权访问 Active Directory 凭据。例如：

• Windows 服务可能配置为以网域用户身份登录。
• IIS 应用可能配置为以群组管理的服务账号 (gMSA) 运行。

通过将工作负载身份联合与 Active Directory Federation Services (AD FS) 结合使用，您可以让这些工作负载将其 Active Directory Kerberos 凭据交换为短期有效的 Google Cloud 凭据。工作负载可以使用这些短期有效的凭据访问 Google Cloud API。

通过链接两个令牌交换，将 Active Directory 凭据与短期 Google Cloud 凭据交换：

1. 工作负载使用 OpenID Connect (OIDC)、SAML-POST 或 WS-Trust 从 AD FS 请求 OIDC 令牌或 SAML 断言。为了向 AD FS 进行身份验证，工作负载使用集成式 Windows 身份验证 (IWA) 及其现有的 Active Directory 凭据。
2. 然后，工作负载使用工作负载身份联合将 OIDC 令牌或 SAML 断言与 Security Token Service 令牌交换，还可以视需要模拟 Google Cloud 服务账号。

本文档介绍了如何使用 Workload Authenticator for Windows 自动执行此过程，而无需更改应用。

准备 AD FS

您只需执行这些步骤一次。

选择协议

准备 AD FS 的方式取决于要使用的协议：

• SAML：您可以允许工作负载使用 SAML 或 WS-Trust 获取 SAML 断言。

  如需使用 SAML 或 WS-Trust，请在 AD FS 中创建信赖方，并将工作负载身份池配置为信任此信赖方颁发的断言。

  工作负载可以使用 SAML-POST 绑定或 WS-Trust 通过其 Active Directory 用户向 AD FS 进行身份验证。然后，AD FS 会发出一个 SAML 断言，其中包含有关工作负载的 Active Directory 用户的信息以及其他信息（例如群组成员资格）。

  使用 SAML 或 WS-Trust 需要 AD FS 3.0、AD FS for Windows Server 2016 或更新版本的 AD FS。

• OIDC：您可以允许工作负载使用 OIDC 获取 OIDC 令牌。

  如需使用 OIDC，请在 AD FS 中创建 OIDC 客户端（原生应用）和 OIDC 资源（Web API）。然后，您可以将工作负载身份池配置为信任为 Web API 颁发的访问令牌。

  工作负载可以使用其 Active Directory 用户和 OAuth client_credentials 授权向 AD FS 进行身份验证。然后，AD FS 会颁发访问令牌，但不会颁发 ID 令牌。

  访问令牌包含有关 OIDC 客户端应用的信息，但不包含有关工作负载的 Active Directory 用户或其群组成员资格的任何信息。

  由于访问令牌不包含有关 Active Directory 用户的任何信息，因此使用 OIDC 可能比使用 SAML 或 WS-Trust 更灵活。

  使用 OIDC 需要 AD FS for Windows Server 2016 或更新版本的 AD FS。

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

IWA 前提条件

本部分介绍使用本指南所需的 IWA 前提条件。

如果您之前未将 IWA 与 AD FS 搭配使用，请确保满足以下前提条件：

• 您已将 AD FS 配置为允许 Windows 身份验证并使用正确的服务主账号名称。
• 您已配置身份验证扩展保护，以使其与您的 AD FS 部署兼容。

注册工作负载

如需在 AD FS 中注册工作负载，请执行以下操作：

OIDC

如需允许工作负载使用 OIDC，您需要在 AD FS 中有两个应用注册：

• 类型为原生应用或服务器应用的应用注册。

• 类型为 Web API 的应用注册，对应于 Google Cloud 上的工作负载身份池提供商。

注册客户端应用

创建一个代表工作负载的客户端应用。如果您有多个需要访问 Google Cloud 的工作负载，则可能需要创建多个客户端应用。

如需在 AD FS 中注册客户端应用，请执行以下操作：

1. 打开 AD FS MMC 管理单元并导航到应用组。
2. 点击添加应用组。

3. 在欢迎页面上，执行以下操作：

   1. 在文本字段中输入客户端的名称。
   2. 选择服务器应用。
   3. 点击下一步。

4. 在服务器应用页面上，执行以下操作：

   1. 在 text-field 文本字段中，输入客户端标识符（客户端 ID）和重定向 URI。

      如果您仅计划使用 client_credentials 授权类型，则不会使用重定向 URI，您可以使用 http://localhost/ 等 URI。

   2. 点击下一步。

5. 在配置应用凭据页面上，执行以下操作：

   1. 选择客户端的身份验证方式。如需使用 IWA，请将 Windows 集成身份验证设置为已启用。
   2. 选择网域用户（将应用配置为以该网域用户身份运行）。
   3. 点击下一步。

6. 在摘要页面上检查设置，然后点击下一步。

7. 点击关闭以关闭对话框。

为工作负载身份池创建 Web API 应用

创建另一个类型为 Web API 的应用注册。此应用对应于一个工作负载身份池提供方，您使用它来设置与 Google Cloud 的信任关系。

如需在 AD FS 中创建应用，请执行以下操作：

1. 打开 AD FS MMC 管理单元并导航到应用组。
2. 点击添加应用组。
3. 在欢迎页面上，输入一个名称（例如 Workload Identity Federation (test environment)），然后选择 Web API。然后点击下一步。

4. 在配置 Web API 页面上，输入 Web API 的信赖方标识符。

   您可以使用以下 URI 作为信赖方标识符，而不是定义自定义信赖方标识符：

   https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/WORKLOAD_POOL_ID/providers/PROVIDER_ID
   

   请替换以下内容：

   • PROJECT_NUMBER：您用于创建工作负载身份池的 Google Cloud 项目的项目编号。
   • WORKLOAD_POOL_ID：您选择的工作负载 ID，用于标识工作负载身份池。稍后在创建工作负载身份池时，您必须使用相同的 ID。
   • PROVIDER_ID：您选择的工作负载 ID，用于标识工作负载身份池提供商。稍后在创建工作负载身份池提供程序时，必须使用相同的 ID。

   以这种方式设置 URI 格式可确保信赖方标识符唯一标识工作负载身份池提供方。

   稍后在配置工作负载身份池提供商时，您需要信赖方标识符。

5. 点击下一步。

6. 在应用访问权限控制政策页面上，选择适当的访问权限政策，然后点击下一步。

7. 在配置应用权限页面上，添加您之前创建的客户端应用。然后点击下一步。

8. 在摘要页面上检查设置，然后点击下一步。

9. 点击关闭以关闭对话框。

SAML 或 WS-Trust

在 AD FS 中创建信赖方信任：

1. 打开 AD FS MMC 管理单元。
2. 导航到信赖方信任。
3. 点击添加信赖方信任。
4. 在添加信赖方信任向导的欢迎页面上，执行以下操作：
   1. 选择声明感知
   2. 点击启动。
5. 在选择数据源页面上，执行以下操作：
   1. 选择手动输入有关信赖方的数据。
   2. 点击下一步。

6. 在指定显示名称页面上，执行以下操作：

   1. 输入信任的名称。
   2. 点击下一步。

7. 在配置证书页面上，点击下一步。虽然工作负载身份联合支持加密的 SAML，但此过程中未进行介绍。如需了解详情，请参阅本指南后面部分的创建身份池和提供商中的 gcloud CLI 说明。

8. 在配置网址页面上，执行以下操作：

   SAML

   使用以下设置：

   • 将启用对 SAML 2.0 WebSSO 协议的支持设置为已启用

   • 在信赖方 SAML 2.0 单点登录服务网址字段中，输入以下网址：

     https://sts.googleapis.com/v1/token
     

   WS-Trust

   保留默认设置

9. 点击下一步。

10. 在配置标识符页面上，输入信赖方标识符。

    您可以使用以下 URI 作为信赖方标识符，而不是定义自定义信赖方标识符：

    https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/WORKLOAD_POOL_ID/providers/PROVIDER_ID
    

    请替换以下内容：

    • PROJECT_NUMBER：您用于创建工作负载身份池的 Google Cloud 项目的项目编号。
    • WORKLOAD_POOL_ID：您选择的工作负载 ID，用于标识工作负载身份池。稍后在创建工作负载身份池时，您必须使用相同的 ID。
    • PROVIDER_ID：您选择的工作负载 ID，用于标识工作负载身份池提供商。稍后在创建工作负载身份池提供程序时，必须使用相同的 ID。

    以这种方式设置 URI 格式可确保信赖方标识符唯一标识工作负载身份池提供方。

    稍后在配置工作负载身份池提供商时，您需要信赖方标识符。

11. 点击下一步。

12. 在选择访问控制策略页面上，选择适当的访问控制策略，然后点击下一步。

13. 在准备好添加信任页面上，检查设置并点击下一步。

14. 在完成页面上，点击关闭以关闭对话框。

为了与工作负载身份联合兼容，SAML 断言必须至少包含一个唯一标识 Active Directory 用户的声明。为此，您通常可以使用名称 ID 声明，该声明对应于 SAML 断言中 NameID 元素的值。

如需自定义 SAML 断言的一组声明，您必须修改信赖方信任的声明颁发策略。要修改声明颁发策略，请执行以下操作：

1. 在信赖方信任列表中，选择刚刚创建的信任，然后点击 Edit claim issuance policy。
2. 点击 Add rule。
3. 在添加转换声明规则向导的选择规则类型页面上，执行以下操作：
   1. 选择转换传入声明。
   2. 点击下一步。

4. 在 Configure claim rule 页面上，配置以下设置：

   • 声明规则名称：Name Identifier。
   • 传入声明类型：选择主 SID、UPN 或其他声明来唯一标识主题。
   • 传出声明类型：名称 ID
   • 传出名称 ID 格式：未指定。

5. 选择传递所有声明值，然后点击完成。

6. （可选）配置其他规则，以在 SAML 断言中包含更多特性。

7. 点击 OK 以关闭声明颁发策略对话框。

配置工作负载身份联合

您只需为每个要联合的 Azure AD 租户或 AWS 账号执行一次这些步骤。然后，您可以为多个工作负载以及多个 Google Cloud 项目使用相同的工作负载身份池和提供方。

如需开始配置工作负载身份联合，请执行以下操作：

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

最好使用专用项目来管理工作负载身份池和提供方。

2. Make sure that billing is enabled for your Google Cloud project.

Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.

Enable the APIs

定义特性映射和条件

AWS 或 Azure 工作负载的特定于环境的凭据包含多个特性，您必须决定要在 Google Cloud 中用作主体标识符 (google.subject) 的特性。

您也可以视需要映射其他特性。然后，您可以在授予对资源的访问权限时引用这些附加特性。

OIDC

特性映射可以使用 AD FS 访问令牌中嵌入的声明作为来源特性。

要对应用进行身份验证，您可以使用以下特性映射：

google.subject=assertion.appid

此映射会将 google.subject 设置为 appid 声明的值，其中包含 AD FS 应用的客户端 ID。

SAML 或 WS-Trust

如本指南前面所述，您的特性映射可以使用 AD FS 发出的断言中嵌入的声明。

使用以下映射让工作负载身份联合使用 SAML 断言中的名称 ID 声明来唯一标识用户：

google.subject=assertion.subject

如果您已将声明颁发策略配置为在 SAML 断言中包含其他声明，则可以添加其他映射。例如：

google.groups=assertion.attributes['http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid']
attribute.userip=['http://schemas.microsoft.com/2014/09/requestcontext/claims/userip'][0]

您可以视需要定义特性条件。特性条件是可以检查断言特性和目标特性的 CEL 表达式。如果给定凭据的特性条件评估结果为 true，则接受凭据。否则，凭据会被拒绝。

OIDC

您可以使用属性条件来限制哪些客户端可以使用工作负载身份联合获取短期有效的 Google Cloud 令牌。

例如，以下条件定义应用必须使用 IWA 向 AD FS 进行身份验证：

assertion.authmethod=='http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/windows'

如需控制可以获取 Google Cloud 短期有效的凭据的应用列表，请勿定义属性条件。相反，请在 AD FS 中使用客户端权限来定义要允许的应用。

SAML 或 WS-Trust

您可以使用属性条件来限制哪些 Active Directory 用户可以使用工作负载身份联合获取短期有效的 Google Cloud 令牌。

例如，以下条件只允许包含特定群组成员资格声明的 SAML 断言：

"S-1-5-6" in google.groups

创建工作负载身份池和提供方

所需的角色

如需获得配置工作负载身份联合所需的权限，请让您的管理员为您授予项目的以下 IAM 角色：

• Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin)
• Service Account Admin (roles/iam.serviceAccountAdmin)

如需详细了解如何授予角色，请参阅管理访问权限。

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

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

控制台

1. 在 Google Cloud 控制台中，前往新建工作负载提供方和池页面。

   转到“新建工作负载提供方和池”

2. 在创建身份池下，输入以下内容：

   • 名称：池的名称。该名称还用作池 ID。池 ID 创建后便无法更改。
   • 说明：描述池用途的文本。

3. 点击继续。

4. 配置提供方设置：

   OIDC

   • 选择提供方：OpenID Connect (OIDC)。
   • 提供方名称：提供方的名称。该名称还用作提供方 ID。提供方 ID 创建后便无法更改。
   • 颁发者网址：https://ADFS_DOMAIN/adfs，其中 ADFS_DOMAIN 是 AD FS 服务器或服务器场的公共域名。

   SAML

   如需从与 SAML 2.0 兼容的 IdP 配置工作负载身份联合，您可以按照 gcloud CLI 说明操作。

5. 点击继续。

6. 在配置提供商特性下，添加您之前识别的特性映射。

7. 在特性条件下，输入您之前确定的特性条件。如果您没有特性条件，请将该字段留空。

8. 点击保存以创建工作负载身份池和提供商。

gcloud

1. 创建新的工作负载身份池：

   gcloud iam workload-identity-pools create WORKLOAD_POOL_ID \
       --location="global" \
       --description="DESCRIPTION" \
       --display-name="DISPLAY_NAME"
   

   请替换以下内容：

   • WORKLOAD_POOL_ID：池的唯一 ID。
   • DISPLAY_NAME：池的名称。
   • DESCRIPTION：池的说明。授予对池身份的访问权限时，系统会显示此说明。

2. 添加工作负载身份池提供商：

   OIDC

   gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
       --location="global" \
       --workload-identity-pool="WORKLOAD_POOL_ID" \
       --issuer-uri="https://ADFS_DOMAIN/adfs" \
       --allowed-audiences="RELYING_PARTY_ID" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS"
   

   请替换以下内容：

   • PROVIDER_ID：提供商的唯一 ID。
   • WORKLOAD_POOL_ID：池的 ID。
   • ADFS_DOMAIN：AD FS 服务器或服务器场的公共域名。
   • RELYING_PARTY_ID：AD FS 中工作负载身份联合池的 Web API 应用的信赖方标识符。只有在使用自定义信赖方标识符时，才需要此参数。
   • MAPPINGS：您之前识别的特性映射的逗号分隔列表。
   • CONDITIONS：您之前确定的特性条件。如果您没有特性条件，请移除该参数。

   前缀 gcp- 已被保留，不能在池或提供方 ID 中使用。

   SAML 或 WS-Trust

   curl -O https://ADFS_DOMAIN/federationmetadata/2007-06/federationmetadata.xml
   
   gcloud iam workload-identity-pools providers create-saml PROVIDER_ID \
       --location="global" \
       --workload-identity-pool="POOL_ID" \
       --idp-metadata-path="federationmetadata.xml" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS"
   

   请替换以下内容：

   • PROVIDER_ID：提供商的唯一 ID。
   • ADFS_DOMAIN：您的 AD FS 服务器或服务器场的域名。
   • WORKLOAD_POOL_ID：池的 ID。
   • MAPPINGS：您之前识别的特性映射的逗号分隔列表。
   • CONDITIONS（可选）：您在本指南前面部分中创建的特性条件。

   前缀 gcp- 已被保留，不能在池或提供方 ID 中使用。

   示例：

   gcloud iam workload-identity-pools providers create-saml example-provider \
       --location="global" \
       --workload-identity-pool="pool-1" \
       --idp-metadata-path="federationmetadata.xml" \
       --attribute-mapping=google.subject=assertion.subject"
   

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

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

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

   请注意，即使配置了 SAML 加密提供商密钥，工作负载身份联合仍然可以处理明文断言。

   创建工作负载身份联合 SAML 断言加密密钥

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

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

   gcloud iam workload-identity-pools providers keys create KEY_ID \
       --workload-identity-pool WORKLOAD_POOL_ID \
       --provider PROVIDER_ID \
       --location global \
       --use encryption \
       --spec KEY_SPECIFICATION

   请替换以下内容：

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

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

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

   请替换以下内容：

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

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

   1. 将证书文件移至 AD FS 服务器。
   2. 在 AD FS 服务器上，右键点击初始按钮（或者按 Win+X），然后点击 Windows PowerShell (管理员)。
   3. 在 PowerShell 中运行以下命令以启用加密：

              Set-AdfsRelyingPartyTrust `
              -TargetName NAME `
              -SamlResponseSignature MessageAndAssertion `
              -EncryptionCertificate PATH `
              -EncryptClaims $True
          

      请替换以下内容：

      • NAME：您的信赖方信任的名称
      • PATH：证书文件的路径

   WS-Trust 用户：此功能仅在您使用 SAML 时可用。

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

   删除工作负载身份联合加密密钥

   如需删除 SAML 加密密钥，请运行以下命令：

     gcloud iam workload-identity-pools providers keys delete KEY_ID \
         --workload-identity-pool WORKLOAD_POOL_ID \
         --provider PROVIDER_ID \
         --location global

   请替换以下内容：

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

   支持的 SAML 加密算法

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

   • http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p
   • http://www.w3.org/2009/xmlenc11#rsa-oaep"
   • http://www.w3.org/2001/04/xmlenc#rsa-1_5"

   工作负载身份联合支持以下块加密算法：

   • http://www.w3.org/2001/04/xmlenc#aes128-cbc
   • http://www.w3.org/2001/04/xmlenc#aes192-cbc
   • http://www.w3.org/2001/04/xmlenc#aes256-cbc
   • http://www.w3.org/2009/xmlenc11#aes128-gcm
   • http://www.w3.org/2009/xmlenc11#aes256-gcm

对工作负载进行身份验证

您必须为每个工作负载执行一次这些步骤。

允许外部工作负载访问 Google Cloud 资源

如需为您的工作负载提供对 Google Cloud 资源的访问权限，我们建议您向主账号授予直接资源访问权限。在这种情况下，主账号是联合用户。某些 Google Cloud 产品存在 Google Cloud API 限制。如果您的工作负载调用存在限制的 API 端点，您可以改用服务账号模拟。在这种情况下，主账号是充当身份的 Google Cloud 服务账号。您可以向此服务账号授予资源的访问权限。

直接资源访问权限

您可以使用 Google Cloud 控制台或 gcloud CLI 向联合身份授予直接对资源的访问权限。

控制台

如需使用 Google Cloud 控制台授予直接对某个资源的 IAM 角色，您必须进入该资源的页面，然后授予该角色。以下示例展示了如何进入 Cloud Storage 页面，然后向联合身份授予直接对 Cloud Storage 存储桶的 Storage Object Viewer (roles/storage.objectViewer) 角色。

1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。
   

   进入“存储桶”

2. 在存储桶列表中，点击您要针对其授予角色的存储桶的名称。

3. 选择页面顶部附近的权限标签。

4. 点击 授予访问权限按钮。

   系统会显示“添加主账号”对话框。

5. 在新主账号字段中，输入需要访问您存储桶的一个或多个身份。

   按主体

   principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT
   

   替换以下内容：

   • PROJECT_NUMBER：项目编号
   • POOL_ID：工作负载池 ID
   • SUBJECT：从您的 IdP 映射的单个主体，例如 [e-mail]

   按群组

   principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP
   

   替换以下内容：

   • PROJECT_NUMBER：项目编号
   • WORKLOAD_POOL_ID：工作负载池 ID
   • GROUP：从您的 IdP 映射的群组，例如：[e-mail]

   按特性

   principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
   

   替换以下内容：

   • PROJECT_NUMBER：项目编号
   • WORKLOAD_POOL_ID：工作负载池 ID
   • ATTRIBUTE_NAME：从您的 IdP 映射的属性之一
   • ATTRIBUTE_VALUE：属性的值

6. 从选择角色下拉菜单中选择一个或多个角色。 您选择的角色将显示在窗格中，其中包含对角色授予的权限的简短说明。

7. 点击保存。

gcloud

如需使用 gcloud CLI 针对项目中的资源授予 IAM 角色，请执行以下操作：

1. 获取在其中定义了资源的项目的编号。

   gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\)
   

2. 授予对该资源的访问权限。

   如需使用 gcloud CLI 向符合特定条件的外部身份授予 Workload Identity User 角色 (roles/iam.workloadIdentityUser)，请运行以下命令。

   按主体

   gcloud storage buckets add-iam-policy-binding BUCKET_ID \
       --role=roles/storage.objectViewer \
       --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"

   按群组

   gcloud storage buckets add-iam-policy-binding BUCKET_ID \
       --role=roles/storage.objectViewer \
       --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"

   按属性

   gcloud storage buckets add-iam-policy-binding BUCKET_ID \
       --role=roles/storage.objectViewer \
       --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"

   替换以下内容：

   • BUCKET_ID：要针对其授予访问权限的存储桶
   • PROJECT_NUMBER：包含工作负载身份池的项目的编号
   • POOL_ID：工作负载身份池的池 ID
   • SUBJECT：已映射到 google.subject 的特性的预期值
   • GROUP：已映射到 google.groups 的特性的预期值
   • ATTRIBUTE_NAME：特性映射中的自定义特性的名称
   • ATTRIBUTE_VALUE：属性映射中的自定义属性的值

   您可以针对支持 IAM 允许政策的任何 Google Cloud 资源授予角色。

   注意：您必须在成员标识符中使用项目编号，而不是项目 ID。

服务账号模拟

1. 如需为外部工作负载创建服务账号，请执行以下操作：

   1. Enable the IAM, Security Token Service, and Service Account Credentials APIs.

      Enable the APIs

   2. 创建一个服务账号以代表工作负载。最好为每个工作负载使用专用服务账号。

      该服务账号不需要与工作负载身份池位于同一项目中。

   3. 向服务账号授予对您希望外部身份访问的资源的访问权限。

   4. 向服务账号授予 Workload Identity User 角色 (roles/iam.workloadIdentityUser)。

   5. 创建一个服务账号以代表工作负载。我们建议您为每个工作负载使用专用服务账号。

      该服务账号不需要与工作负载身份池位于同一项目中，但您必须引用包含该服务账号的项目。

2. 如需使用 Google Cloud 控制台或 gcloud CLI 通过服务账号模拟向联合身份授予访问权限，请执行以下操作：

   控制台

   如需使用 Google Cloud 控制台向具有服务账号的联合身份授予 IAM 角色，请执行以下操作：

   1. 执行以下操作，创建一个充当要模拟的身份的服务账号：

      1. Enable the IAM, Security Token Service, and Service Account Credentials APIs.

         Enable the APIs

      2. 创建一个代表工作负载的身份的服务账号。我们建议您为每个工作负载使用专用服务账号。

         该服务账号不需要与工作负载身份池位于同一项目中，但在授予 IAM 访问权限时，您必须引用包含该服务账号的项目。

      3. 向服务账号授予对您希望外部身份访问的资源的访问权限。

   2. 如需使用服务账号模拟授予访问权限，请执行以下操作。

      1. 进入工作负载身份池页面。

         转到“工作负载身份池”

      2. 选择授予访问权限。

      3. 在向服务账号授予访问权限对话框中，选择使用服务账号模拟授予访问权限。

      4. 在服务账号列表中，选择要模拟的外部身份的服务账号，然后执行以下操作：

      5. 如需选择池中的哪些身份可以模拟服务账号，请执行以下操作之一：

         • 如需仅允许工作负载身份池的特定身份模拟服务账号，请选择仅限与过滤条件匹配的身份。

         • 在属性名称列表中，选择您要作为过滤依据的属性。

         • 在属性值字段中，输入属性的预期值；例如，如果您使用属性映射 google.subject=assertion.sub，请将属性名称设置为 subject，并将属性值设置为外部身份提供方颁发的令牌中 sub 声明的值。

      6. 如需保存配置，请点击保存，然后点击关闭。

   gcloud

   如需使用 gcloud CLI 向符合特定条件的外部身份授予 Workload Identity User 角色 (roles/iam.workloadIdentityUser)，请运行以下命令。

   按主体

   gcloud storage buckets add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
       --role=roles/storage.objectViewer \
       --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"

   按群组

   gcloud storage buckets add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
       --role=roles/storage.objectViewer \
       --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"

   按属性

   gcloud storage buckets add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
       --role=roles/storage.objectViewer \
       --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"

   替换以下内容：

   • SERVICE_ACCOUNT_EMAIL：服务账号的电子邮件地址
   • PROJECT_NUMBER：包含工作负载身份池的项目的编号
   • POOL_ID：工作负载身份池的池 ID
   • SUBJECT：已映射到 google.subject 的特性的预期值
   • GROUP：已映射到 google.groups 的特性的预期值
   • ATTRIBUTE_NAME：特性映射中的自定义特性的名称
   • ATTRIBUTE_VALUE：属性映射中的自定义属性的值

   注意：您必须在成员标识符中使用项目编号，而不是项目 ID。

创建凭据配置

通过使用 Workload Authenticator for Windows，您可以允许 Cloud 客户端库和 gcloud CLI 和 Terraform 等工具使用 Active Directory 凭据向 Google Cloud 进行身份验证。

Workload Authenticator for Windows 是一种开源工具，它充当 Cloud 客户端库和 gcloud CLI 等工具的插件：

1. 当工具或库需要新凭据时，它会在后台启动 Workload Authenticator。
2. Workload Authenticator 使用 OIDC、SAML 或 WS-Trust 从 AD FS 获取新的令牌或 SAML 断言，并将后者传回给工具或库。
3. 然后，工具或库使用工作负载身份联合，将令牌或 SAML 断言与短期有效的 Google Cloud 凭据交换。

如需使用 Workload Authenticator for Windows，您必须创建一个凭据配置文件。此文件定义以下内容：

• 在哪里可以找到 Workload Authenticator for Windows 可执行文件 (wwauth.exe)，以及要使用呢哪些参数运行它
• 要使用的工作负载身份池和提供商
• 需要模拟的服务账号

如需创建凭据配置文件，请在运行工作负载的 Windows Server 上执行以下操作：

1. 右键点击开始按钮（或者按 Win+X），然后点击 Windows PowerShell。

2. 下载 Workload Authenticator for Windows，并将其保存到工作负载可以访问的位置：

   (New-Object Net.WebClient).DownloadFile(
     "https://github.com/GoogleCloudPlatform/iam-windows-authenticator/releases/latest/download/wwauth.exe",
     "${env:ProgramData}\wwauth.exe")
   

   如果您是通过使用 Workload Authenticator for Windows 创建凭据配置文件，则该文件包含其可执行文件的路径。如果您稍后删除或移动该可执行文件，工作负载将无法找到和使用该可执行文件。

3. 启动 wwauth.exe：

   & ${env:ProgramData}\wwauth.exe
   

   此时将打开一个配置对话框：

   

4. 选择 AD FS 标签页，然后输入以下设置：

   • AD FS 服务器的颁发者 URI：AD FS 服务器或服务器场的公共 URI。

     https://ADFS_DOMAIN/adfs/
     

     将 ADFS_DOMAIN 替换为 AD FS 服务器或服务器场的公共域名。

   后续设置取决于您要使用的协议：

   OIDC

   • 协议：AdfsOidc
   • 信赖方 ID：保留默认值。
   • 客户端 ID：AD FS 中服务器应用的客户端标识符（客户端 ID）。

   SAML

   • 协议：AdfsSamlPost
   • 断言消费者服务网址：https://sts.googleapis.com/v1/token。
   • 使用证书对请求进行签名：已停用

   WS-Trust

   • 协议：AdfsWsTrust

5. 选择工作负载身份标签页，然后输入以下设置：

   • 项目编号：包含工作负载身份池的项目的项目编号
   • 池 ID：工作负载身份池的 ID
   • 提供方 ID：工作负载身份池提供方的 ID
   • 模拟服务账号：已启用（如果您使用服务账号模拟）
   • 电子邮件地址：服务账号的电子邮件地址（如果您使用服务账号模拟）

6. 选择 AD FS 标签页，并验证信赖方 ID 字段现在包含您的工作负载身份池提供方的网址。

7. 点击应用，然后选择要保存凭据配置文件的文件位置。

   与服务账号密钥不同，凭据配置文件不包含任何密钥，不需要保密。如需详细了解凭据配置文件，请访问 https://google.aip.dev/auth/4117。

现在，您可以测试配置了：

1. 选择用于测试的 Active Directory 用户。此用户可以是工作负载的 Active Directory 用户，也可以是您当前用于登录的用户。

2. 如需使用当前用户测试配置，请点击测试。

   如需使用其他用户进行测试，请选择测试 > 以用户身份测试配置，然后输入用户的凭据。

   现在，工具会尝试通过执行以下步骤来向 Google Cloud 进行身份验证：

   1. 从 AD FS 获取 OIDC 令牌或 SAML 断言。
   2. 获取 Google Security Token Service 令牌。
   3. 模拟服务账号（如果您使用服务账号模拟）。

   如果身份验证成功，您会看到以下消息：测试已成功完成：

   

使用凭据配置访问 Google Cloud

如需允许工具和客户端库使用您的凭据配置，请在运行工作负载的 Windows Server 上执行以下操作：

1. 右键点击开始按钮，然后点击运行。
2. 输入 sysdm.cpl 并点击确定。
3. 在高级标签页上，点击环境变量。

4. 在系统变量部分中，添加两个新变量：

   名称	值
   GOOGLE_APPLICATION_CREDENTIALS	凭据配置文件的路径
   GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES	1

5. 点击确定。

6. 使用支持工作负载身份联合并且可以自动查找凭据的客户端库或工具：

   C++

   从 v2.6.0 版开始，C++ 版 Google Cloud 客户端库支持工作负载身份联合。如需使用工作负载身份联合，您必须使用 gRPC 1.36.0 版或更高版本构建客户端库。

   Go

   如果 Go 客户端库使用 golang.org/x/oauth2 模块的 v0.0.0-20210218202405-ba52d332ba99 版本或更高版本，则客户端库支持身份联合。

   如要查看客户端库使用的模块版本，请运行以下命令：

   cd $GOPATH/src/cloud.google.com/go
   go list -m golang.org/x/oauth2
   

   Java

   如果 Java 客户端库使用 com.google.auth:google-auth-library-oauth2-http 工件的 0.24.0 版或更高版本，则客户端支持身份联合。

   如需查看该客户端库使用的工件版本，请在应用目录中运行以下 Maven 命令：

   mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http
   

   Node.js

   如果 Node.js 版客户端库使用 7.0.2 版或更高版本的 google-auth-library 软件包，则该客户端库支持工作负载身份联合。

   如要查看客户端库使用的软件包版本，请在应用目录中运行以下命令：

   npm list google-auth-library
   

   创建 GoogleAuth 对象时，您可以指定项目 ID，也可以允许 GoogleAuth 自动查找项目 ID。如要自动查找项目 ID，配置文件中的服务账号必须具有项目的 Browser 角色 (roles/browser) 或具有同等权限的角色。如需了解详情，请参阅 google-auth-library 软件包的 README。

   Python

   如果 Python 客户端库使用 google-auth 软件包的 1.27.0 版本或更高版本，则客户端支持身份联合。

   如要检查客户端库使用的软件包版本，请在已安装该软件包的环境中运行以下命令：

   pip show google-auth
   

   如要为身份验证客户端指定项目 ID，您可以设置 GOOGLE_CLOUD_PROJECT 环境变量，也可以允许客户端自动查找项目 ID。如要自动查找项目 ID，配置文件中的服务账号必须具有项目的 Browser 角色 (roles/browser) 或具有同等权限的角色。如需了解详情，请参阅 google-auth 软件包用户指南。

   gcloud

   如需使用工作负载身份联合进行身份验证，请使用 gcloud auth login 命令：

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

   将 FILEPATH 替换为凭据配置文件的文件路径。

   版本 363.0.0 及更高版本的 gcloud CLI 支持 gcloud CLI 中的工作负载身份联合。

   Terraform

   如果您使用 3.61.0 版或更高版本，则 Google Cloud 提供方支持工作负载身份联合：

   terraform {
     required_providers {
       google = {
         source  = "hashicorp/google"
         version = "~> 3.61.0"
       }
     }
   }
   

   gsutil

   如需使用工作负载身份联合进行身份验证，请使用以下方法之一：

   将 gsutil 与 gcloud 结合使用时，请按正常方式登录：

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

   将 gsutil 用作独立的命令行应用时，请修改 .boto 文件以包含以下部分：

   [Credentials]
   gs_external_account_file = FILEPATH
   

   在这两种情况下，请将 FILEPATH 替换为凭据配置文件的文件路径。

   379.0.0 版及更高版本的 gcloud CLI 支持 gsutil 中的工作负载身份联合。

   bq

   如需使用工作负载身份联合进行身份验证，请使用 gcloud auth login 命令，如下所示：

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

   将 FILEPATH 替换为凭据配置文件的文件路径。

   390.0.0 版及更高版本的 gcloud CLI 支持 bq 中的工作负载身份联合。

后续步骤

• 详细了解工作负载身份联合。
• 了解使用工作负载身份联合的最佳实践。
• 了解如何管理工作负载身份池和提供方。