Federación de identidades de cargas de trabajo

La federación de identidades de cargas de trabajo permite que una carga de trabajo de confianza use una identidad que ya tiene, sin tener que almacenar una clave de API de OpenAI ni una credencial de ChatGPT. La carga de trabajo presenta un token de corta duración emitido por tu proveedor de identidad y OpenAI lo intercambia por un token de acceso de OpenAI, también de corta duración.

Las cargas de trabajo de la API de OpenAI también pueden intercambiar una identidad acreditada por un certificado verificado mediante la federación de identidades de cargas de trabajo con X.509.

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

Ambas opciones usan el mismo modelo de confianza, pero se administran de forma diferente y requieren configuraciones distintas en tiempo de ejecución. Primero, revisa los conceptos comunes y las indicaciones sobre proveedores de identidad que aparecen a continuación. Luego, sigue los pasos de la sección correspondiente al producto que usa tu carga de trabajo.

• API de OpenAI: continúa en Usar la identidad de la carga de trabajo con la API de OpenAI.
• Codex: consulta Usar la identidad de la carga de trabajo con Codex.

Consulta la referencia de reglas de federación de Codex para conocer cómo funcionan las reglas y su ciclo de vida.

Cómo funciona

Antes de que se conecte la carga de trabajo, un administrador configura tres elementos:

1. Un proveedor de identidad indica a OpenAI en qué emisor externo confiar y cómo verificar sus tokens firmados o las identidades acreditadas por certificados.
2. Una regla de acceso especifica qué atributos del token acepta OpenAI y en nombre de qué identidad de OpenAI puede actuar la carga de trabajo. En la configuración de la API de OpenAI, se denomina asignación de cuenta de servicio. En la configuración de Codex, se denomina regla de federación.
3. Una entidad de seguridad de OpenAI recibe el acceso resultante. En la API de OpenAI, es una cuenta de servicio de la Plataforma API. En Codex, es un usuario o una cuenta de servicio de ChatGPT en un Espacio de trabajo administrado.

En tiempo de ejecución:

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

El intercambio de tokens nunca crea entidades de seguridad ni proyectos, ni incorpora miembros a un Espacio de trabajo. Los administradores crean o seleccionan esos recursos durante la configuración.

Obtener un token de identidad

Elige la guía correspondiente al entorno donde se ejecuta tu carga de trabajo:

En las configuraciones documentadas, OpenAI admite tokens de sujeto en formato JWT compatibles con OIDC, incluidos los JWT-SVID de SPIFFE. Si usas la API de OpenAI y tu proveedor de OIDC no aparece en la lista, comunícate con el equipo de soporte de OpenAI. Para Codex, selecciona OIDC personalizado en el portal de administración de OpenAI.

Cada guía de proveedor de OIDC explica cómo emitir e inspeccionar un token. Para Codex, sigue únicamente los pasos de emisión del token y luego vuelve a Usar la identidad de la carga de trabajo con Codex. Las instrucciones de configuración de OpenAI y los ejemplos de uso del SDK que aparecen en las guías corresponden a la API de OpenAI. La federación con X.509 solo es compatible con la API de OpenAI.

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

Sigue estos pasos si tu carga de trabajo llama directamente a la API de OpenAI. Necesitas permiso para administrar los proveedores de identidad de cargas 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 cargas de trabajo. Primero, crea el proveedor. Luego, configura sus asignaciones de cuentas de servicio en la página de detalles del proveedor.

Proveedores X.509

Un proveedor X.509 obtiene los atributos de identidad de la carga de trabajo a partir de un certificado de cliente que OpenAI verifica con la configuración de TLS mutuo que ya tiene tu organización. El proveedor 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 de ancla 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 de mTLS, el funcionamiento de las cadenas de certificados, los filtros CEL y la rotación.

A continuación, crea el proveedor X.509, deriva un único valor no vacío para openai.subject y asigna esa identidad a una cuenta de servicio del proyecto que tenga 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. Luego, envía el token de portador 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 completar los pasos en el panel y ver cómo realizar las solicitudes.

Configurar un proveedor de identidad de cargas de trabajo con OIDC

Crea un proveedor de identidad de cargas de trabajo por cada emisor externo en el que confíes. La API de OpenAI admite tokens de sujeto JWT de OIDC para la identidad de cargas de trabajo. La configuración incluye las siguientes opciones:

El descubrimiento personalizado de OIDC y el uso de un JWKS cargado son opciones mutuamente excluyentes. Si habilitas el descubrimiento personalizado, se oculta la opción de usar un JWKS cargado. La URL de descubrimiento personalizada debe ser pública, usar HTTPS y no contener credenciales, un puerto personalizado, una cadena de consulta ni un fragmento.

Si la opción Usar una URL personalizada para el descubrimiento de OIDC no aparece en tu panel, usa el descubrimiento estándar de OIDC o habilita Usar un JWKS cargado para verificar los tokens. Usa el JWKS público que publica tu proveedor de identidad y actualízalo cuando el proveedor rote sus claves de firma.

Cuando el emisor del token y el host de descubrimiento sean distintos, configura URL del emisor de OIDC con el valor de la declaración iss del token y URL personalizada de descubrimiento de OIDC con la URL del host que publica el documento de descubrimiento del proveedor. OpenAI sigue verificando que el emisor del token coincida con el 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 para la federación de identidades de cargas 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, por ejemplo 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 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. Si usas sintaxis o funciones no admitidas, no se podrá resolver la asignación.

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

Las transformaciones deben devolver 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 impiden resolver la asignación. OpenAI convierte los resultados escalares de las transformaciones en cadenas antes de compararlos con los valores de la asignación. Por ejemplo, true se convierte en "true" y 7 se convierte en "7".

Los valores de las claves de asignación que comienzan con openai. se obtienen únicamente mediante transformaciones de atributos. Las declaraciones originales del token de sujeto que ya tienen el prefijo openai. no influyen en la selección de la asignación, a menos que configures la transformación correspondiente.

Administrar el JWKS y la rotación de claves

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

• Descubrimiento de OIDC: OpenAI obtiene /.well-known/openid-configuration del emisor y luego consulta la jwks_uri que figura en ese documento. OpenAI conserva en caché los documentos de descubrimiento y el contenido de los JWKS remotos durante 600 segundos.
• Descubrimiento personalizado de OIDC: OpenAI obtiene /.well-known/openid-configuration de la URL base de descubrimiento personalizada que configuraste y luego consulta la jwks_uri que figura en ese documento. La declaración iss del token debe seguir coincidiendo con URL del emisor de OIDC.
• Actualización cuando no se encuentra una clave: si el kid de un token no aparece en el JWKS en caché, OpenAI actualiza el JWKS y repite la búsqueda antes de rechazar el token.
• JWKS cargado: si habilitas Usar un JWKS cargado para verificar los tokens, OpenAI usa el JWKS que cargaste y guardaste en el proveedor. No realiza el descubrimiento de OIDC ni consulta un JWKS remoto. Una vez que la 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 anteriores como las nuevas en el JWKS del emisor durante el período de rotación. Así, los tokens firmados con la clave anterior siguen funcionando mientras OpenAI acepta los tokens firmados con la 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 figura 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.

En los proveedores X.509, las claves de asignación usan atributos openai.* derivados. Da preferencia a una asignación que exija una coincidencia exacta de openai.subject. Las declaraciones originales del JWT, como sub, aud e iss, solo se aplican a los proveedores de OIDC.

La configuración de la asignación incluye las siguientes opciones:

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

Valores válidos con comodín:

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

Valores no admitidos con comodín:

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

El panel muestra las restricciones de la asignación como Permisos. Las respuestas al intercambio de tokens muestran las mismas restricciones como alcances de OAuth en la propiedad scope. Las asignaciones no pueden incluir alcances de la API de administración. Las llamadas posteriores a la API siguen sujetas a las comprobaciones habituales de autorización.

Ejemplo de resolución de una asignación

La resolución de la asignación comienza después de que OpenAI verifica la identidad externa. OpenAI busca las asignaciones correspondientes a los valores de identity_provider_id y service_account_id de la solicitud, omite las que no están habilitadas y evalúa solo los atributos necesarios para cada asignación. Emite un token únicamente si hay exactamente una asignación habilitada que 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 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 comience con repo:my-org/my-repo:. El valor de la clave openai.repository_ref se obtiene de la transformación del atributo. Una declaración original del token con ese nombre no determina su valor.

Si más de una asignación habilitada coincide con una solicitud de intercambio, OpenAI rechaza la solicitud. 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 que aparece en la guía de tu proveedor de identidad o llama directamente al punto de acceso de intercambio de tokens. Para conocer los campos de las solicitudes y respuestas, el funcionamiento de la autorización y las limitaciones actuales, consulta la referencia de intercambio de tokens de identidad de cargas de trabajo.

Renovar el token de acceso

Si administras directamente el intercambio de tokens, envía access_token y expires_at juntos al pasar la credencial de un servicio de tokens a una aplicación. El campo expires_at indica el momento exacto de vencimiento en UTC, expresado como una marca de tiempo Unix en segundos. Programa la renovación antes de ese momento y deja margen para las diferencias entre relojes y la latencia de las solicitudes.

El campo expires_in indica la vigencia del token en segundos a partir de 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 la respuesta para obtener más detalles.

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

Usar la identidad de la carga de trabajo con Codex

Sigue estos pasos para automatizaciones de Codex de confianza en un Espacio de trabajo administrado de ChatGPT. Codex asigna la carga de trabajo a un usuario o a una cuenta de servicio de ChatGPT en lugar de asignarla a una cuenta de servicio de la Plataforma API.

La referencia de reglas de federación explica cómo una regla puede aceptar varios sujetos externos y asignarlos a una única entidad de seguridad 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 la configuración del proveedor. No pegues tokens de producción en herramientas de terceros para JWT.

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

La asignación de la API de OpenAI no coincide

Verifica 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 haya exactamente una asignación que coincida. Consulta la referencia de errores de intercambio de tokens para conocer en detalle las categorías de errores.

Codex indica que la configuración está incompleta

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

Codex usa otra credencial

Carga en el proceso de Codex las dos variables requeridas para la identidad de la carga de trabajo. Si cualquiera de ellas está presente, Codex da prioridad a WIF sobre las claves de API, los tokens de acceso y las credenciales de inicio de sesión guardadas. Inicia un proceso nuevo con la configuración descargada y vuelve a ejecutar codex login status.

Recomendaciones de seguridad

• Usa una entidad de seguridad dedicada para cada aplicación o carga de trabajo.
• Mantén los entornos de producción separados de los demás entornos.
• Da preferencia a las coincidencias exactas de declaraciones frente a los patrones amplios.
• Otorga solo el acceso que necesita la carga de trabajo.
• Usa tokens de acceso de corta duración.
• Revisa los proveedores, las asignaciones y las reglas, y elimina los que ya no se usen.
• Revisa los errores de intercambio de tokens y los patrones de acceso inesperados.

Documentación relacionada

• Referencia de reglas de federación de Codex
• Referencia de intercambio de tokens de identidad de cargas de trabajo
• Autenticación de Codex
• Variables de entorno de Codex
• Modo no interactivo de Codex