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

为 AWS 配置工作负载身份联合

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

  • AWS 出站身份联合: 通过 GetWebIdentityToken 获取 AWS STS 签发的 OIDC JWT,并用它换取短期 OpenAI 访问令牌。
  • Amazon EKS: 使用 Amazon EKS 的投射服务账户令牌换取短期 OpenAI 访问令牌。

OpenAI 支持 AWS 通过出站身份联合签发的 OIDC JWT,也支持 Amazon EKS 签发的 Kubernetes 投射服务账户令牌。OpenAI 不支持将使用 SigV4 签名的请求或 AWS STS 临时访问密钥凭证用作工作负载身份联合的主体令牌。

AWS 出站身份联合

通过 AWS 出站身份联合,AWS 主体可以向 AWS STS 请求已签名的 OIDC JWT,并向外部服务出示该令牌。在 OpenAI 工作负载身份联合中,AWS 签发的 JWT 用作主体令牌。OpenAI 会先验证该令牌,再签发 OpenAI 访问令牌。

配置 AWS 出站身份联合

为用于签发令牌的 AWS 账户启用出站身份联合。有关配置步骤,请参阅 AWS 的出站身份联合入门指南。

aws iam enable-outbound-web-identity-federation

记下 AWS 返回的账户专属签发者 URL。配置 OpenAI 工作负载身份提供方时,将该 URL 填入签发者字段。它必须与 AWS 签发的令牌中的 iss 声明一致。

STS 全局端点不提供 AWS STS GetWebIdentityToken API。请将 AWS CLI 或 SDK 配置为使用区域 STS 端点。

授予工作负载调用 sts:GetWebIdentityToken 的权限。在 IAM 中限制受众和令牌的最长有效期,使 AWS 主体只能生成供 OpenAI 使用的令牌。以下示例允许生成受众为 https://api.openai.com/v1、有效期最长为 300 秒的令牌:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:GetWebIdentityToken",
      "Resource": "*",
      "Condition": {
        "ForAllValues:StringEquals": {
          "sts:IdentityTokenAudience": "https://api.openai.com/v1"
        },
        "NumericLessThanEquals": {
          "sts:DurationSeconds": 300
        }
      }
    }
  ]
}

向 AWS 请求 OIDC 令牌时,指定的受众必须与您将在 OpenAI 工作负载身份提供方中配置的受众一致。请使用 ES384,除非您的环境需要兼容 RS256。

TOKEN=$(aws sts get-web-identity-token \
  --audience "https://api.openai.com/v1" \
  --signing-algorithm ES384 \
  --duration-seconds 300 \
  --tags Key=environment,Value=production \
         Key=workload,Value=batch-ingest \
  --query "WebIdentityToken" \
  --output text)
export TOKEN

验证 AWS 签发的令牌

配置工作负载身份联合之前,将 AWS 签发的令牌导出为环境变量 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 载荷,不验证令牌签名。对于生产环境的令牌,请使用本地解码器,避免将令牌粘贴到第三方工具中。

AWS 签发的 OIDC 令牌解码后类似于以下示例:

{
  "iss": "https://abc123-def456-ghi789-jkl012.tokens.sts.global.api.aws",
  "aud": "https://api.openai.com/v1",
  "sub": "arn:aws:iam::123456789012:role/OpenAIWifRole",
  "iat": 1716235422,
  "exp": 1716235722,
  "jti": "jwt-id-example",
  "https://sts.amazonaws.com/": {
    "aws_account": "123456789012",
    "source_region": "us-west-2",
    "org_id": "o-exampleorgid",
    "principal_tags": {
      "environment": "production"
    },
    "request_tags": {
      "environment": "production",
      "workload": "batch-ingest"
    }
  }
}

AWS 签发的令牌不一定包含所有 AWS 专有声明。https://sts.amazonaws.com/ 下有哪些声明,取决于发起调用的主体、会话上下文和请求标签。

核对您计划在 OpenAI 中配置的声明:

  • iss:必须与 OpenAI 工作负载身份提供方中配置的 AWS 账户专属签发者 URL 一致。
  • aud:必须与调用 GetWebIdentityToken 时指定的受众以及 OpenAI 工作负载身份提供方中配置的受众一致。
  • sub:其值为请求令牌的 IAM 主体的 ARN。建议精确匹配角色的完整 ARN。
  • AWS 专有声明:匹配账户、组织、主体标签或请求标签的值之前,请以解码后的令牌为准核对这些值。

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

配置工作负载身份联合

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

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

配置工作负载身份提供方

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

  2. 设置签发者和受众。 将 OIDC 签发者 URL 设为启用出站身份联合时返回的 AWS 账户专属签发者 URL。该值必须与令牌中的 iss 声明一致。将受众设为传给 GetWebIdentityToken 的受众。本例中,该值为 https://api.openai.com/v1。

  3. 使用 AWS OIDC 发现机制。 保持使用上传的 JWKS 验证令牌选项关闭。OpenAI 使用 AWS 签发者的 OIDC 发现元数据和 JWKS 验证 AWS 签发的令牌。

  4. 仅当映射需要派生属性时,才添加属性转换。 直接匹配原始令牌时,可以使用顶层标量声明,例如 sub、aud 和 iss。AWS 专有声明嵌套在 https://sts.amazonaws.com/ 命名空间下,因此要在映射中使用这些声明,需要先用 CEL 方括号语法创建派生属性。例如,将属性名称填为 aws_environment,表达式填为 assertion["https://sts.amazonaws.com/"]["principal_tags"]["environment"],即可根据上面解码后的令牌示例创建 openai.aws_environment。使用嵌套声明之前,请先在示例令牌中核对其路径。如果转换表达式无法求值,映射解析就会失败。对于本身以 openai. 开头的原始令牌声明,除非配置了相应的转换,否则以 openai. 开头的映射键会忽略这些声明。

配置服务账户映射

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

  2. 匹配 AWS 主体。 将键设为 sub,将值设为解码后的令牌中的 IAM 主体 ARN,例如 arn:aws:iam::123456789012:role/OpenAIWifRole。对于 AWS 出站身份联合,精确匹配 sub 声明可实现最严格的隔离。

  3. 根据需要添加其他声明匹配条件。 您可以匹配任意可用的标量声明或转换后的属性。例如,如果需要进一步限定信任边界,可以使用从 AWS 账户、组织、主体标签或请求标签声明派生的属性。

  4. 选择 OpenAI 目标。 将项目设为目标服务账户所属的 OpenAI 项目。将服务账户设为 AWS 工作负载可以使用的 OpenAI 服务账户,例如 aws-outbound-prod-openai-wif。

  5. 根据需要缩小 API 权限范围。 选择适当的权限,例如 api.model.request 和 api.vector_store.read,以进一步限制通过此映射签发的访问令牌的权限。将权限留空,就不会额外施加工作负载身份联合特有的作用域限制。使用该令牌的请求仍以映射到的服务账户身份获得授权。

在代码中使用令牌

配置 OpenAI SDK 客户端,使其向 AWS STS 请求由 AWS 签发的 OIDC 令牌,并用该令牌换取 OpenAI 签发的访问令牌。

将 OPENAI_WIF_AUDIENCE 设为 OpenAI 工作负载身份提供方中配置的受众。主体令牌提供方使用该受众调用 AWS STS 的 GetWebIdentityToken,并将 AWS 签发的 JWT 作为主体令牌返回。随后,OpenAI SDK 使用该令牌换取 OpenAI 签发的访问令牌。

使用 AWS 签发的 OIDC 令牌进行身份验证
import { GetWebIdentityTokenCommand, STSClient } from "@aws-sdk/client-sts";
import OpenAI from "openai";

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

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

const sts = new STSClient({ region: awsRegion });

function awsOutboundWebIdentityTokenProvider() {
  return {
    tokenType: "jwt" as const,
    getToken: async () => {
      const response = await sts.send(
        new GetWebIdentityTokenCommand({
          Audience: [wifAudience],
          SigningAlgorithm: "ES384",
          DurationSeconds: 300,
        })
      );

      if (!response.WebIdentityToken) {
        throw new Error("AWS STS did not return a web identity token.");
      }

      return response.WebIdentityToken;
    },
  };
}

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

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

console.log(response.output_text);

AWS 最佳实践

  • 为每个工作负载分配专用的 AWS 身份。对于使用 AWS 出站身份联合的工作负载,分别使用独立的 IAM 角色。对于 EKS 工作负载,分别使用独立的 Kubernetes 服务账户。
  • 为访问 OpenAI 配置专用受众。AWS 签发的令牌或 EKS 投射令牌中的受众值必须与 OpenAI 工作负载身份提供方中配置的受众值一致。
  • 在满足工作负载需要的前提下,尽量缩短令牌有效期。对于 AWS 出站身份联合,请使用 sts:DurationSeconds 等 IAM 条件。对于 EKS,请为投射令牌设置合适的有效期。
  • 优先精确匹配主体。对于 AWS 出站令牌,请匹配完整的 IAM 主体 ARN。对于 EKS 令牌,请匹配完整的 Kubernetes 服务账户主体标识。
  • 使用稳定的属性限定映射范围。如果使用账户、组织、命名空间或转换后的属性能够缩小访问范围,同时避免建立过于宽泛的信任规则,请使用这些属性。
  • 每次交换令牌时都重新获取令牌。按需请求 AWS 出站令牌,并从挂载的文件路径读取 EKS 投射令牌,以便在令牌轮换后自动使用新令牌。
  • 仅授予工作负载所需的权限。在映射上设置权限,进一步限制目标 OpenAI 服务账户授予的访问范围。