For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navigation principale

Configuration de la fédération d’identités de charge de travail pour Oracle Cloud Infrastructure

Utilisez Oracle Cloud Infrastructure (OCI) comme fournisseur d’identités de charge de travail en échangeant un token d’accès Oracle Identity Cloud Service (IDCS) contre un token d’accès OpenAI de courte durée. Un principal d’instance OCI signe une demande d’échange de tokens adressée à un domaine d’identité de la même location. OpenAI valide le token obtenu et autorise la charge de travail OCI à agir en tant que compte de service OpenAI associé par mappage.

Pour Codex, suivez cette page afin d’obtenir et d’inspecter le token Oracle. Ensuite, configurez l’identité de charge de travail de Codex pour écrire ce token dans un fichier et indiquer son emplacement à Codex. Le mappage de compte de service et les exemples de SDK présentés sur cette page s’appliquent à l’API OpenAI.

Cette configuration ne nécessite ni clé API OpenAI, ni application de ressource OAuth Oracle personnalisée, ni droits accordés à des groupes dynamiques sur une application personnalisée.

Configurez la charge de travail OCI

Exécutez votre charge de travail sur une instance OCI Compute dotée d’un principal d’instance. Pour Oracle Kubernetes Engine (OKE), vérifiez quelle identité signe la requête : le signataire standard utilisant le principal d’instance identifie généralement le nœud de travail, et non un pod Kubernetes individuel.

Le signataire obtient les informations d’authentification auprès du service de métadonnées d’instance OCI. Vérifiez que la charge de travail peut accéder au point de terminaison de métadonnées à l’adresse locale au lien :

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

La charge de travail doit également pouvoir envoyer des requêtes HTTPS sortantes au domaine d’identité de sa location. Le point de terminaison de métadonnées lui-même ne nécessite ni passerelle NAT ni connexion Internet.

Demandez un token d’identité Oracle

Utilisez InstancePrincipalsSecurityTokenSigner du SDK Python OCI pour signer une demande d’échange de tokens OAuth adressée à votre domaine d’identité :

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

La portée urn:opc:idm:__myscopes__ utilise l’autorisation existante du principal d’instance. Utilisez le token d’accès IDCS renvoyé comme token de sujet pour la fédération d’identités de charge de travail OpenAI. Ne remplacez pas l’audience du token Oracle par https://api.openai.com/v1 ; configurez le fournisseur OpenAI avec une audience présente dans le token Oracle réel.

Vérifiez le token

Définissez TOKEN sur un token d’accès généré par la charge de travail OCI réelle, puis utilisez le décodeur JWT local existant pour inspecter ses revendications :

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

Le décodeur inspecte le token sans vérifier sa signature. Traitez les tokens bruts comme des données sensibles, ne les consignez pas dans les journaux et ne collez pas de tokens de production dans des décodeurs JWT tiers.

Un token d’accès Oracle décodé peut contenir les revendications suivantes :

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

Utilisez le token émis par votre propre domaine d’identité comme source de vérité. Configurez la valeur exacte de iss et l’une des valeurs aud du token. Privilégiez les revendications immuables ipst_instance, ipst_compartment, domain_id et ca_ocid pour autoriser une charge de travail.

Configurez la fédération d’identités de charge de travail

Créez un fournisseur d’identités de charge de travail pour votre domaine d’identité Oracle, puis ajoutez un mappage pour l’instance ou le compartiment OCI autorisé à utiliser le compte de service OpenAI cible.

Configurez le fournisseur d’identités de charge de travail

  1. Créez le fournisseur d’identités de charge de travail. Définissez Nom sur une valeur unique, par exemple oracle-cloud-prod. Renseignez le champ Description, par exemple avec Production OCI instance principal, pour identifier la charge de travail de confiance.

  2. Définissez l’émetteur et l’audience. Définissez URL de l’émetteur OIDC sur la revendication iss du token, par exemple https://identity.oraclecloud.com/. Définissez Audience sur l’une des valeurs aud de ce même token.

  3. Configurez la découverte OIDC propre au locataire lorsqu’elle est disponible. Si l’option Utiliser une URL personnalisée pour la découverte OIDC apparaît sous Avancé, activez-la. Définissez URL de découverte OIDC personnalisée sur le domaine d’identité propre à votre locataire, par exemple https://idcs-example.identity.oraclecloud.com. OpenAI récupère https://idcs-example.identity.oraclecloud.com/.well-known/openid-configuration, puis utilise la valeur jwks_uri du document de découverte pour récupérer les clés publiques de signature du locataire. Si l’option de découverte personnalisée n’apparaît pas, activez Utiliser un JWKS importé pour la vérification des tokens et importez à la place le JWKS public disponible à l’adresse https://<identity-domain>/admin/v1/SigningCert/jwk.

  4. N’ajoutez des transformations d’attributs que si vous avez besoin d’attributs dérivés. Vous pouvez utiliser les revendications Oracle brutes telles que ipst_instance, ipst_compartment, domain_id et ca_ocid directement dans les assertions de mappage de compte de service. Pour dériver explicitement un attribut d’instance, saisissez instance avec l’expression assertion.ipst_instance afin de créer openai.instance.

La référence Oracle sur la découverte OpenID Connect explique l’importance de la découverte personnalisée : le document de découverte peut déclarer l’émetteur global https://identity.oraclecloud.com/ tout en publiant le point de terminaison des tokens et jwks_uri sur le domaine d’identité propre au locataire. Conservez l’émetteur global dans URL de l’émetteur OIDC et utilisez le domaine du locataire pour URL de découverte OIDC personnalisée.

Si votre domaine d’identité publie les métadonnées de découverte à l’adresse de l’émetteur du token, laissez la découverte personnalisée désactivée et utilisez la découverte OIDC standard. Si OpenAI ne peut pas accéder au document de découverte du locataire ou au point de terminaison des clés de signature, désactivez la découverte personnalisée, activez Utiliser un JWKS importé pour la vérification des tokens et importez le JWKS public du locataire disponible à l’adresse https://<identity-domain>/admin/v1/SigningCert/jwk. La découverte personnalisée et le JWKS importé ne peuvent pas être activés simultanément. Mettez à jour les clés importées lorsque Oracle renouvelle ses certificats de signature.

Configurez le mappage de compte de service

  1. Créez un mappage de compte de service. Définissez Nom sur une valeur unique, par exemple oracle-instance-prod, et ajoutez une description qui identifie la charge de travail OCI de confiance.

  2. Ciblez l’identité OCI stable au périmètre le plus restreint. Pour accorder l’accès à une instance, définissez Clé sur ipst_instance et Valeur sur l’OCID exact de l’instance figurant dans le token vérifié. Pour accorder l’accès aux instances d’un compartiment, définissez Clé sur ipst_compartment et Valeur sur l’OCID exact du compartiment.

  3. Ajoutez des restrictions de domaine et de location si nécessaire. Ajoutez des lignes de mappage pour domain_id ou ca_ocid afin de limiter la charge de travail à un domaine d’identité ou à une location Oracle en particulier. Ajoutez sub_type avec la valeur instance lorsque le token contient cette revendication et que vous souhaitez exiger un principal d’instance. Toutes les lignes de mappage doivent correspondre.

  4. Choisissez la cible OpenAI. Définissez Projet sur le projet auquel appartient le compte de service, puis sélectionnez le Compte de service que la charge de travail OCI de confiance peut utiliser.

  5. Restreignez les autorisations de l’API si nécessaire. Sélectionnez uniquement les Autorisations nécessaires à la charge de travail. Les autorisations du mappage peuvent restreindre celles du compte de service sélectionné, mais ne peuvent pas lui accorder des autorisations qu’il ne possède pas déjà.

Une charge de travail OKE qui utilise le signataire standard avec principal d’instance hérite de l’identité du nœud de travail. Un mappage au niveau de l’instance autorise ce nœud, et non un seul pod. Utilisez une identité de charge de travail OCI plus précise et prise en charge lorsque vous avez besoin d’isoler des pods qui partagent un nœud de travail.

Utilisez le token dans le code

Installez les packages Python OpenAI, OCI et Requests :

pip install openai oci requests

Pour Ruby, installez les gems OpenAI et OCI :

gem install openai oci

Définissez OCI_IDENTITY_DOMAIN_URL sur l’URL de base du domaine d’identité situé dans la même location que la charge de travail. Définissez OPENAI_IDENTITY_PROVIDER_ID et OPENAI_SERVICE_ACCOUNT_ID sur les identifiants issus de votre fournisseur OpenAI et de votre mappage de compte de service.

L’exemple suivant signe une demande d’échange de tokens Oracle avec le principal d’instance OCI, renvoie le token d’accès IDCS au SDK OpenAI et laisse le SDK l’échanger contre un token d’accès OpenAI de courte durée lorsque cela est nécessaire :

Authentifiez-vous avec un principal d’instance OCI
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)

Le fournisseur de tokens de sujet demande un nouveau token Oracle lorsque le SDK OpenAI doit renouveler les informations d’authentification de l’identité de charge de travail. N’affichez jamais le token de sujet Oracle ni le token d’accès OpenAI obtenu, et ne les stockez jamais de manière persistante.

Recommandations de sécurité OCI

  • Mappez une seule instance avec ipst_instance lorsqu’une seule charge de travail doit avoir accès.
  • N’utilisez ipst_compartment que lorsque toutes les instances éligibles de ce compartiment doivent partager le mappage.
  • Ajoutez domain_id ou ca_ocid pour faire respecter les restrictions de domaine d’identité et de location.
  • Utilisez un compte de service OpenAI distinct pour chaque application et chaque environnement.
  • Vérifiez si un token OKE représente un nœud de travail avant de vous appuyer sur une isolation au niveau des pods.
  • Utilisez l’audience présente dans le token Oracle émis au lieu de supposer qu’il possède une audience propre à OpenAI.
  • Si votre domaine d’identité ne peut pas utiliser la découverte OIDC, renouvelez les clés publiques importées lorsqu’Oracle renouvelle ses clés de signature.