如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

为 Google Cloud 配置工作负载身份联合

在以下两种场景中,您都可以将 Google Cloud 用作工作负载身份提供方:

  • Google 工作负载身份:使用由 Google 签名并颁发给已关联的 Google 服务账号的 OIDC 令牌,换取短期 OpenAI 访问令牌。
  • Google Kubernetes Engine:使用投射到工作负载中的 GKE 服务账号令牌换取短期 OpenAI 访问令牌。

Google 工作负载身份

Google Cloud 工作负载可以向 Google 元数据服务器请求已签名的 OIDC 身份令牌,无需存储长期有效的服务账号密钥。在 OpenAI 工作负载身份联合流程中,Google 身份令牌用作主体令牌。OpenAI 会先验证该令牌,再颁发 OpenAI 访问令牌。此流程适用于 Compute Engine、Cloud Run、使用已关联的 Google 服务账号的 GKE 工作负载,以及其他提供元数据服务器身份端点的 Google 托管运行环境。

设置 Google 工作负载身份

为需要调用 OpenAI API 的工作负载创建 Google 服务账号。有关完整设置流程,请参阅 Google 的创建服务账号指南。

例如,您可以使用 Google Cloud CLI 创建服务账号:

gcloud iam service-accounts create openai-wif \
  --description="Service account for OpenAI workload identity federation" \
  --display-name="OpenAI workload identity federation"

创建 Compute Engine 虚拟机时关联该服务账号,或将该账号关联到运行应用的 Google Cloud 资源。该资源必须能够在运行时访问 Google 元数据服务器。有关虚拟机的设置详情,请参阅 Google 指南,了解如何创建使用用户管理的服务账号的虚拟机。

请勿为此流程创建或下载服务账号密钥。工作负载会使用已关联的服务账号向元数据服务器请求短期 OIDC 令牌。

获取 Google 身份令牌

在已关联服务账号的 Google Cloud 资源上,向元数据服务器请求 OIDC 身份令牌,并指定已配置的受众。此令牌用作主体令牌,OpenAI 会验证它并换发 OpenAI 访问令牌。

AUDIENCE="https://api.openai.com/v1"

TOKEN=$(curl -sS -G -H "Metadata-Flavor: Google" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity" \
  --data-urlencode "audience=${AUDIENCE}")
export TOKEN

元数据服务器会返回由 Google 签名的 JWT。有关元数据服务器身份端点的更多信息,请参阅 Google 的验证虚拟机身份指南。

验证令牌

配置工作负载身份联合之前,请将 Google 身份令牌导出为环境变量 TOKEN,然后在本地运行以下脚本,检查令牌中的声明:

const parts = process.env.TOKEN?.split(".") ?? [];
if (parts.length !== 3) {
  throw new Error("Expected a compact JWT with three segments");
}
if (!/^[A-Za-z0-9_-]+$/.test(parts[1]) || parts[1].length % 4 === 1) {
  throw new Error("JWT payload is not valid Base64URL");
}

const bytes = Buffer.from(parts[1], "base64url");
if (bytes.toString("base64url") !== parts[1]) {
  throw new Error("JWT payload is not valid Base64URL");
}
const decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
const claims = JSON.parse(decoded);
if (claims === null || Array.isArray(claims) || typeof claims !== "object") {
  throw new Error("JWT payload is not a JSON object");
}
console.log(decoded);

此命令仅解码 JWT 的载荷,不验证令牌签名。请使用本地解码工具处理生产环境的令牌,避免将这些令牌粘贴到第三方工具中。

Google 元数据服务器颁发的身份令牌解码后类似于以下示例:

{
  "iss": "https://accounts.google.com",
  "aud": "https://api.openai.com/v1",
  "azp": "110123456789012345678",
  "sub": "110123456789012345678",
  "email": "openai-wif@my-project.iam.gserviceaccount.com",
  "email_verified": true,
  "iat": 1716235422,
  "exp": 1716239022
}

根据解码后的载荷,核对收到的令牌是否与 OpenAI 中配置的颁发方、受众和映射值一致。在交换令牌之前,检查 iss、aud、email 和 sub 声明即可发现大多数配置问题。

配置工作负载身份联合

在 OpenAI 中为 Google 颁发的身份令牌创建工作负载身份提供方,然后添加服务账号映射,用于匹配令牌中取值稳定的声明。

先配置工作负载身份提供方,再创建服务账号映射。

设置工作负载身份提供方

  1. 创建工作负载身份提供方。将名称设为唯一值,例如 google-workload-identity-prod。填写描述,例如 Production Google Cloud workloads,以便管理员识别该提供方。

  2. 设置颁发方和受众。将 OIDC 颁发方 URL 设为 https://accounts.google.com。将受众设为工作负载向 Google 元数据服务器请求令牌时指定的自定义受众,例如 https://api.openai.com/v1。此值必须与令牌的 aud 声明一致。

  3. 使用 Google 的 OIDC 发现机制。保持使用上传的 JWKS 验证令牌选项关闭。OpenAI 会使用 Google 的 OIDC 发现元数据和 JWKS 验证由 Google 签名的身份令牌。

  4. 如果需要派生映射属性,请添加属性转换。例如,输入 subject 并将表达式设为 assertion.sub,即可根据主体声明生成 openai.subject。控制台会自动添加 openai. 前缀。对于原本就以 openai. 开头的令牌声明,只有配置了对应的转换,才能将其用于以 openai. 开头的映射键。

设置服务账号映射

  1. 创建服务账号映射。将名称设为在该工作负载身份提供方内唯一的值,例如 compute-openai-wif。填写描述,例如 Production Compute Engine OpenAI API workload,说明哪些工作负载可以使用此映射。

  2. 匹配 Google 服务账号中取值稳定的声明。为每个必须匹配的声明添加一行,填写键和值。使用 sub 作为绑定身份的主要依据,因为它的值稳定且唯一。为方便阅读,您还可以同时匹配 email。

  3. 选择 OpenAI 目标账号。将项目设为目标服务账号所属的 OpenAI 项目。将服务账号设为 Google Cloud 工作负载可以使用的 OpenAI 服务账号,例如 google-workload-identity-prod-openai-wif。

  4. 根据需要缩小 API 权限范围。选择适当的权限,例如 api.model.request 和 api.vector_store.read,以进一步限制通过此映射签发的访问令牌的权限。如果将权限留空,工作负载身份联合(WIF)就不会额外限制授权范围,令牌仍按映射到的服务账号所拥有的权限授权访问。

在代码中使用令牌

配置 OpenAI SDK 客户端,使其向元数据服务器请求 Google 身份令牌,并用该令牌换取 OpenAI 颁发的访问令牌。

将 OPENAI_WIF_AUDIENCE 设为工作负载身份提供方配置中指定的自定义受众。SDK 会为该受众请求 Google 身份令牌,用它换取 OpenAI 颁发的访问令牌,然后使用 OpenAI 令牌对 API 请求进行身份验证。

使用 Google 元数据服务器颁发的身份令牌进行身份验证
import OpenAI from "openai";

const metadataEndpoint =
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity";

const identityProviderId = process.env.OPENAI_IDENTITY_PROVIDER_ID;
const serviceAccountId = process.env.OPENAI_SERVICE_ACCOUNT_ID;
const audience = process.env.OPENAI_WIF_AUDIENCE;

if (!identityProviderId || !serviceAccountId || !audience) {
  throw new Error(
    "Set OPENAI_IDENTITY_PROVIDER_ID, OPENAI_SERVICE_ACCOUNT_ID, and OPENAI_WIF_AUDIENCE"
  );
}

function googleMetadataIdentityTokenProvider(audience: string) {
  return {
    tokenType: "jwt" as const,
    getToken: async () => {
      const url = new URL(metadataEndpoint);
      url.searchParams.set("audience", audience);
      url.searchParams.set("format", "full");

      const response = await fetch(url, {
        headers: { "Metadata-Flavor": "Google" },
      });

      if (!response.ok) {
        throw new Error(
          `Google metadata token request failed with status ${response.status}.`
        );
      }

      const token = (await response.text()).trim();
      if (!token) {
        throw new Error(
          "Google metadata server did not return an identity token."
        );
      }

      return token;
    },
  };
}

const client = new OpenAI({
  workloadIdentity: {
    identityProviderId,
    serviceAccountId,
    provider: googleMetadataIdentityTokenProvider(audience),
  },
});

const response = await client.responses.create({
  model: "gpt-6.1-terra",
  input: "Say hello from Google Cloud workload identity federation.",
});

console.log(response.output_text);

Google Cloud 最佳实践

  • 为每个工作负载分配专用的 Google 服务账号。避免在不相关的服务或环境之间共用服务账号。
  • 使用工作负载身份流程替代长期有效的服务账号密钥。对于能够使用元数据服务器身份令牌或 GKE 工作负载身份的工作负载,避免分发和轮换 JSON 密钥文件。
  • 在实际可行的范围内,将每个身份限定到尽可能小的工作负载范围。为各个应用使用独立的服务账号,有助于在审计时区分各应用的操作,并按最小权限原则授予访问权限。
  • 谨慎使用基于属性的映射。尽可能优先使用服务账号主体声明等稳定标识符,避免依赖可能变化的元数据。
  • 将生产项目与非生产项目分开。使用独立项目可降低意外共用权限的风险,并简化审计。
  • 仅授予必需的 IAM 权限。将 Google 身份的权限限制在工作负载所需的范围内。
  • 监控服务账号的使用情况。意外的令牌交换可能意味着配置发生了漂移,或工作负载已遭入侵。