Usa Oracle Cloud Infrastructure (OCI) como proveedor de identidades de carga de trabajo al intercambiar un token de acceso de Oracle Identity Cloud Service (IDCS) por un token de acceso de OpenAI de corta duración. Una entidad principal de instancia de OCI firma una solicitud de intercambio de tokens dirigida a un dominio de identidad del mismo arrendamiento. OpenAI valida el token resultante y autoriza a la carga de trabajo de OCI a actuar como una cuenta de servicio de OpenAI asignada.
Para Codex, usa esta página para obtener e inspeccionar el token de Oracle. Luego, configura la identidad de carga de trabajo de Codex para escribir ese token en un archivo e indicarle a Codex dónde encontrarlo. La asignación de cuentas de servicio y los ejemplos del SDK de esta página se aplican a la API de OpenAI.
Esta configuración no requiere una clave de API de OpenAI, una aplicación de recursos OAuth personalizada de Oracle ni permisos de grupos dinámicos para una aplicación personalizada.
Configura la carga de trabajo de OCI
Ejecuta tu carga de trabajo en una instancia de OCI Compute con una entidad principal de instancia. Para Oracle Kubernetes Engine (OKE), confirma qué identidad firma la solicitud: el firmante estándar de entidades principales de instancia suele identificar al nodo de trabajo, no a un pod individual de Kubernetes.
El firmante obtiene las credenciales del servicio de metadatos de instancias de OCI. Verifica que la carga de trabajo pueda acceder al punto de acceso de metadatos local al enlace:
curl --fail --silent \
--header "Authorization: Bearer Oracle" \
http://169.254.169.254/opc/v2/instance/id
La carga de trabajo también debe poder realizar solicitudes HTTPS salientes al dominio de identidad de su arrendamiento. El punto de acceso de metadatos en sí no requiere una puerta de enlace NAT ni una conexión a Internet.
Solicita un token de identidad de Oracle
Usa InstancePrincipalsSecurityTokenSigner del SDK de OCI para Python para firmar una solicitud de intercambio de tokens OAuth dirigida a tu dominio de identidad:
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
El alcance urn:opc:idm:__myscopes__ usa la autorización existente de la entidad principal de instancia. Usa el token de acceso de IDCS devuelto como token de sujeto para la federación de identidades de carga de trabajo de OpenAI. No reemplaces la audiencia del token de Oracle por https://api.openai.com/v1; configura el proveedor de OpenAI con una audiencia que aparezca en el token real de Oracle.
Verifica el token
Establece TOKEN en un token de acceso generado por la carga de trabajo real de OCI y luego usa el decodificador JWT local existente para inspeccionar sus declaraciones:
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);El decodificador inspecciona el token sin verificar su firma. Trata los tokens sin procesar como información confidencial, no los incluyas en registros y no pegues tokens de producción en decodificadores JWT de terceros.
Un token de acceso de Oracle decodificado puede contener las siguientes declaraciones:
{
"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
}
Usa el token emitido por tu propio dominio de identidad como fuente de referencia. Configura el valor exacto de iss y uno de los valores de aud del token. Da preferencia a las declaraciones inmutables ipst_instance, ipst_compartment, domain_id y ca_ocid al autorizar una carga de trabajo.
Configura la federación de identidades de carga de trabajo
Crea un proveedor de identidades de carga de trabajo para tu dominio de identidad de Oracle y luego agrega una asignación para la instancia o el compartimento de OCI que puede usar la cuenta de servicio de OpenAI de destino.
Configura el proveedor de identidades de carga de trabajo
-
Crea el proveedor de identidades de carga de trabajo. Establece Nombre en un valor único, como
oracle-cloud-prod. Usa Descripción, por ejemplo,Production OCI instance principal, para identificar la carga de trabajo de confianza. -
Establece el emisor y la audiencia. Establece URL del emisor OIDC en la declaración
issdel token, por ejemplo,https://identity.oraclecloud.com/. Establece Audiencia en uno de los valores deauddel mismo token. -
Configura el descubrimiento OIDC específico del arrendatario cuando esté disponible. Si aparece Usar URL personalizada para el descubrimiento OIDC en Avanzado, activa esa opción. Establece URL personalizada de descubrimiento OIDC en el dominio de identidad específico de tu arrendatario, por ejemplo,
https://idcs-example.identity.oraclecloud.com. OpenAI obtienehttps://idcs-example.identity.oraclecloud.com/.well-known/openid-configurationy luego usa el valor dejwks_uridel documento de descubrimiento para obtener las claves públicas de firma del arrendatario. Si no aparece la opción de descubrimiento personalizado, activa Usar JWKS cargado para verificar tokens y carga el JWKS público dehttps://<identity-domain>/admin/v1/SigningCert/jwken su lugar. -
Agrega transformaciones de atributos solo cuando necesites atributos derivados. Puedes usar declaraciones de Oracle sin procesar, como
ipst_instance,ipst_compartment,domain_idyca_ocid, directamente en las aserciones de asignación de cuentas de servicio. Para un atributo de instancia derivado explícitamente, ingresainstancecon la expresiónassertion.ipst_instancepara crearopenai.instance.
La referencia de descubrimiento de OpenID Connect de Oracle muestra por qué es importante el descubrimiento personalizado: el documento de descubrimiento puede declarar el emisor global https://identity.oraclecloud.com/ y publicar el punto de acceso de tokens y jwks_uri en el dominio de identidad específico del arrendatario. Mantén el emisor global en URL del emisor OIDC y usa el dominio del arrendatario en URL personalizada de descubrimiento OIDC.
Si tu dominio de identidad publica metadatos de descubrimiento en el emisor del token,
deja desactivado el descubrimiento personalizado y usa el descubrimiento OIDC estándar. Si OpenAI
no puede acceder al documento de descubrimiento del arrendatario o al punto de acceso de claves de firma, desactiva
el descubrimiento personalizado, activa Usar JWKS cargado para verificar tokens y
carga el JWKS público del arrendatario desde
https://<identity-domain>/admin/v1/SigningCert/jwk. El descubrimiento personalizado y
el JWKS cargado no pueden estar activados al mismo tiempo. Actualiza las claves cargadas cuando
Oracle rote sus certificados de firma.
Configura la asignación de cuentas de servicio
-
Crea una asignación de cuentas de servicio. Establece Nombre en un valor único, como
oracle-instance-prod, y agrega una descripción que identifique la carga de trabajo de OCI de confianza. -
Usa como criterio de coincidencia la identidad estable de OCI más específica. Para conceder acceso a una instancia, establece Clave en
ipst_instancey Valor en el OCID exacto de la instancia que aparece en el token verificado. Para conceder acceso a las instancias de un compartimento, establece Clave enipst_compartmenty Valor en el OCID exacto del compartimento. -
Agrega restricciones de dominio y arrendamiento cuando sea necesario. Agrega más filas de asignación para
domain_idoca_ocida fin de limitar la carga de trabajo a un dominio de identidad o arrendamiento de Oracle específico. Agregasub_typecon el valorinstancecuando el token incluya esa declaración y quieras exigir una entidad principal de instancia. Todas las filas de asignación deben coincidir. -
Elige el destino de OpenAI. Establece Proyecto en el proyecto al que pertenece la cuenta de servicio y luego selecciona la Cuenta de servicio que puede usar la carga de trabajo de OCI de confianza.
-
Restringe los permisos de la API si es necesario. Selecciona solo los Permisos que necesita la carga de trabajo. Los permisos de la asignación pueden restringir la cuenta de servicio seleccionada, pero no pueden otorgarle permisos que aún no tenga.
Una carga de trabajo de OKE que usa el firmante estándar de entidades principales de instancia hereda la identidad del nodo de trabajo. Una asignación a nivel de instancia autoriza a ese nodo, no solo a un pod. Usa una identidad de carga de trabajo de OCI más específica y compatible cuando necesites aislamiento entre pods que comparten un nodo de trabajo.
Usa el token en el código
Instala los paquetes de Python de OpenAI, OCI y Requests:
pip install openai oci requests
Para Ruby, instala las gemas de OpenAI y OCI:
gem install openai oci
Establece OCI_IDENTITY_DOMAIN_URL en la URL base del dominio de identidad que se encuentra en el mismo arrendamiento que la carga de trabajo. Establece OPENAI_IDENTITY_PROVIDER_ID y OPENAI_SERVICE_ACCOUNT_ID en los ID de tu proveedor de OpenAI y de la asignación de cuentas de servicio.
El siguiente ejemplo firma una solicitud de intercambio de tokens de Oracle con la entidad principal de instancia de OCI, devuelve el token de acceso de IDCS al SDK de OpenAI y permite que el SDK lo intercambie por un token de acceso de OpenAI de corta duración cuando sea necesario:
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)El proveedor de tokens de sujeto solicita un nuevo token de Oracle cuando el SDK de OpenAI necesita renovar la credencial de identidad de carga de trabajo. Nunca imprimas ni guardes de forma persistente el token de sujeto de Oracle ni el token de acceso de OpenAI resultante.
Recomendaciones de seguridad de OCI
- Asigna una instancia con
ipst_instancecuando solo una carga de trabajo deba tener acceso. - Usa
ipst_compartmentsolo cuando todas las instancias elegibles de ese compartimento deban compartir la asignación. - Agrega
domain_idoca_ocidpara aplicar restricciones de dominio de identidad y arrendamiento. - Usa una cuenta de servicio de OpenAI independiente para cada aplicación y entorno.
- Verifica si un token de OKE representa a un nodo de trabajo antes de confiar en el aislamiento a nivel de pod.
- Usa la audiencia presente en el token de Oracle emitido en lugar de suponer una audiencia específica de OpenAI.
- Rota las claves públicas cargadas cuando Oracle rote sus claves de firma si tu dominio de identidad no puede usar el descubrimiento OIDC.