For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
メインナビゲーション

AWS 向けワークロード ID フェデレーションの構成

次のいずれかのシナリオで、AWS をワークロード ID プロバイダーとして使用できます。

  • AWS アウトバウンド ID フェデレーション: GetWebIdentityToken で取得した AWS STS 発行の OIDC JWT を、有効期間の短い OpenAI アクセストークンと交換します。
  • Amazon EKS: 投影された Amazon EKS サービスアカウントトークンを、有効期間の短い OpenAI アクセストークンと交換します。

Codex で使用する場合は、このページの手順で AWS トークンを取得し、内容を確認します。その後、Codex のワークロード ID を構成して、トークンをファイルに書き込み、Codex がそのファイルを参照するようにします。このページのサービスアカウントマッピングと SDK の例は、OpenAI API を対象としています。

OpenAI は、アウトバウンド ID フェデレーションによって AWS が発行する OIDC JWT と、Amazon EKS が発行する Kubernetes の投影されたサービスアカウントトークンをサポートしています。SigV4 署名付きリクエストや AWS STS の一時アクセスキー認証情報は、ワークロード ID フェデレーションのサブジェクトトークンとしてサポートしていません。

AWS アウトバウンド ID フェデレーション

AWS アウトバウンド ID フェデレーションでは、AWS プリンシパルが AWS STS に署名付き OIDC JWT をリクエストし、そのトークンを外部サービスに提示できます。OpenAI のワークロード ID フェデレーションでは、AWS が発行した JWT がサブジェクトトークンとなり、OpenAI はこれを検証してから OpenAI アクセストークンを発行します。

AWS アウトバウンド ID フェデレーションのセットアップ

トークンを発行する AWS アカウントで、アウトバウンド ID フェデレーションを有効にします。セットアップの詳細は、AWS のアウトバウンド ID フェデレーションの開始ガイドを参照してください。

aws iam enable-outbound-web-identity-federation

AWS から返されたアカウント固有の発行者 URL を記録します。この値を OpenAI のワークロード ID プロバイダーの発行者として構成します。この値は、AWS が発行するトークンの iss クレームと一致する必要があります。

AWS STS の GetWebIdentityToken API は、STS のグローバルエンドポイントでは利用できません。 リージョン別の STS エンドポイントを使用するように AWS CLI または SDK を構成してください。

ワークロードに sts:GetWebIdentityToken を呼び出す権限を付与します。AWS プリンシパルが OpenAI 向けのトークンのみを発行できるよう、IAM で対象者とトークンの最大有効期間を制限します。この例では、対象者が 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
        }
      }
    }
  ]
}

OpenAI のワークロード ID プロバイダーに構成するものと同じ対象者を指定して、AWS 発行の OIDC トークンをリクエストします。環境で RS256 との互換性が必要な場合を除き、ES384 を使用してください。

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 発行トークンの検証

ワークロード ID フェデレーションを構成する前に、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 のワークロード ID プロバイダーに構成した AWS アカウント固有の発行者 URL と一致する必要があります。
  • audGetWebIdentityToken の対象者、および OpenAI のワークロード ID プロバイダーの対象者と一致する必要があります。
  • sub:トークンをリクエストした IAM プリンシパルの ARN を示します。ロール ARN の完全一致による照合を推奨します。
  • AWS 固有のクレーム:アカウント、組織、プリンシパルタグ、リクエストタグの値を照合する前に、デコードしたトークンを正しい情報源として確認してください。

デコードしたペイロードを使用して、受け取ったトークンを OpenAI に構成した発行者、対象者、マッピングの値と比較します。構成上の問題の多くは、トークンを交換する前に issaudsub のクレームを確認することで見つけられます。

ワークロード ID フェデレーションのセットアップ

AWS アカウントの発行者に対応するワークロード ID プロバイダーを OpenAI に作成し、AWS 発行のトークンに含まれる安定したクレームと照合するサービスアカウントマッピングを追加します。

まずワークロード ID プロバイダーを構成し、その後にサービスアカウントマッピングを作成します。

ワークロード ID プロバイダーのセットアップ

  1. ワークロード ID プロバイダーを作成します。 名前 には、aws-outbound-prod などの一意の値を設定します。管理者がプロバイダーを識別しやすいように、 説明には Production AWS outbound identity federation workloads などを入力します。

  2. 発行者と対象者を設定します。 OIDC 発行者 URL には、アウトバウンド ID フェデレーションを有効にした際に返された AWS アカウント固有の発行者 URL を設定します。この値は、トークンの iss クレームと一致する必要があります。 対象者 には、GetWebIdentityToken に渡すものと同じ対象者を設定します。この例では https://api.openai.com/v1 です。

  3. AWS の OIDC ディスカバリーを使用します。 アップロードした JWKS をトークン検証に使用 は無効のままにします。OpenAI は、AWS 発行者の OIDC ディスカバリーメタデータと JWKS を使用して、AWS 発行のトークンを検証します。

  4. 派生したマッピング属性が必要な場合にのみ、属性変換を追加します。 トークンをそのまま照合する場合は、subaudiss などのトップレベルのスカラークレームを使用できます。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 など、ワークロード ID プロバイダー内で一意の値を設定します。 説明には Production AWS role for OpenAI API workload などを入力し、このマッピングを使用できるワークロードを説明します。

  2. AWS プリンシパルを照合します。 キー には sub を設定し、 には arn:aws:iam::123456789012:role/OpenAIWifRole など、デコードしたトークンに含まれる IAM プリンシパルの ARN を設定します。sub クレームの完全一致による照合は、AWS アウトバウンド ID フェデレーションで最も強力な分離を実現します。

  3. 必要に応じて、クレームの照合条件を追加します。 利用可能な任意のスカラークレームや変換済み属性を照合できます。たとえば、追加の信頼境界が必要な場合は、AWS アカウント、組織、プリンシパルタグ、リクエストタグのクレームから派生させた変換済み属性を使用します。

  4. OpenAI 側の対象を選択します。 プロジェクト には、対象のサービスアカウントを所有する OpenAI プロジェクトを設定します。 サービスアカウント には、aws-outbound-prod-openai-wif など、AWS ワークロードが使用できる OpenAI サービスアカウントを設定します。

  5. 必要に応じて API 権限を制限します。 api.model.requestapi.vector_store.read などの適切な 権限 を選択し、このマッピングから発行されるアクセストークンの権限をさらに絞り込みます。WIF 固有のスコープ制限を追加しない場合は、権限を空欄のままにします。その場合も、トークンにはマッピング先のサービスアカウントの権限が適用されます。

コードでのトークンの使用

AWS STS に AWS 発行の OIDC トークンをリクエストし、OpenAI 発行のアクセストークンと交換するように OpenAI SDK クライアントを構成します。

OPENAI_WIF_AUDIENCE には、OpenAI のワークロード ID プロバイダーに構成したものと同じ対象者を設定します。サブジェクトトークンプロバイダーは、その対象者を指定して 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",
    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 ID を使用します。AWS アウトバウンド ID フェデレーションには個別の IAM ロールを、EKS ワークロードには個別の Kubernetes サービスアカウントを使用します。
  • OpenAI へのアクセス専用のオーディエンスを設定します。AWS が発行するトークンまたは EKS の射影されたトークンと、OpenAI のワークロード ID プロバイダーの設定で、同じオーディエンス値を使用します。
  • トークンの有効期間は、実用上無理のない範囲で短くします。AWS アウトバウンド ID フェデレーションでは sts:DurationSeconds などの IAM 条件を使用し、EKS では射影されたトークンに適切な有効期限を設定します。
  • サブジェクトの完全一致による照合を推奨します。AWS アウトバウンドトークンでは IAM プリンシパル ARN 全体を、EKS トークンでは Kubernetes サービスアカウントのサブジェクト全体を照合します。
  • マッピングの適用範囲は、安定した境界に基づいて設定します。信頼ルールの範囲を広げずにアクセスを制限できる場合は、アカウント、組織、名前空間、または変換済み属性を使用します。
  • 交換時にはトークンを再読み込みします。AWS アウトバウンドトークンは必要なときにリクエストし、EKS の射影されたトークンはマウントされたファイルパスから読み取ることで、ローテーション後のトークンを自動的に取得できるようにします。
  • ワークロードに必要な権限のみを付与します。マッピング単位の権限を使用して、対象の OpenAI サービスアカウントが付与するアクセスをさらに制限します。