使用 X.509 证书配置 Workload Identity Federation

本指南介绍了如何将工作负载身份联合与由证书颁发机构 (CA) 颁发的 X.509 证书结合使用，以向 Google Cloud 进行身份验证并访问 Google Cloud 资源。

如果您的工作负载拥有 mTLS 客户端证书，您可以将一个或多个 CA 注册到 Workload Identity Federation 作为信任锚，从而向 Google Cloud 进行身份验证。您还可以注册中间 CA。

通过使用工作负载身份联合，您可以让这些工作负载通过双向 TLS (mTLS) 连接获取短期有效的 Google Cloud 凭据。工作负载可以使用这些短期有效的凭据访问 Google Cloud API。

概念

基于 X.509 证书的联合身份验证概念包括：

• 信任锚是指被视为信任根的 CA 证书。任何客户端证书链都应链接到其中一个信任锚点。

• 中间 CA 是可选的证书授权机构证书，可帮助构建客户端证书链。

• 信任库包含用于验证客户端证书链的信任锚证书和中间 CA 证书。CA 会为客户端颁发可信证书。

  您可以将以下类型的客户端证书上传到受信任证书存储区：

  • 您选择的第三方 CA 颁发的证书
  • 您的私有 CA 颁发的证书
  • 签名证书，如创建自签名证书中所述

准备工作

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

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

所需的角色

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

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

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

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

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

配置工作负载身份联合

本部分介绍如何配置 Workload Identity Federation 和信任库。您只需为每个信任库执行这些步骤一次。然后，您可以为多个工作负载以及多个 Google Cloud 项目使用相同的工作负载身份池和提供方。

创建和配置信任库

本部分介绍了如何创建信任库 YAML 配置文件和自签名 CA 证书。

生成密钥和签名证书

本部分使用 openssl 命令创建根证书和中间证书。

如果您已有证书，则可以跳过此步骤，然后继续执行设置证书格式。

如需生成具有有效 keyUsage 和 extendedKeyUsage 字段的根证书和已签名中间证书，请执行以下操作：

1. 创建示例 example.cnf 文件，其中包含创建有效签名证书所需的最低配置。您可以修改此文件，以在这些证书上设置其他字段。

   cat > example.cnf << EOF
   [req]
   distinguished_name = empty_distinguished_name
   [empty_distinguished_name]
   # Kept empty to allow setting via -subj command line arg.
   [ca_exts]
   basicConstraints=critical,CA:TRUE
   keyUsage=keyCertSign
   extendedKeyUsage=clientAuth
   EOF
   

2. 创建根证书：

   openssl req -x509 \
       -new -sha256 -newkey rsa:2048 -nodes \
       -days 3650 -subj '/CN=root' \
       -config example.cnf \
       -extensions ca_exts \
       -keyout root.key -out root.cert
   

3. 为中间证书创建签名请求：

   openssl req \
       -new -sha256 -newkey rsa:2048 -nodes \
       -subj '/CN=int' \
       -config example.cnf \
       -extensions ca_exts \
       -keyout int.key -out int.req
   

4. 创建中间证书：

   openssl x509 -req \
       -CAkey root.key -CA root.cert \
       -set_serial 1 \
       -days 3650 \
       -extfile example.cnf \
       -extensions ca_exts \
       -in int.req -out int.cert
   

设置证书格式

如需在信任存储区中包括新证书或现有证书，请将证书格式设置为单行，并将它们存储在环境变量中，以便证书可以读入 YAML 文件中。证书必须采用 PEM 格式。如需设置证书格式并将其存储在环境变量中，请执行以下操作：

1. 将根证书另存为单行字符串：

   export ROOT_CERT=$(cat root.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')
   

2. 将中间证书另存为单行字符串：

   export INTERMEDIATE_CERT=$(cat int.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')
   

创建信任库 YAML 文件

在本部分中，您将创建一个受信任证书存储区 YAML 文件，其中包含信任锚和中间 CA。

如需创建受信任证书存储区 YAML 文件，请运行以下命令。此文件包含您在设置证书格式中创建的环境变量的证书内容。如需添加其他信任锚点，请在 trustStore 下添加其他 trustAnchors 条目。如需添加其他中间 CA 证书，请在 trustStore 下添加其他 intermediateCas 条目。

cat << EOF > trust_store.yaml
trustStore:
  trustAnchors:
  - pemCertificate: "${ROOT_CERT}"
  intermediateCas:
  - pemCertificate: "${INTERMEDIATE_CERT}"
EOF

定义特性映射和条件

客户端 X.509 证书可以包含多个属性。您必须选择要用作主题标识符的属性，方法是将 Google Cloud 中的 google.subject 映射到证书中的属性。例如，如果证书中的属性是主题公用名，则映射如下所示：google.subject=assertion.subject.dn.cn

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

您的属性映射可以使用客户端证书中的属性，包括：

• serialNumberHex：序列号
• subject.dn.cn：主题通用名称
• subject.dn.o：主题组织名称
• subject.dn.ou：主题组织部门
• issuer.dn.cn：颁发机构的通用名称
• issuer.dn.o：发卡组织名称
• issuer.dn.ou：发卡组织部门
• san.dns：主题备用名称的第一个 DNS 名称
• san.uri：主题备用名称的第一个 URI

您必须将其中一个属性映射到 google.subject，以唯一标识主题。为了防止欺骗威胁，请选择具有不可更改的唯一值的属性。默认情况下，google.subject 标识符会设置为客户端证书主题常用名称 assertion.subject.dn.cn。

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

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

例如，以下条件会限制对包含 SPIFFE ID spiffe://example/path 的客户端证书的访问权限：

assertion.san.uri=="spiffe://example/path"

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

1. 如需创建新的工作负载身份池，请执行以下命令：

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

   请替换以下内容：

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

2. 如需添加 X.509 工作负载身份池提供方，请运行以下命令：

   gcloud iam workload-identity-pools providers create-x509 PROVIDER_ID \
       --location=global \
       --workload-identity-pool="POOL_ID" \
       --trust-store-config-path="TRUST_STORE_CONFIG" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS" \
       --billing-project="ALLOWLISTED_PROJECT"
   

   替换以下内容：

   • PROVIDER_ID：您选择的唯一工作负载身份池提供方 ID。
   • POOL_ID：您之前创建的工作负载身份池 ID。
   • TRUST_STORE_CONFIG：信任库 YAML 文件。
   • MAPPINGS：您在本指南前面部分中创建的以英文逗号分隔的属性映射列表。 如果您未指定 google.subject，则默认映射将为 google.subject=assertion.subject.dn.cn
   • CONDITIONS：您在本指南前面部分中创建的可选属性条件。如果您没有特性条件，请移除该参数。
   • ALLOWLISTED_PROJECT：项目 ID。

对工作负载进行身份验证

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

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

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

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

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

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

下载或创建凭据配置

Cloud 客户端库和 gcloud CLI 可以自动获取外部凭据，并使用这些凭据来模拟服务账号。为了让库和工具完成此过程，您必须提供凭据配置文件。此文件定义以下内容：

• 从何处获取外部凭据
• 要使用的工作负载身份池和提供商
• 需要模拟的服务账号

此外，对于 X.509 证书联合，还需要提供证书配置文件。此文件包含 X.509 客户端证书和私钥文件的路径。

如需创建凭据和证书配置文件，请执行以下操作：

gcloud iam workload-identity-pools create-cred-config
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --credential-cert-path CLIENT_CERT_PATH \
    --credential-cert-private-key-path CLIENT_KEY_PATH \
    --output-file=FILEPATH.json

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --credential-cert-path CLIENT_CERT_PATH \
    --credential-cert-private-key-path CLIENT_KEY_PATH \
    --output-file=FILEPATH.json

使用凭据配置访问 Google Cloud

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

1. 初始化环境变量 GOOGLE_APPLICATION_CREDENTIALS 并将其指向凭据配置文件：

   Bash

     export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
     

   其中，FILEPATH 是凭据配置文件的相对路径。

   PowerShell

     $env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
     

   其中，FILEPATH 是凭据配置文件的相对路径。

2. 确保客户端库可以找到证书配置文件。证书配置文件应存储在默认的 Google Cloud CLI 位置：

   • Linux 和 macOS：~/.config/gcloud/certificate_config.json

   • Windows：%APPDATA%\gcloud\certificate_config.json

   或由 GOOGLE_API_CERTIFICATE_CONFIG 环境变量指向。

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

  go list -m cloud.google.com/go/auth
  go list -m cloud.google.com/api

  pip show google-auth

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

使用纯文本请求获取访问 Google Cloud 的访问令牌

如需获取访问令牌，请执行以下操作：

1. 使用 curl 通过 mTLS 和客户端证书执行令牌交换：

   curl --key CLIENT_CERT_KEY \
   --cert CLIENT_CERT \
   --request POST 'https://sts.mtls.googleapis.com/v1/token' \
   --header "Content-Type: application/json" \
   --data-raw '{
       "subject_token_type": "urn:ietf:params:oauth:token-type:mtls",
       "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
       "audience": "WORKLOAD_IDENTITY_POOL_URI",
       "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
       "scope": "https://www.googleapis.com/auth/cloud-platform",
   }'
   

   替换以下内容：

   • CLIENT_CERT_KEY：客户端证书私钥
   • CLIENT_CERT：客户端证书

   • WORKLOAD_IDENTITY_POOL_URI：工作负载身份池提供方的网址，格式如下：

     //iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

2. 使用上一步中生成的载体访问令牌访问 Google Cloud 资源，例如：

   curl -X GET 'https://storage.googleapis.com/my_object' -H "Authorization: Bearer $ACCESS_TOKEN"
   

配额和限制

下表列出了配额和限制。

后续步骤

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