Federación de identidades de carga de trabajo

La federación de identidades de carga de trabajo permite que una carga de trabajo de confianza use una identidad que ya tiene en lugar de almacenar una clave de API de OpenAI o una credencial de ChatGPT. La carga de trabajo presenta un token de corta duración de tu proveedor de identidad y OpenAI lo intercambia por un token de acceso de OpenAI de corta duración.

Las cargas de trabajo de la API de OpenAI también pueden intercambiar una identidad de certificado verificada mediante la federación de identidades de carga de trabajo X.509.

Puedes usar la federación de identidades de carga de trabajo con la API de OpenAI o Codex:

Ambas opciones usan el mismo modelo de confianza, pero difieren en su administración y configuración de ejecución. Comienza con los conceptos compartidos y las indicaciones sobre proveedores de identidad que aparecen a continuación, y luego sigue la sección del producto que usa tu carga de trabajo.

• API de OpenAI: continúa con Usar la identidad de carga de trabajo con la API de OpenAI.
• Codex: sigue Usar la identidad de carga de trabajo con Codex para completar la configuración en el portal de administración y la configuración de ejecución.

Los administradores también pueden administrar proveedores y reglas de Codex con la API de administración. Consulta la referencia de reglas de federación de Codex para conocer el comportamiento de las reglas y su ciclo de vida.

Cómo funciona

Un administrador configura tres elementos antes de que se conecte la carga de trabajo:

1. Un proveedor de identidad indica a OpenAI en qué emisor externo confiar y cómo verificar sus tokens firmados o identidades de certificado.
2. Una regla de acceso describe qué atributos del token acepta OpenAI y con qué identidad de OpenAI puede actuar la carga de trabajo. En la configuración de la API de OpenAI, esto se denomina asignación de cuenta de servicio. En la configuración de Codex, se denomina regla de federación.
3. Una entidad principal de OpenAI recibe el acceso resultante. Para la API de OpenAI, la entidad principal es una cuenta de servicio de la plataforma. Para Codex, la entidad principal es una cuenta de usuario o de servicio de ChatGPT en un espacio de trabajo administrado.

Durante la ejecución:

1. La carga de trabajo recibe un OIDC JWT o un SPIFFE JWT-SVID de corta duración, o bien una carga de trabajo de la API de OpenAI presenta un certificado X.509.
2. La carga de trabajo presenta su identidad externa junto con los ID que requiere su producto.
3. OpenAI verifica el token o certificado y luego evalúa la asignación o regla configurada.
4. OpenAI devuelve un token de acceso de corta duración para la entidad principal asignada.

El intercambio de tokens nunca crea una entidad principal, un proyecto ni una membresía en un espacio de trabajo. Los administradores crean o seleccionan esos recursos durante la configuración.

Obtener un token de identidad

Elige la guía del entorno en el que se ejecuta tu carga de trabajo:

OpenAI admite tokens de sujeto JWT compatibles con OIDC en las configuraciones documentadas, incluidos los SPIFFE JWT-SVID. Para la API de OpenAI, contacta al soporte de OpenAI si tu proveedor OIDC no aparece en la lista. Para Codex, elige OIDC personalizado en el portal de administración de OpenAI.

La guía de cada proveedor OIDC explica cómo emitir e inspeccionar un token. Para Codex, sigue solo esos pasos de emisión de tokens y luego vuelve a Usar la identidad de carga de trabajo con Codex. La configuración de OpenAI y los ejemplos del SDK de esas guías se aplican a la opción de la API de OpenAI. La federación X.509 solo admite la opción de la API de OpenAI.

Usar la identidad de carga de trabajo con la API de OpenAI

Usa esta opción cuando tu carga de trabajo llame directamente a la API de OpenAI. Necesitas permiso para administrar los proveedores de identidad de carga de trabajo y las asignaciones de cuentas de servicio de la organización.

Ve a Configuración de la organización > Seguridad > Proveedor de identidad de carga de trabajo. Primero crea el proveedor y luego configura sus asignaciones de cuentas de servicio desde la página de detalles del proveedor.

Proveedores X.509

Un proveedor X.509 deriva atributos de identidad de carga de trabajo de un certificado de cliente que OpenAI verifica con la configuración de TLS mutuo existente de tu organización. No almacena certificados ni mantiene un almacén de confianza separado.

Antes de crear el proveedor, configura y activa el certificado de confianza que sirve como ancla de confianza para tu certificado de cliente en Configuración de la organización > Seguridad > TLS mutuo. La guía de TLS mutuo explica los permisos, los requisitos de los certificados, el alcance de la activación, los hosts mTLS, el comportamiento de la cadena de certificados, los filtros CEL y la rotación.

A continuación, crea el proveedor X.509, deriva un valor no vacío de openai.subject y asigna esa identidad a una cuenta de servicio del proyecto con solo los permisos que necesita la carga de trabajo. La carga de trabajo presenta su certificado al punto de acceso de tokens X.509 para obtener un token de portador de corta duración y luego envía ese token y un certificado de cliente aceptado al punto de acceso mTLS de la API.

Sigue la guía de configuración de certificados X.509 para ver el procedimiento completo en el panel y el flujo de solicitudes.

Configurar un proveedor de identidad de carga de trabajo OIDC

Crea un proveedor de identidades de carga de trabajo para cada emisor externo en el que confíes. La identidad de carga de trabajo de la API de OpenAI admite tokens de sujeto JWT de OIDC. Su configuración incluye:

El descubrimiento OIDC personalizado y el uso de un JWKS cargado son mutuamente excluyentes. Activar el descubrimiento personalizado oculta la opción de JWKS cargado. La URL de descubrimiento personalizada debe usar HTTPS público y no puede contener credenciales, un puerto personalizado, una consulta ni un fragmento.

Si Usar una URL personalizada para el descubrimiento OIDC no aparece en tu panel, usa el descubrimiento OIDC estándar o activa Usar un JWKS cargado para verificar tokens como alternativa. Usa el JWKS público que publica tu proveedor de identidades y actualízalo cuando el proveedor rote sus claves de firma.

Cuando el emisor del token y el host de descubrimiento difieran, establece URL del emisor OIDC en la declaración iss del token y URL de descubrimiento OIDC personalizada en el host que publica el documento de descubrimiento del proveedor. OpenAI sigue verificando el token con respecto al emisor configurado; la URL personalizada solo determina de dónde obtiene los metadatos de descubrimiento y las claves públicas de firma.

Transformar las declaraciones del token con CEL

Las transformaciones de atributos usan Common Expression Language (CEL). OpenAI admite los operadores estándar de CEL especificados en langdef.md y no agrega funciones personalizadas de federación de identidades de carga de trabajo. Cada expresión recibe un objeto raíz:

• assertion: el conjunto de declaraciones verificadas del JWT.

El panel aplica automáticamente el prefijo openai.. Ingresa el sufijo, como subject, y una expresión, como assertion.sub. La API almacena el atributo derivado como openai.subject.

12345678910[
  {
    "attribute": "openai.subject",
    "expression": "assertion.sub"
  },
  {
    "attribute": "openai.repository",
    "expression": "assertion.repository"
  }
]

Usa la sintaxis de CEL definida en la especificación del lenguaje CEL. Por ejemplo, puedes leer los valores de las declaraciones con expresiones como assertion.sub o assertion.repository. Las funciones o la sintaxis no admitidas hacen que falle la resolución de asignaciones.

12345678910[
  {
    "attribute": "openai.repository_ref",
    "expression": "assertion.repository + \"@\" + assertion.ref"
  },
  {
    "attribute": "openai.production",
    "expression": "assertion.ref == \"refs/heads/main\""
  }
]

Los resultados de las transformaciones deben ser valores escalares: cadenas, valores true o false, enteros o números finitos. Los arreglos, los objetos, los valores nulos y los errores de evaluación hacen que falle la resolución de asignaciones. OpenAI convierte los resultados escalares de las transformaciones en cadenas antes de compararlos con los valores de las asignaciones. Por ejemplo, true se convierte en "true" y 7 se convierte en "7".

Las claves de asignación que empiezan con openai. se resuelven únicamente a partir de transformaciones de atributos. Las declaraciones sin transformar del token de sujeto que ya usan el prefijo openai. no afectan las decisiones de asignación, a menos que configures una transformación correspondiente.

Administrar JWKS y la rotación de claves

OpenAI verifica los tokens de sujeto OIDC con la fuente de claves configurada en el proveedor de identidades de carga de trabajo:

• Descubrimiento OIDC: OpenAI obtiene el documento /.well-known/openid-configuration del emisor y luego obtiene el contenido de la jwks_uri descubierta. OpenAI almacena en caché los documentos de descubrimiento y las cargas útiles de JWKS remotos durante 600 segundos.
• Descubrimiento OIDC personalizado: OpenAI obtiene /.well-known/openid-configuration de la URL base de descubrimiento personalizado configurada y luego obtiene el contenido de la jwks_uri descubierta. La declaración iss del token debe seguir coincidiendo con URL del emisor OIDC.
• Actualización de claves si no hay coincidencia: si no se encuentra el kid de un token en el JWKS almacenado en caché, OpenAI actualiza el JWKS e intenta buscarlo de nuevo antes de rechazar el token.
• JWKS cargado: cuando Usar un JWKS cargado para verificar tokens está activado, OpenAI usa el JWKS cargado que está almacenado en el proveedor y no realiza el descubrimiento OIDC ni obtiene JWKS remotos. Una vez que una actualización del proveedor está disponible para el intercambio de tokens, los nuevos intercambios usan el JWKS guardado.
• Conjuntos de claves: un JWKS puede contener más de una clave pública. Cada clave debe tener un kid único y no vacío.

Al rotar las claves de firma, publica tanto las claves públicas antiguas como las nuevas en el JWKS del emisor durante el período de rotación. Esto permite que los tokens firmados con la clave antigua sigan funcionando mientras OpenAI acepta los tokens firmados con la clave nueva. Si usas un JWKS cargado, actualiza el proveedor antes de emitir tokens con el nuevo kid; OpenAI rechaza los tokens firmados con una clave que no figure en el JWKS configurado.

Configurar una asignación de cuenta de servicio

Una asignación de cuenta de servicio define qué identidades externas pueden generar tokens de acceso para una cuenta de servicio de OpenAI.

Para los proveedores X.509, las claves de asignación usan atributos openai.* derivados. Es preferible usar una asignación exacta de openai.subject. Las declaraciones JWT sin transformar, como sub, aud e iss, solo se aplican a los proveedores OIDC.

Su configuración incluye:

Los valores de los atributos deben ser valores JSON escalares. Las cadenas pueden usar un único comodín al final con un prefijo no vacío, como repo:example/*. No se admite un comodín por sí solo ni en medio de un valor.

Valores válidos con comodines:

• repo:openai/*
• repository:my-org/*

Valores no admitidos con comodines:

• *
• repo:*:prod
• repo/*/main

El panel muestra las restricciones de las asignaciones como Permisos. Las respuestas de intercambio de tokens exponen las mismas restricciones como alcances de OAuth en la propiedad scope. Las asignaciones no pueden incluir alcances de la API de administración, y la autorización habitual de la API sigue aplicándose a las solicitudes posteriores.

Ejemplo de resolución de asignaciones

La resolución de asignaciones comienza después de que OpenAI verifica la identidad externa. OpenAI busca las asignaciones para los valores solicitados de identity_provider_id y service_account_id, omite las que no están habilitadas, evalúa solo los atributos que requiere cada asignación y emite un token únicamente si exactamente una asignación habilitada coincide con todos los atributos configurados.

Supongamos que un token de GitHub Actions contiene estas declaraciones:

1234567{
  "iss": "https://token.actions.githubusercontent.com",
  "aud": "https://api.openai.com/v1",
  "sub": "repo:my-org/my-repo:ref:refs/heads/main",
  "repository": "my-org/my-repo",
  "ref": "refs/heads/main"
}

El proveedor puede derivar un atributo:

123456[
  {
    "attribute": "openai.repository_ref",
    "expression": "assertion.repository + \"@\" + assertion.ref"
  }
]

La asignación de la cuenta de servicio puede entonces exigir tanto atributos originales como derivados:

Los tres valores deben coincidir. El valor de sub usa un comodín al final, por lo que coincide con cualquier valor que tenga el prefijo repo:my-org/my-repo:. La clave openai.repository_ref se resuelve a partir de la transformación del atributo, no de una declaración original del token con ese nombre.

Si más de una asignación habilitada coincide con un intercambio, OpenAI lo rechaza. OpenAI exige una asignación única para cada par (provider, service account) y no combina permisos de distintas asignaciones.

Conectar la carga de trabajo

Usa el ejemplo del SDK de la guía de tu proveedor de identidad, o llama directamente al punto de acceso de intercambio de tokens. Para conocer los campos de solicitud y respuesta, el comportamiento de la autorización y las limitaciones actuales, consulta la referencia de intercambio de tokens de identidad de carga de trabajo.

Renovar el token de acceso

Si gestionas el intercambio de tokens directamente, mantén juntos access_token y expires_at al pasar la credencial de un servicio de tokens a una aplicación. El campo expires_at indica el momento de vencimiento absoluto en UTC, expresado como una marca de tiempo Unix en segundos. Programa la renovación antes de ese momento, teniendo en cuenta las diferencias entre relojes y la latencia de las solicitudes.

El campo expires_in indica la vigencia del token en segundos desde su emisión. Por ejemplo, un token emitido a las 12:00 UTC con expires_in: 3600 vence a las 13:00 UTC, incluso si otro servicio lo recibe a las 12:05 UTC. El tiempo de transporte y procesamiento no prolonga la vigencia del token. Consulta los campos de respuesta para obtener más detalles.

El intercambio de tokens no devuelve un token de actualización. Para renovarlo, repite el intercambio con un token de identidad externo válido o un certificado de cliente válido.

Usar la identidad de carga de trabajo con Codex

Usa esta opción para automatizaciones de Codex de confianza en un espacio de trabajo administrado de ChatGPT. Codex asigna la carga de trabajo a un usuario o una cuenta de servicio de ChatGPT en lugar de una cuenta de servicio de la Plataforma API.

Sigue la guía Usar la identidad de carga de trabajo con Codex para conocer el procedimiento completo de administración y ejecución. Abarca las fuentes de tokens específicas de cada proveedor, las reglas de federación, la configuración requerida del archivo de tokens, la prioridad de las credenciales, las interfaces de Codex compatibles, la rotación y la verificación. Para la atribución opcional en auditorías, Codex acepta OPENAI_WORKLOAD_IDENTITY_CONTEXT; la guía de Codex define su esquema, los límites de privacidad y el comportamiento de auditoría.

Usa la API de administración para administrar los proveedores y las reglas de Codex de forma programática. La referencia de reglas de federación explica cómo una regla puede aceptar más de un sujeto externo y asignarlos a una sola entidad principal de ChatGPT.

Solucionar problemas de conexión

OpenAI rechaza el token de identidad

Decodifica el token localmente y compara sus declaraciones iss, aud, sub, exp, iat y las específicas del proveedor con el proveedor configurado. No pegues tokens de producción en herramientas JWT de terceros.

Para la API de OpenAI, compara también los atributos del token con la asignación de la cuenta de servicio seleccionada. Para Codex, compáralos con la regla de federación seleccionada.

La asignación de la API de OpenAI no coincide

Confirma que la solicitud use los ID del proveedor de identidad y de la cuenta de servicio previstos, que la asignación esté activa y que coincida exactamente una asignación. Consulta la referencia de errores de intercambio de tokens para conocer las categorías de errores en detalle.

Codex informa que la configuración está incompleta

Confirma que el proceso de Codex tenga las dos variables de entorno de identidad de carga de trabajo requeridas y que OPENAI_IDENTITY_TOKEN_FILE contenga una ruta absoluta a un token vigente. Revisa los permisos del archivo y del directorio que lo contiene.

Codex usa otra credencial

Carga las dos variables de identidad de carga de trabajo requeridas en el proceso de Codex. La presencia de cualquiera de ellas hace que se seleccione WIF antes que las claves de API, los tokens de acceso y los inicios de sesión guardados. Inicia un nuevo proceso con la configuración descargada cargada, y luego vuelve a ejecutar codex login status.

Recomendaciones de seguridad

• Usa una entidad principal dedicada para cada aplicación o carga de trabajo.
• Separa los entornos de producción de los demás entornos.
• Prefiere las coincidencias exactas de declaraciones a los patrones amplios.
• Otorga solo el acceso que necesite la carga de trabajo.
• Usa períodos de validez cortos para los tokens de acceso.
• Revisa y elimina los proveedores, las asignaciones y las reglas que no se usen.
• Revisa los errores de intercambio de tokens y los patrones de acceso inesperados.

Documentación relacionada

• Usar la identidad de carga de trabajo con Codex
• Referencia de reglas de federación de Codex
• Administrar la identidad de carga de trabajo de Codex con la API de administración
• Referencia de intercambio de tokens de identidad de carga de trabajo
• Autenticación de Codex
• Variables de entorno de Codex
• Modo no interactivo de Codex