Para usar Oracle Cloud Infrastructure (OCI) como proveedor de identidades de cargas de trabajo, intercambia un token de acceso de Oracle Identity Cloud Service (IDCS) por un token de acceso de OpenAI de corta duración. Una identidad principal de instancia de OCI firma la 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 en nombre de la cuenta de servicio de OpenAI a la que está asignada.
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 acceder a una aplicación personalizada.
Configurar la carga de trabajo de OCI
Ejecuta tu carga de trabajo en una instancia de OCI Compute con una identidad principal de instancia. Si usas Oracle Kubernetes Engine (OKE), confirma qué identidad firma la solicitud. El firmante estándar de la identidad principal de instancia suele identificar al nodo de trabajo en su conjunto, 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 mediante su dirección de enlace local:
curl --fail --silent \
--header "Authorization: Bearer Oracle" \
http://169.254.169.254/opc/v2/instance/id
La carga de trabajo también debe poder enviar 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 conexión a internet.
Solicitar un token de identidad de Oracle
Usa InstancePrincipalsSecurityTokenSigner del SDK de OCI para Python para firmar una solicitud OAuth de intercambio de tokens 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__ utiliza la autorización que ya tiene la identidad principal de instancia. Usa el token de acceso de IDCS que recibas como token de sujeto para la federación de identidades de cargas de trabajo de OpenAI. No sustituyas la audiencia del token de Oracle por https://api.openai.com/v1. Configura el proveedor de OpenAI con una audiencia que figure en el token emitido por Oracle.
Verificar el token
Asigna a TOKEN un token de acceso generado por la carga de trabajo de OCI que vas a usar. Luego, usa el decodificador local de JWT existente para examinar 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 examina el token sin verificar su firma. Trata los tokens sin procesar como datos sensibles. No los incluyas en los registros ni pegues tokens de producción en decodificadores de 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
}
Toma como referencia el token emitido por tu propio dominio de identidad. Configura el valor exacto de iss y uno de los valores de aud del token. Al autorizar una carga de trabajo, da preferencia a las declaraciones inmutables ipst_instance, ipst_compartment, domain_id y ca_ocid.
Configurar la federación de identidades de cargas de trabajo
Crea un proveedor de identidades de cargas de trabajo para tu dominio de identidad de Oracle. Luego, agrega una asignación para la instancia o el compartimento de OCI que podrá usar la cuenta de servicio de OpenAI de destino.
Configurar el proveedor de identidades de cargas de trabajo
-
Crea el proveedor de identidades de cargas de trabajo. En Nombre, ingresa un valor único, como
oracle-cloud-prod. En Descripción, ingresa un texto que identifique la carga de trabajo de confianza, comoProduction OCI instance principal. -
Configura el emisor y la audiencia. En URL del emisor OIDC, ingresa el valor de la declaración
issdel token, por ejemplo,https://identity.oraclecloud.com/. En Audiencia, ingresa uno de los valores deauddel mismo token. -
Configura el descubrimiento OIDC específico del arrendatario cuando esté disponible. Si la opción Usar una URL personalizada para el descubrimiento OIDC aparece en Opciones avanzadas, actívala. En URL personalizada de descubrimiento OIDC, ingresa la URL del dominio de identidad 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 la opción de descubrimiento personalizado no aparece, activa Usar un JWKS cargado para verificar los tokens y carga el JWKS público que se encuentra enhttps://<identity-domain>/admin/v1/SigningCert/jwk. -
Agrega transformaciones de atributos solo cuando necesites atributos derivados. Puedes usar declaraciones de Oracle sin transformar, como
ipst_instance,ipst_compartment,domain_idyca_ocid, directamente en las aserciones de asignación de cuentas de servicio. Para derivar un atributo de instancia de forma explícita, ingresainstancecon la expresiónassertion.ipst_instancepara crearopenai.instance.
La referencia de Oracle sobre el descubrimiento de OpenID Connect explica por qué es importante el descubrimiento personalizado. El documento de descubrimiento puede declarar el emisor global https://identity.oraclecloud.com/ y, al mismo tiempo, publicar el punto de acceso de tokens y jwks_uri en el dominio de identidad específico del arrendatario. Conserva 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 los metadatos de descubrimiento en la URL del 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 las claves de firma, desactiva el descubrimiento personalizado, activa Usar un JWKS cargado para verificar los tokens y carga el JWKS público del arrendatario que se encuentra en https://<identity-domain>/admin/v1/SigningCert/jwk. No puedes activar el descubrimiento personalizado y el uso de un JWKS cargado al mismo tiempo. Actualiza las claves cargadas cuando Oracle rote sus certificados de firma.
Configurar la asignación de la cuenta de servicio
-
Crea una asignación de cuenta de servicio. En Nombre, ingresa 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 sola instancia, en Clave ingresa
ipst_instancey en Valor ingresa el OCID exacto de la instancia que figura en el token verificado. Para conceder acceso a las instancias de un mismo compartimento, en Clave ingresaipst_compartmenty en Valor ingresa el OCID exacto del compartimento. -
Limita el acceso por dominio y arrendamiento cuando sea necesario. Agrega filas de asignación para
domain_idoca_ocidsi necesitas restringir la carga de trabajo a un dominio de identidad o arrendamiento específico de Oracle. Agregasub_typecon el valorinstancesi el token incluye esa declaración y quieres exigir una identidad principal de instancia. El token debe cumplir los criterios de todas las filas de la asignación. -
Elige el destino en OpenAI. En Proyecto, selecciona el proyecto al que pertenece la cuenta de servicio. Luego, selecciona la Cuenta de servicio que podrá usar la carga de trabajo de OCI de confianza.
-
Limita los permisos de la API si es necesario. Selecciona solo los Permisos que necesite la carga de trabajo. Los permisos de la asignación pueden restringir los de la cuenta de servicio seleccionada, pero no pueden conceder permisos que la cuenta aún no tenga.
Una carga de trabajo de OKE que usa el firmante estándar de la identidad principal de instancia hereda la identidad del nodo de trabajo. Una asignación a nivel de instancia autoriza al nodo completo, no solo a un pod. Si necesitas aislar los pods que comparten un nodo de trabajo, usa una identidad de carga de trabajo de OCI más específica que sea compatible con esa configuración.
Usar 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
Asigna a OCI_IDENTITY_DOMAIN_URL la URL base del dominio de identidad que pertenece al mismo arrendamiento que la carga de trabajo. Asigna a OPENAI_IDENTITY_PROVIDER_ID y OPENAI_SERVICE_ACCOUNT_ID los ID correspondientes que figuran en el proveedor de OpenAI y en la asignación de la cuenta de servicio.
El siguiente ejemplo usa la identidad principal de instancia de OCI para firmar una solicitud de intercambio de tokens de Oracle. Devuelve el token de acceso de IDCS al SDK de OpenAI para que el SDK pueda intercambiarlo por un token de acceso de OpenAI de corta duración cuando lo necesite:
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 la 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 para OCI
- Si solo una carga de trabajo debe tener acceso, asigna una sola instancia mediante
ipst_instance. - Usa
ipst_compartmentsolo cuando todas las instancias que cumplan los requisitos en ese compartimento deban compartir la asignación. - Agrega
domain_idoca_ocidpara restringir el acceso por dominio de identidad y arrendamiento. - Usa una cuenta de servicio de OpenAI distinta para cada aplicación y entorno.
- Antes de confiar en el aislamiento a nivel de pod, verifica si el token de OKE representa a un nodo de trabajo.
- Usa la audiencia que figura en el token emitido por Oracle. No des por hecho que la audiencia es específica de OpenAI.
- Si tu dominio de identidad no puede usar el descubrimiento OIDC, rota las claves públicas cargadas cuando Oracle rote sus claves de firma.