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

Workload-Identitätsföderation für Oracle Cloud Infrastructure konfigurieren

Du kannst Oracle Cloud Infrastructure (OCI) als Identitätsanbieter für Workloads nutzen, indem du ein Zugriffstoken von Oracle Identity Cloud Service (IDCS) gegen ein kurzlebiges OpenAI-Zugriffstoken eintauschst. Ein OCI Instance Principal signiert die Anfrage zum Token-Austausch, die an eine Identitätsdomäne im selben Mandanten geht. OpenAI prüft das ausgestellte Token und berechtigt den OCI-Workload, im Namen des zugeordneten OpenAI-Dienstkontos zu handeln.

Für dieses Setup brauchst du weder einen OpenAI-API-Schlüssel noch eine benutzerdefinierte OAuth-Ressourcenanwendung in Oracle. Du musst auch keinen dynamischen Gruppen Zugriff auf eine benutzerdefinierte Anwendung gewähren.

OCI-Workload einrichten

Führe deinen Workload auf einer OCI Compute-Instanz mit einem Instance Principal aus. Prüfe bei Oracle Kubernetes Engine (OKE), welche Identität die Anfrage signiert. Der standardmäßige Signierer für Instance Principals weist in der Regel die Identität des Worker-Nodes aus, nicht die eines einzelnen Kubernetes-Pods.

Der Signierer bezieht seine Anmeldedaten vom Metadatendienst für OCI-Instanzen. Prüfe mit folgendem Befehl, ob der Workload den linklokalen Metadaten-Endpunkt erreichen kann.

curl --fail --silent \
  --header "Authorization: Bearer Oracle" \
  http://169.254.169.254/opc/v2/instance/id

Der Workload muss außerdem ausgehende HTTPS-Anfragen an die Identitätsdomäne seines Mandanten senden können. Für den Metadaten-Endpunkt selbst brauchst du weder ein NAT-Gateway noch eine Internetverbindung.

Identitätstoken von Oracle anfordern

Signiere mit InstancePrincipalsSecurityTokenSigner aus dem OCI Python SDK die folgende OAuth-Anfrage zum Token-Austausch an deine Identitätsdomäne.

POST https://<identity-domain>/oauth2/v1/token
Content-Type: application/x-www-form-urlencoded;charset=utf-8

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
scope=urn:opc:idm:__myscopes__
requested_token_type=urn:ietf:params:oauth:token-type:access_token

Der Scope urn:opc:idm:__myscopes__ nutzt die bestehenden Berechtigungen des Instance Principals. Verwende das zurückgegebene IDCS-Zugriffstoken als Subject-Token für die Workload-Identitätsföderation mit OpenAI. Ersetze die Audience des Oracle-Tokens nicht durch https://api.openai.com/v1. Konfiguriere den Identitätsanbieter in OpenAI mit einer Audience, die im ausgestellten Oracle-Token steht.

Token prüfen

Setze TOKEN auf ein Zugriffstoken, das dein OCI-Workload tatsächlich erzeugt hat. Sieh dir dann die Claims mit dem vorhandenen lokalen JWT-Decoder an.

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

Der Decoder zeigt den Inhalt des Tokens an, ohne die Signatur zu prüfen. Behandle die Tokens vertraulich. Schreibe sie nicht in Logs und füge keine Tokens aus dem Produktivbetrieb in JWT-Decoder von Drittanbietern ein.

Ein dekodiertes Oracle-Zugriffstoken kann die folgenden Claims enthalten.

{
  "iss": "https://identity.oraclecloud.com/",
  "aud": [
    "https://idcs-example.us-phoenix-1.identity.oraclecloud.com",
    "https://idcs-example.identity.oraclecloud.com"
  ],
  "sub_type": "instance",
  "ipst_instance": "ocid1.instance.oc1.phx.<instance-id>",
  "ipst_compartment": "ocid1.compartment.oc1..<compartment-id>",
  "domain_id": "ocid1.domain.oc1..<domain-id>",
  "ca_ocid": "ocid1.tenancy.oc1..<tenancy-id>",
  "tenant": "idcs-example",
  "exp": 1782369434,
  "iat": 1782365834
}

Maßgeblich ist das Token, das deine eigene Identitätsdomäne ausstellt. Übernimm für die Konfiguration den exakten Wert von iss und einen der aud-Werte aus diesem Token. Verwende für die Autorisierung eines Workloads vorzugsweise die unveränderlichen Claims ipst_instance, ipst_compartment, domain_id und ca_ocid.

Workload-Identitätsföderation einrichten

Erstelle für deine Oracle-Identitätsdomäne einen Identitätsanbieter für Workloads. Lege anschließend eine Zuordnung fest, die der OCI-Instanz oder den Instanzen eines Compartments Zugriff auf das gewünschte OpenAI-Dienstkonto gewährt.

Identitätsanbieter für Workloads einrichten

  1. Erstelle den Identitätsanbieter für Workloads. Gib unter Name einen eindeutigen Wert ein, etwa oracle-cloud-prod. Beschreibe unter Beschreibung den vertrauenswürdigen Workload, etwa mit Production OCI instance principal.

  2. Lege Aussteller und Audience fest. Gib unter URL des OIDC-Ausstellers den Wert des Claims iss aus dem Token ein, etwa https://identity.oraclecloud.com/. Wähle für Audience einen der aud-Werte aus demselben Token.

  3. Konfiguriere die mandantenspezifische OIDC-Discovery, sofern verfügbar. Wenn die Option Benutzerdefinierte URL für die OIDC-Discovery verwenden unter Erweitert angezeigt wird, aktiviere sie. Gib unter Benutzerdefinierte OIDC-Discovery-URL die URL der Identitätsdomäne deines Mandanten ein, etwa https://idcs-example.identity.oraclecloud.com. OpenAI ruft https://idcs-example.identity.oraclecloud.com/.well-known/openid-configuration ab und lädt dann über den jwks_uri aus dem Discovery-Dokument die öffentlichen Signaturschlüssel des Mandanten. Falls die Option für die benutzerdefinierte Discovery fehlt, aktiviere Hochgeladenes JWKS zur Token-Prüfung verwenden und lade stattdessen das öffentliche JWKS von https://<identity-domain>/admin/v1/SigningCert/jwk hoch.

  4. Füge Attributtransformationen nur hinzu, wenn du abgeleitete Attribute brauchst. Du kannst Oracle-Claims wie ipst_instance, ipst_compartment, domain_id und ca_ocid direkt in den Zuordnungsbedingungen für Dienstkonten verwenden. Wenn du ausdrücklich ein Instanzattribut ableiten möchtest, gib instance als Attribut und assertion.ipst_instance als Ausdruck ein. So erstellst du openai.instance.

Die Oracle-Referenz zur OpenID Connect Discovery erklärt, warum die benutzerdefinierte Discovery wichtig ist. Das Discovery-Dokument kann https://identity.oraclecloud.com/ als globalen Aussteller angeben, obwohl der Token-Endpunkt und der jwks_uri auf der Identitätsdomäne des Mandanten liegen. Behalte unter URL des OIDC-Ausstellers den globalen Aussteller bei und gib unter Benutzerdefinierte OIDC-Discovery-URL die Domäne des Mandanten an.

Wenn deine Identitätsdomäne die Discovery-Metadaten unter der URL des Token-Ausstellers veröffentlicht, lass die benutzerdefinierte Discovery deaktiviert und verwende die standardmäßige OIDC-Discovery. Wenn OpenAI das Discovery-Dokument des Mandanten oder den Endpunkt für die Signaturschlüssel nicht erreichen kann, deaktiviere die benutzerdefinierte Discovery. Aktiviere Hochgeladenes JWKS zur Token-Prüfung verwenden und lade das öffentliche JWKS des Mandanten von https://<identity-domain>/admin/v1/SigningCert/jwk hoch. Die benutzerdefinierte Discovery und ein hochgeladenes JWKS lassen sich nicht gleichzeitig verwenden. Aktualisiere die hochgeladenen Schlüssel, wenn Oracle seine Signaturzertifikate austauscht.

Dienstkontozuordnung einrichten

  1. Erstelle eine Dienstkontozuordnung. Gib unter Name einen eindeutigen Wert ein, etwa oracle-instance-prod. Ergänze eine Beschreibung, aus der hervorgeht, welchem OCI-Workload du vertraust.

  2. Wähle die OCI-Identität, die den Zugriff möglichst eng und dauerhaft eingrenzt. Soll nur eine Instanz Zugriff erhalten, gib unter Schlüssel ipst_instance und unter Wert die exakte Instanz-OCID aus dem geprüften Token ein. Sollen Instanzen eines Compartments Zugriff erhalten, gib unter Schlüssel ipst_compartment und unter Wert die exakte Compartment-OCID ein.

  3. Beschränke den Zugriff bei Bedarf auf eine Domäne oder einen Mandanten. Füge weitere Zuordnungszeilen für domain_id oder ca_ocid hinzu, um den Zugriff auf Workloads einer bestimmten Oracle-Identitätsdomäne oder eines bestimmten Mandanten zu begrenzen. Füge sub_type mit dem Wert instance hinzu, wenn das Token diesen Claim enthält und du einen Instance Principal voraussetzen möchtest. Das Token muss die Bedingungen aller Zuordnungszeilen erfüllen.

  4. Wähle das Ziel in OpenAI aus. Wähle unter Projekt das Projekt aus, zu dem das Dienstkonto gehört. Wähle anschließend das Dienstkonto aus, das der vertrauenswürdige OCI-Workload verwenden darf.

  5. Schränke die API-Berechtigungen bei Bedarf ein. Wähle nur die Berechtigungen aus, die der Workload benötigt. Mit der Zuordnung kannst du die Berechtigungen des ausgewählten Dienstkontos einschränken, aber keine Berechtigungen erteilen, die das Dienstkonto selbst nicht hat.

Ein OKE-Workload, der den standardmäßigen Signierer für Instance Principals verwendet, übernimmt die Identität des Worker-Nodes. Eine Zuordnung auf Instanzebene gewährt dem gesamten Node Zugriff, nicht nur einem einzelnen Pod. Wenn du Pods auf demselben Worker-Node voneinander isolieren musst, verwende eine spezifischere Workload-Identität, die OCI unterstützt.

Token im Code verwenden

Installiere die Python-Pakete für OpenAI, OCI und Requests.

pip install openai oci requests

Installiere für Ruby die Gems für OpenAI und OCI.

gem install openai oci

Setze OCI_IDENTITY_DOMAIN_URL auf die Basis-URL der Identitätsdomäne, die zum selben Mandanten gehört wie der Workload. Setze OPENAI_IDENTITY_PROVIDER_ID und OPENAI_SERVICE_ACCOUNT_ID auf die jeweiligen IDs aus der Konfiguration deines OpenAI-Identitätsanbieters und deiner Dienstkontozuordnung.

Im folgenden Beispiel signiert der OCI Instance Principal die Anfrage zum Token-Austausch bei Oracle. Das OpenAI SDK erhält das zurückgegebene IDCS-Zugriffstoken und tauscht es bei Bedarf gegen ein kurzlebiges OpenAI-Zugriffstoken ein.

Mit einem OCI Instance Principal authentifizieren
import os

import oci
import requests
from openai import OpenAI
from openai.auth import SubjectTokenProvider


def oracle_instance_principal_token_provider(
    identity_domain_url: str,
) -> SubjectTokenProvider:
    def get_token() -> str:
        signer = oci.auth.signers.InstancePrincipalsSecurityTokenSigner()
        response = requests.post(
            f"{identity_domain_url.rstrip('/')}/oauth2/v1/token",
            data={
                "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
                "scope": "urn:opc:idm:__myscopes__",
                "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
            },
            headers={
                "Content-Type": "application/x-www-form-urlencoded;charset=utf-8",
            },
            auth=signer,
            timeout=30,
        )
        response.raise_for_status()

        token = response.json().get("access_token")
        if not isinstance(token, str) or not token:
            raise RuntimeError("Oracle IDCS did not return an access token.")

        return token

    return {"token_type": "jwt", "get_token": get_token}


client = OpenAI(
    workload_identity={
        "identity_provider_id": os.environ["OPENAI_IDENTITY_PROVIDER_ID"],
        "service_account_id": os.environ["OPENAI_SERVICE_ACCOUNT_ID"],
        "provider": oracle_instance_principal_token_provider(
            os.environ["OCI_IDENTITY_DOMAIN_URL"]
        ),
    },
)

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Say hello from Oracle Cloud Infrastructure workload identity federation.",
)

print(response.output_text)

Der Anbieter des Subject-Tokens fordert ein neues Oracle-Token an, wenn das OpenAI SDK den Identitätsnachweis des Workloads erneuern muss. Gib weder das Oracle-Subject-Token noch das daraus hervorgehende OpenAI-Zugriffstoken aus und speichere keines der beiden Tokens dauerhaft.

Sicherheitsempfehlungen für OCI

  • Ordne mit ipst_instance eine einzelne Instanz zu, wenn nur ein Workload Zugriff haben soll.
  • Verwende ipst_compartment nur, wenn die Zuordnung für jede berechtigte Instanz im betreffenden Compartment gelten soll.
  • Füge domain_id oder ca_ocid hinzu, um den Zugriff auf die jeweilige Identitätsdomäne bzw. den jeweiligen Mandanten zu beschränken.
  • Verwende für jede Anwendung und jede Umgebung ein eigenes OpenAI-Dienstkonto.
  • Prüfe, ob ein OKE-Token einen Worker-Node identifiziert, bevor du dich auf die Isolation einzelner Pods verlässt.
  • Verwende die Audience aus dem ausgestellten Oracle-Token. Setze keine OpenAI-spezifische Audience voraus.
  • Wenn deine Identitätsdomäne keine OIDC-Discovery nutzen kann, ersetze die hochgeladenen öffentlichen Schlüssel, sobald Oracle seine Signaturschlüssel austauscht.