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

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

Utilisez Oracle Cloud Infrastructure (OCI) comme fournisseur d’identités de charges de travail en échangeant un jeton d’accès Oracle Identity Cloud Service (IDCS) contre un jeton d’accès OpenAI de courte durée. Un principal d’instance OCI signe une demande d’échange de jeton adressée à un domaine d’identité de la même location OCI. OpenAI valide le jeton obtenu et autorise la charge de travail OCI à agir au nom du compte de service OpenAI auquel elle est associée.

Cette configuration ne nécessite ni clé API OpenAI, ni application de ressources OAuth Oracle personnalisée, ni autorisations accordées à des groupes dynamiques pour accéder à une application personnalisée.

Configuration de la charge de travail OCI

Exécutez votre charge de travail sur une instance OCI Compute dotée d’un principal d’instance. Si vous utilisez Oracle Kubernetes Engine (OKE), vérifiez quelle identité signe la demande. Le mécanisme de signature standard du principal d’instance identifie généralement le nœud de travail plutôt qu’un pod Kubernetes en particulier.

Le mécanisme de signature obtient ses informations d’identification auprès du service de métadonnées d’instance OCI. Vérifiez que la charge de travail peut joindre le point de terminaison des métadonnées à son adresse de liaison locale :

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 OCI. L’accès au point de terminaison des métadonnées lui-même ne nécessite ni passerelle NAT ni connexion Internet.

Demande d’un jeton d’identité Oracle

Utilisez InstancePrincipalsSecurityTokenSigner du SDK OCI pour Python afin de signer une demande d’échange de jeton 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 les autorisations dont dispose déjà le principal d’instance. Utilisez le jeton d’accès IDCS obtenu comme jeton du sujet pour la fédération d’identités de charges de travail OpenAI. Ne remplacez pas l’audience du jeton Oracle par https://api.openai.com/v1. Configurez le fournisseur OpenAI avec une audience qui figure dans le jeton effectivement émis par Oracle.

Vérification du jeton

Affectez à TOKEN un jeton d’accès généré par la charge de travail OCI concernée, puis utilisez le décodeur JWT local existant pour examiner 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 examine le jeton sans vérifier sa signature. Traitez les jetons bruts comme des données sensibles. Ne les consignez pas dans les journaux et ne collez pas de jetons de production dans des décodeurs JWT tiers.

Un jeton 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
}

Prenez comme référence le jeton émis par votre propre domaine d’identité. Configurez la valeur exacte de iss et l’une des valeurs de aud du jeton. Pour autoriser une charge de travail, privilégiez les revendications immuables ipst_instance, ipst_compartment, domain_id et ca_ocid.

Configuration de la fédération d’identités de charges de travail

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

Configuration du fournisseur d’identités de charges de travail

  1. Créez le fournisseur d’identités de charges de travail. Dans Nom, saisissez une valeur unique, par exemple oracle-cloud-prod. Dans Description, indiquez la charge de travail de confiance, par exemple Production OCI instance principal.

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

  3. Configurez la découverte OIDC propre au locataire si cette option est disponible. Si l’option Utiliser une URL personnalisée pour la découverte OIDC apparaît dans Paramètres avancés, activez-la. Dans URL de découverte OIDC personnalisée, saisissez l’URL du domaine d’identité propre à votre locataire, par exemple https://idcs-example.identity.oraclecloud.com. OpenAI récupère le document de découverte à l’adresse https://idcs-example.identity.oraclecloud.com/.well-known/openid-configuration, puis utilise le champ jwks_uri de ce document 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 vérifier les jetons et importez le JWKS public disponible à l’adresse https://<identity-domain>/admin/v1/SigningCert/jwk.

  4. Ajoutez des transformations d’attributs uniquement 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 correspondance du compte de service. Pour dériver explicitement un attribut d’instance, saisissez instance et associez-lui l’expression assertion.ipst_instance pour créer openai.instance.

La documentation Oracle sur la découverte OpenID Connect explique l’intérêt de la découverte personnalisée. Le document de découverte peut déclarer l’émetteur global https://identity.oraclecloud.com/ alors que le point de terminaison des jetons et l’adresse jwks_uri se trouvent sur le domaine d’identité propre au locataire. Conservez l’émetteur global dans URL de l’émetteur OIDC et utilisez le domaine du locataire dans 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 jeton, 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 vérifier les jetons et importez le JWKS public du locataire disponible à l’adresse https://<identity-domain>/admin/v1/SigningCert/jwk. La découverte personnalisée et la vérification par JWKS importé ne peuvent pas être activées simultanément. Mettez à jour les clés importées lorsqu’Oracle renouvelle ses certificats de signature.

Configuration de la règle de correspondance du compte de service

  1. Créez une règle de correspondance pour le compte de service. Dans Nom, saisissez une valeur unique, par exemple oracle-instance-prod, et ajoutez une description qui identifie la charge de travail OCI de confiance.

  2. Choisissez l’identité OCI stable la plus précise possible. Pour accorder l’accès à une seule instance, saisissez dans Clé le nom ipst_instance et dans Valeur l’OCID exact de l’instance figurant dans le jeton vérifié. Pour accorder l’accès aux instances d’un même compartiment, saisissez dans Clé le nom ipst_compartment et dans Valeur l’OCID exact du compartiment.

  3. Limitez si nécessaire l’accès à un domaine d’identité ou à une location OCI. Ajoutez à la règle des lignes pour domain_id ou ca_ocid afin de limiter l’accès aux charges de travail d’un domaine d’identité ou d’une location Oracle en particulier. Ajoutez sub_type avec la valeur instance si le jeton contient cette revendication et que vous souhaitez exiger un principal d’instance. Le jeton doit satisfaire les critères de toutes les lignes de la règle.

  4. Choisissez la cible OpenAI. Dans Projet, sélectionnez 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. Limitez les autorisations d’accès à l’API si nécessaire. Sélectionnez uniquement les Autorisations dont la charge de travail a besoin. La règle de correspondance peut restreindre les autorisations du compte de service sélectionné, mais elle ne peut pas accorder d’autorisations dont ce compte ne dispose pas déjà.

Une charge de travail OKE qui utilise le mécanisme de signature standard du principal d’instance hérite de l’identité du nœud de travail. Une règle de correspondance définie au niveau de l’instance autorise l’ensemble du nœud, et pas seulement un pod. Si vous devez isoler des pods qui partagent un nœud de travail, utilisez une identité de charge de travail plus précise prise en charge par OCI.

Utilisation du jeton dans le code

Installez les paquets Python OpenAI, OCI et Requests :

pip install openai oci requests

Pour Ruby, installez les gems OpenAI et OCI :

gem install openai oci

Affectez à OCI_IDENTITY_DOMAIN_URL l’URL de base du domaine d’identité situé dans la même location OCI que la charge de travail. Affectez à OPENAI_IDENTITY_PROVIDER_ID et à OPENAI_SERVICE_ACCOUNT_ID les identifiants provenant respectivement de votre fournisseur OpenAI et de la règle de correspondance du compte de service.

Dans l’exemple suivant, le principal d’instance OCI signe une demande d’échange de jeton Oracle. Le SDK OpenAI reçoit le jeton d’accès IDCS obtenu et l’échange au besoin contre un jeton d’accès OpenAI de courte durée :

Authentification 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 jetons du sujet demande un nouveau jeton Oracle lorsque le SDK OpenAI doit renouveler les informations d’identification de la charge de travail. N’affichez jamais le jeton du sujet Oracle ni le jeton d’accès OpenAI obtenu, et ne les enregistrez jamais sur un support persistant.

Recommandations de sécurité pour OCI

  • Si une seule charge de travail doit avoir accès au compte de service, associez une seule instance à ce compte à l’aide de ipst_instance.
  • Utilisez ipst_compartment uniquement si toutes les instances admissibles du compartiment doivent partager la même règle de correspondance.
  • Ajoutez domain_id ou ca_ocid pour limiter l’accès au domaine d’identité ou à la location OCI concernés.
  • Utilisez un compte de service OpenAI distinct pour chaque application et chaque environnement.
  • Avant de vous appuyer sur l’isolation au niveau des pods, vérifiez si le jeton OKE représente un nœud de travail.
  • Utilisez l’audience qui figure dans le jeton émis par Oracle. Ne supposez pas que cette audience est propre à OpenAI.
  • Si votre domaine d’identité ne peut pas utiliser la découverte OIDC, renouvelez les clés publiques importées chaque fois qu’Oracle renouvelle ses clés de signature.