Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Identitätsföderation für AWS-Workloads konfigurieren

Du kannst AWS in zwei Szenarien als Identitätsanbieter für Workloads verwenden:

  • Ausgehende Identitätsföderation von AWS: Tausche ein OIDC-JWT, das AWS STS über GetWebIdentityToken ausstellt, gegen ein kurzlebiges OpenAI-Zugriffstoken ein.
  • Amazon EKS: Tausche ein projiziertes Token eines Amazon-EKS-Dienstkontos gegen ein kurzlebiges OpenAI-Zugriffstoken ein.

OpenAI unterstützt OIDC-JWTs, die AWS über die ausgehende Identitätsföderation ausstellt, sowie projizierte Kubernetes-Dienstkonto-Tokens, die Amazon EKS ausstellt. Mit SigV4 signierte Anfragen und temporäre Zugangsdaten mit Zugriffsschlüsseln von AWS STS unterstützt OpenAI nicht als Subject-Tokens für die Identitätsföderation von Workloads.

Ausgehende Identitätsföderation von AWS

Mit der ausgehenden Identitätsföderation von AWS kann ein AWS-Prinzipal ein signiertes OIDC-JWT von AWS STS anfordern und es einem externen Dienst vorlegen. Bei der Identitätsföderation für Workloads prüft OpenAI das von AWS ausgestellte JWT als Subject-Token, bevor OpenAI ein Zugriffstoken ausstellt.

Ausgehende Identitätsföderation von AWS einrichten

Aktiviere die ausgehende Identitätsföderation für das AWS-Konto, das die Tokens ausstellen soll. Einzelheiten findest du im AWS-Leitfaden zum Einstieg in die ausgehende Identitätsföderation.

aws iam enable-outbound-web-identity-federation

Notiere die kontospezifische Aussteller-URL, die AWS zurückgibt. Diese URL gibst du beim Identitätsanbieter für Workloads in OpenAI als Aussteller an. Sie muss mit dem Claim iss in den von AWS ausgestellten Tokens übereinstimmen.

Die AWS-STS-API GetWebIdentityToken ist am globalen STS-Endpunkt nicht verfügbar. Stelle in der AWS CLI oder im SDK einen regionalen STS-Endpunkt ein.

Erteile dem Workload die Berechtigung, sts:GetWebIdentityToken aufzurufen. Beschränke in IAM die Audience und die maximale Gültigkeitsdauer, damit der AWS-Prinzipal nur Tokens für OpenAI ausstellen lassen kann. Dieses Beispiel erlaubt Tokens für die Audience https://api.openai.com/v1 mit einer Gültigkeitsdauer von höchstens 300 Sekunden:

{
  "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
        }
      }
    }
  ]
}

Fordere von AWS ein OIDC-Token mit derselben Audience an, die du später beim Identitätsanbieter für Workloads in OpenAI angibst. Verwende ES384, sofern deine Umgebung keine Kompatibilität mit RS256 erfordert.

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

Von AWS ausgestelltes Token prüfen

Bevor du die Identitätsföderation für Workloads konfigurierst, exportiere das von AWS ausgestellte Token als TOKEN. Führe dann dieses Skript lokal aus, um die Claims zu prüfen:

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);

Dieser Befehl dekodiert die JWT-Payload, ohne die Signatur des Tokens zu prüfen. Dekodiere Tokens aus dem Produktivbetrieb lokal und vermeide es, sie in Tools von Drittanbietern einzufügen.

Ein dekodiertes OIDC-Token von AWS sieht etwa so aus:

{
  "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"
    }
  }
}

Nicht jedes von AWS ausgestellte Token enthält alle AWS-spezifischen Claims. Welche Claims unter https://sts.amazonaws.com/ stehen, hängt vom aufrufenden Prinzipal, vom Sitzungskontext und von den Tags der Anfrage ab.

Prüfe die Claims, die du in OpenAI konfigurieren möchtest:

  • iss: Muss mit der Aussteller-URL des AWS-Kontos übereinstimmen, die du beim Identitätsanbieter für Workloads in OpenAI angegeben hast.
  • aud: Muss mit der Audience für GetWebIdentityToken und der Audience des Identitätsanbieters für Workloads in OpenAI übereinstimmen.
  • sub: Enthält den ARN des IAM-Prinzipals, der das Token angefordert hat. Prüfe möglichst auf exakte Übereinstimmung mit dem Rollen-ARN.
  • AWS-spezifische Claims: Entnimm die maßgeblichen Werte dem dekodierten Token, bevor du Bedingungen für Konto, Organisation, Prinzipal-Tags oder Anfrage-Tags festlegst.

Vergleiche anhand der dekodierten Payload das erhaltene Token mit dem Aussteller, der Audience und den Zuordnungswerten, die du in OpenAI konfiguriert hast. Die meisten Konfigurationsfehler erkennst du bereits vor dem Token-Austausch an den Claims iss, aud und sub.

Identitätsföderation für Workloads einrichten

Erstelle in OpenAI einen Identitätsanbieter für Workloads mit dem Aussteller deines AWS-Kontos. Füge dann eine Dienstkontozuordnung hinzu, die stabile Claims im von AWS ausgestellten Token abgleicht.

Konfiguriere zuerst den Identitätsanbieter für Workloads und erstelle anschließend die Dienstkontozuordnung.

Identitätsanbieter für Workloads einrichten

  1. Erstelle den Identitätsanbieter für Workloads. Gib unter Name einen eindeutigen Wert ein, etwa aws-outbound-prod. Wähle eine Beschreibung, an der das Administrationsteam den Anbieter erkennen kann, etwa Production AWS outbound identity federation workloads.

  2. Lege Aussteller und Audience fest. Gib unter OIDC-Aussteller-URL die kontospezifische Aussteller-URL ein, die AWS beim Aktivieren der ausgehenden Identitätsföderation zurückgegeben hat. Der Wert muss mit dem Claim iss des Tokens übereinstimmen. Gib unter Audience denselben Wert ein, den du an GetWebIdentityToken übergibst. In diesem Beispiel ist das https://api.openai.com/v1.

  3. Nutze OIDC Discovery von AWS. Lass die Option Hochgeladenes JWKS zur Token-Prüfung verwenden deaktiviert. OpenAI prüft das von AWS ausgestellte Token anhand der OIDC-Discovery-Metadaten und des JWKS des AWS-Ausstellers.

  4. Füge Attributtransformationen nur hinzu, wenn du für die Zuordnung abgeleitete Attribute brauchst. Skalare Claims auf der obersten Ebene des Tokens, etwa sub, aud und iss, kannst du direkt abgleichen. Die AWS-spezifischen Claims stehen verschachtelt im Namensraum https://sts.amazonaws.com/. Erstelle daher mit der CEL-Klammernotation abgeleitete Attribute, bevor du diese Claims in Zuordnungen verwendest. Gib beispielsweise aws_environment mit dem Ausdruck assertion["https://sts.amazonaws.com/"]["principal_tags"]["environment"] ein, um aus dem oben dekodierten Beispieltoken openai.aws_environment zu erzeugen. Prüfe den Pfad zum verschachtelten Claim vorab anhand eines Beispieltokens. Lässt sich eine Transformation nicht auswerten, schlägt die Auflösung der Zuordnung fehl. Beginnt ein Claim im ursprünglichen Token bereits mit openai., wird er für Zuordnungsschlüssel mit dem Präfix openai. nur berücksichtigt, wenn eine passende Transformation konfiguriert ist.

Dienstkontozuordnung einrichten

  1. Erstelle eine Dienstkontozuordnung. Gib unter Name einen Wert ein, der innerhalb des Identitätsanbieters für Workloads eindeutig ist, etwa aws-role-openai-wif. Gib unter Beschreibung an, welcher Workload die Zuordnung verwenden kann, etwa Production AWS role for OpenAI API workload.

  2. Prüfe auf Übereinstimmung mit dem AWS-Prinzipal. Gib unter Schlüssel den Wert sub ein und unter Wert den ARN des IAM-Prinzipals aus dem dekodierten Token, etwa arn:aws:iam::123456789012:role/OpenAIWifRole. Die exakte Übereinstimmung mit dem Claim sub bietet bei der ausgehenden Identitätsföderation von AWS die stärkste Isolation.

  3. Lege bei Bedarf weitere Bedingungen für Claims fest. Du kannst jeden verfügbaren skalaren Claim und jedes transformierte Attribut abgleichen. Wenn du weitere Vertrauensgrenzen brauchst, verwende beispielsweise Attribute, die du aus AWS-Claims für Konto, Organisation, Prinzipal-Tags oder Anfrage-Tags abgeleitet hast.

  4. Wähle das Ziel in OpenAI. Wähle unter Projekt das OpenAI-Projekt aus, zu dem das Zieldienstkonto gehört. Wähle unter Dienstkonto das OpenAI-Dienstkonto aus, das der AWS-Workload verwenden darf, etwa aws-outbound-prod-openai-wif.

  5. Schränke bei Bedarf die API-Berechtigungen ein. Wähle passende Berechtigungen wie api.model.request und api.vector_store.read aus, um den Zugriff der über diese Zuordnung ausgestellten Tokens weiter einzuschränken. Lass das Feld leer, wenn du den Berechtigungsumfang nicht zusätzlich für die Identitätsföderation einschränken möchtest. Für das Token gelten weiterhin die Berechtigungen des zugeordneten Dienstkontos.

Token im Code verwenden

Konfiguriere deinen OpenAI-SDK-Client so, dass er ein OIDC-Token von AWS STS anfordert und gegen ein von OpenAI ausgestelltes Zugriffstoken eintauscht.

Setze OPENAI_WIF_AUDIENCE auf dieselbe Audience, die du beim Identitätsanbieter für Workloads in OpenAI angegeben hast. Der Anbieter für Subject-Tokens ruft die AWS-STS-API GetWebIdentityToken mit dieser Audience auf und gibt das von AWS ausgestellte JWT als Subject-Token zurück. Das OpenAI SDK tauscht es gegen ein von OpenAI ausgestelltes Zugriffstoken ein.

Mit einem von AWS ausgestellten OIDC-Token authentifizieren
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);

Empfehlungen für AWS

  • Verwende für jeden Workload eine eigene AWS-Identität. Nutze für die ausgehende Identitätsföderation von AWS separate IAM-Rollen und für EKS-Workloads separate Kubernetes-Dienstkonten.
  • Lege für den Zugriff auf OpenAI eine eigene Audience fest. Verwende im von AWS ausgestellten Token oder im projizierten EKS-Token dieselbe Audience wie in der Konfiguration des Identitätsanbieters für Workloads in OpenAI.
  • Halte die Gültigkeitsdauer der Tokens möglichst kurz. Verwende für die ausgehende Identitätsföderation von AWS IAM-Bedingungen wie sts:DurationSeconds. Lege in EKS eine geeignete Gültigkeitsdauer für das projizierte Token fest.
  • Prüfe möglichst auf exakte Übereinstimmung mit dem Subject. Vergleiche bei Tokens aus der ausgehenden Identitätsföderation von AWS den vollständigen ARN des IAM-Prinzipals und bei EKS-Tokens das vollständige Subject des Kubernetes-Dienstkontos.
  • Begrenze Zuordnungen anhand stabiler Merkmale. Verwende Konto, Organisation, Namespace oder transformierte Attribute, wenn du damit den Zugriff einschränken kannst, ohne weitreichende Vertrauensregeln einzuführen.
  • Lade Tokens bei jedem Austausch neu. Fordere Tokens für die ausgehende Identitätsföderation von AWS bei Bedarf an und lies projizierte EKS-Tokens aus der eingebundenen Datei. So werden erneuerte Tokens automatisch verwendet.
  • Erteile nur die Berechtigungen, die der Workload benötigt. Mit Berechtigungen auf Zuordnungsebene kannst du den Zugriff weiter einschränken, den das OpenAI-Zieldienstkonto gewährt.