在 Python 中为 GCP 工作负载身份池生成凭据配置

本文旨在指导用户如何在 Python 中程序化地为 Google Cloud Platform (GCP) 工作负载身份池生成凭据配置，特别是针对与外部身份提供商（如 AWS）进行联合的场景。我们将探讨如何利用 `google.auth.external_account` 包来构建和使用这些凭据，以替代 `gcloud` 命令行工具的 `create-cred-config` 功能，并提供相应的代码示例和注意事项。

理解 GCP 工作负载身份联合与凭据配置

Google Cloud Platform 的工作负载身份联合（Workload Identity Federation）允许外部身份（如来自 AWS、Azure、或本地 OIDC 提供商的身份）模拟 GCP 服务账号，从而访问 GCP 资源，而无需下载和管理服务账号密钥。这显著提升了安全性，并简化了跨云或混合云环境的身份管理。

通常，您可以使用 gcloud iam workload-identity-pools create-cred-config 命令行工具来生成一个 JSON 格式的凭据配置文件。这个文件描述了如何从外部身份提供商获取令牌，并将其交换为 GCP 访问令牌，以便您的应用程序可以使用。例如，针对 AWS 的命令如下：

gcloud iam workload-identity-pools create-cred-config \
projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$IDENTITY_POOL/providers/$IDENTITY_POOL_PROVIDER \
--service-account=$SA_EMAIL \
--output-file=$ClientConfig \
--aws

然而，在 Python 应用程序中，尤其是当您希望动态生成或管理这些凭据时，直接通过 SDK 调用来实现这一功能的需求就变得尤为重要。

立即学习“Python免费学习笔记（深入）”；

英特尔AI工具

英特尔AI与机器学习解决方案

下载

Python 中的解决方案：google.auth.external_account

GCP 官方客户端库中并没有直接与 gcloud create-cred-config 命令完全对应的 API 调用来生成一个外部账号凭据配置文件。但是，google.auth.external_account 包提供了一个强大的机制，允许您在 Python 代码中直接构造和使用这些外部账号凭据，从而实现相同的目标：通过工作负载身份联合获取 GCP 资源的访问权限。

google.auth.external_account.ExternalAccountCredentials 类是此解决方案的核心。它允许您定义外部身份提供商的详细信息，以及如何将其令牌交换为 GCP 访问令牌。

关键参数解析

要构造 ExternalAccountCredentials 对象，您需要提供以下关键信息，这些信息与 gcloud 命令的参数相对应：

1. audience: 目标受众字符串，格式为 //iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$IDENTITY_POOL/providers/$IDENTITY_POOL_PROVIDER。它指明了您的外部身份将向哪个 GCP 工作负载身份池提供商进行身份验证。
2. service_account_impersonation_url: 服务账号模拟的 URL，格式为 https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/$SERVICE_ACCOUNT_EMAIL:generateAccessToken。这指示了外部身份在通过工作负载身份池验证后，将模拟哪个 GCP 服务账号。
3. credential_source: 凭据源配置。这是一个字典，描述了如何从外部身份提供商获取初始的身份令牌。对于 AWS，通常包含 "environment_id": "aws"，google.auth.external_account 会自动尝试从标准 AWS 环境变量（如 AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN）或 EC2 实例元数据中发现凭据。
4. subject_token_type: 主题令牌类型。对于 AWS，这是 "urn:ietf:params:oauth:token-type:aws-federated-token"。
5. token_url: GCP 安全令牌服务 (STS) 的 URL，用于交换外部令牌以获取 GCP 访问令牌。通常是 "https://sts.googleapis.com/v1/token"。

示例：在 Python 中使用 AWS 工作负载身份联合

以下代码示例展示了如何使用 google.auth.external_account 在 Python 中为 AWS 工作负载身份联合创建和使用凭据。

import os
import json
from google.auth.external_account import ExternalAccountCredentials
from google.cloud import storage # 以 Google Cloud Storage 客户端为例

# --- 1. 配置参数 (请替换为您的实际值) ---
# GCP 项目编号
PROJECT_NUMBER = "YOUR_GCP_PROJECT_NUMBER"
# 工作负载身份池 ID
IDENTITY_POOL = "YOUR_IDENTITY_POOL_ID"
# 工作负载身份池提供商 ID
IDENTITY_POOL_PROVIDER = "YOUR_IDENTITY_POOL_PROVIDER_ID"
# 要模拟的 GCP 服务账号的电子邮件地址
SERVICE_ACCOUNT_EMAIL = "your-service-account@your-gcp-project.iam.gserviceaccount.com"
# 外部凭据配置文件的输出路径 (如果需要生成文件)
OUTPUT_CONFIG_FILE = "gcp_aws_cred_config.json"

# --- 2. 构造 `audience` 和 `service_account_impersonation_url` ---
# audience 字符串，指示向哪个工作负载身份池提供商进行认证
audience = (
    f"//iam.googleapis.com/projects/{PROJECT_NUMBER}/locations/global/"
    f"workloadIdentityPools/{IDENTITY_POOL}/providers/{IDENTITY_POOL_PROVIDER}"
)

# 服务账号模拟 URL
service_account_impersonation_url = (
    f"https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/"
    f"{SERVICE_ACCOUNT_EMAIL}:generateAccessToken"
)

# --- 3. 定义 `credential_source` 和其他相关参数 ---
# 对于 AWS，credential_source 字典描述了如何获取 AWS 临时凭据。
# google.auth.external_account 会自动检测 AWS 环境。
aws_credential_source_config = {
    "environment_id": "aws",
    # 如果在 EC2 实例上运行，这些 URL 用于获取实例元数据中的凭据。
    # 如果通过环境变量提供 AWS 凭据，这些字段并非严格必需，但包含它们
    # 可以使配置更完整，与 gcloud 生成的文件结构一致。
    # "url": "http://169.254.169.254/latest/meta-data/iam/security-credentials/",
    # "region_url": "http://169.254.169.254/latest/meta-data/placement/region"
}

# 主题令牌类型，对于 AWS 联合身份是固定的
subject_token_type = "urn:ietf:params:oauth:token-type:aws-federated-token"

# GCP STS 令牌交换 URL
token_url = "https://sts.googleapis.com/v1/token"

# --- 4. 创建 ExternalAccountCredentials 对象 ---
try:
    credentials = ExternalAccountCredentials(
        token_url=token_url,
        credential_source=aws_credential_source_config,
        audience=audience,
        service_account_impersonation_url=service_account_impersonation_url,
        subject_token_type=subject_token_type
    )

    print("成功创建 ExternalAccountCredentials 对象。")

    # --- 5. 使用凭据访问 GCP 服务 (以 Google Cloud Storage 为例) ---
    # 确保您的运行环境已配置有效的 AWS 凭据 (例如，通过环境变量或 AWS CLI 配置)。
    storage_client = storage.Client(credentials=credentials, project=PROJECT_NUMBER)
    print("\n尝试列出 GCP Cloud Storage 存储桶...")
    buckets = list(storage_client.list_buckets())
    print("成功通过工作负载身份联合认证并列出存储桶：")
    for bucket in buckets:
        print(f"- {bucket.name}")

except Exception as e:
    print(f"在使用凭据时发生错误: {e}")
    print("请确保您的 AWS 凭据已正确配置（例如