如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .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 在解析 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-5.6-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 服務帳戶授予的存取權限。