Federación de identidades de carga de trabajo

La federación de identidades de carga de trabajo permite que las automatizaciones de confianza utilicen Codex sin almacenar un token de acceso personal ni otra credencial de OpenAI de larga duración. Su carga de trabajo presenta un token de identidad de corta duración de un proveedor que usted ya administra. OpenAI verifica ese token y devuelve un token de acceso de corta duración para un usuario o una cuenta de servicio de su espacio de trabajo administrado de ChatGPT.

Utilice la identidad de carga de trabajo para procesos desatendidos de Codex en plataformas en la nube, Kubernetes, sistemas de CI y otros entornos que puedan emitir tokens OIDC o JWT-SVID de SPIFFE. Para conocer el modelo de confianza compartida y el flujo independiente de OpenAI API, consulte la descripción general de la identidad de carga de trabajo.

Antes de comenzar

Necesita:

• Permiso para administrar identidades de carga de trabajo en OpenAI Admin Portal.
• Un espacio de trabajo administrado de ChatGPT.
• Un usuario o una cuenta de servicio de ChatGPT que sea miembro activo de ese espacio de trabajo, o permiso para crear uno durante la configuración.
• Un token OIDC o un JWT-SVID de SPIFFE cuyo emisor, audiencia y claims de identificación conozca.
• Un entorno de ejecución capaz de mantener actualizado ese token en un archivo protegido ubicado en una ruta absoluta.
• Codex 0.148.0 o posterior.
• Una política de autenticación efectiva de Codex que permita la autenticación de ChatGPT y el espacio de trabajo seleccionado por la regla de federación. Consulte Aplicar un método de inicio de sesión o un espacio de trabajo.

OpenAI no crea una entidad principal ni una pertenencia al espacio de trabajo durante el intercambio de tokens. Un administrador selecciona o crea la entidad principal antes de que se conecte la carga de trabajo. La creación de un usuario humano ocupa una licencia del espacio de trabajo y está sujeta a las reglas de pertenencia de ese espacio de trabajo.

En Windows nativo, utilice el entorno aislado de Windows elevado. Los demás modos de entorno aislado de Windows no pueden proteger el archivo del token de identidad frente a comandos controlados por el modelo.

Obtenga un token de identidad

El entorno de ejecución de su carga de trabajo obtiene y actualiza el token de identidad ascendente. Codex no llama en su nombre a servicios de metadatos en la nube ni a bibliotecas cliente del proveedor de identidad.

Siga la guía de su proveedor para configurar la emisión de tokens e inspeccionar un token de muestra:

• Microsoft Azure
• AWS
• Google Cloud
• Oracle Cloud Infrastructure
• GitHub Actions
• Kubernetes
• SPIFFE

Decodifique localmente un token de muestra y anote sus iss, aud, sub y cualquier otro claim en el que tenga previsto confiar. La decodificación no verifica la firma. No pegue un token de producción en un sitio web ni lo escriba en registros.

Conecte la carga de trabajo

Un administrador crea el proveedor y la regla de federación antes de iniciar Codex.

1. Abra Identidad de carga de trabajo en OpenAI Admin Portal y seleccione Conectar carga de trabajo.
2. Reutilice un proveedor configurado para Codex o cree uno. Los ajustes preestablecidos del proveedor completan la configuración habitual para GitHub Actions, Microsoft Entra ID, Google Cloud, AWS, Kubernetes, SPIFFE y proveedores OIDC personalizados.
3. Seleccione Codex y el espacio de trabajo administrado que pueda utilizar la carga de trabajo.
4. Añada las condiciones más restrictivas que identifiquen la carga de trabajo. Haga coincidir un subject, claims exactos, una condición CEL o una combinación. Añada audiencias aceptadas para restringir los tokens que acepta la regla. Todos los criterios de coincidencia configurados deben cumplirse.
5. Asigne la regla a un usuario o una cuenta de servicio existente de ChatGPT, o cree uno durante la configuración.
6. Revise el proveedor, las condiciones, el espacio de trabajo, la entidad principal, los ámbitos y la duración del token de acceso. Seleccione Conectar carga de trabajo y, a continuación, Descargar configuración.

El archivo descargado contiene un ID no secreto de la regla de federación y la ruta en la que Codex leerá el token de identidad. No contiene ninguna credencial.

Para automatizar la configuración, utilice la Admin API de identidad de carga de trabajo. Para conocer el comportamiento de los criterios de coincidencia y consultar ejemplos, consulte la Referencia de reglas de federación.

Configure el proceso de Codex

El proceso que inicia Codex necesita estas dos variables de identidad de carga de trabajo:

export OPENAI_FEDERATION_RULE_ID="idpm_..."
export OPENAI_IDENTITY_TOKEN_FILE="/var/run/secrets/openai.com/identity-token"

OPENAI_FEDERATION_RULE_ID no es un secreto. El archivo de token sí lo es. Utilice una ruta absoluta en un directorio específico, como /var/run/secrets/openai.com, que pertenezca a la cuenta de la carga de trabajo y tenga el modo 0700. Solo los procesos de host de confianza deben escribir allí. Mantenga el directorio fuera de los repositorios y de otras rutas disponibles para las herramientas de Codex. Mantenga las credenciales fuera de los registros, el historial del shell y los artefactos de compilación.

Añada atribución de auditoría

Cuando varias instancias del entorno de ejecución comparten una regla de federación, puede identificar cada instancia en los eventos de auditoría de emisión de tokens. Establezca la variable opcional OPENAI_WORKLOAD_IDENTITY_CONTEXT en un objeto JSON codificado como una cadena:

export OPENAI_WORKLOAD_IDENTITY_CONTEXT='{
  "instance_id": "runner-42",
  "display_name": "payments-prod",
  "labels": {
    "environment": "production",
    "region": "us-west-2"
  }
}'

El objeto requiere instance_id. También puede contener display_name y hasta ocho etiquetas. El objeto codificado puede tener hasta 1024 bytes. instance_id y display_name pueden tener hasta 128 caracteres. Las claves de las etiquetas pueden tener hasta 64 caracteres y sus valores hasta 256 caracteres.

Los identificadores deben comenzar con una letra o un número ASCII. A continuación, los valores pueden contener letras, números, ., _, :, /, @ y -. Las claves de etiquetas admiten letras, números, ., _ y -.

OpenAI trata este contexto como atribución de auditoría comunicada por el cliente, no como una identidad de carga de trabajo verificada. No afecta a la autenticación, la autorización, la coincidencia de reglas, los ámbitos, los límites de frecuencia, la revocación, las puertas de acceso a funciones ni las métricas. No incluya credenciales, secretos, datos personales, prompts, resultados del modelo ni otro Customer Content en él.

Para un contexto válido, OpenAI deriva un ID de atribución estable limitado al inquilino, proveedor, regla de federación y instance_id. Para la atribución, el token de acceso contiene el ID, pero no el contexto. El evento de auditoría de emisión correcta del token contiene el ID y el contexto normalizado. Un contexto que supere un límite o incumpla este esquema hace que el intercambio falle con invalid_grant.

Codex lee el contexto cuando se inicia el proceso y no lo transmite, ni tampoco el ID de la regla o la ruta del archivo de token, a shells, hooks o servidores MCP controlados por el modelo. Reinicie Codex después de cambiar el contexto.

Proteja y rote el archivo de token

Para implementaciones administradas de Linux, macOS y WSL, añada todo el directorio de tokens a permissions.filesystem.deny_read en los requisitos administrados:

[permissions.filesystem]
deny_read = ["/var/run/secrets/openai.com"]

Esto impide que los comandos controlados por el modelo lean el token activo o un reemplazo temporal, mientras el proceso host de Codex aún puede utilizar el token para el intercambio. En los volúmenes de tokens proyectados, deniegue el acceso a todo el montaje del token y a cualquier ruta de respaldo o destino resuelto situada fuera de él. Los modos de archivo y la eliminación de variables de entorno por sí solos no protegen las credenciales frente a otro proceso que se ejecute como el mismo usuario. En Windows nativo, utilice el entorno aislado elevado descrito anteriormente.

Para los orígenes de tokens que no proyecten un archivo, haga que un proceso de host de confianza escriba cada reemplazo dentro de ese directorio protegido y cambie su nombre para colocarlo en su ubicación. Un cambio de nombre atómico evita que Codex lea un token parcial. Por ejemplo, adapte este script de actualización propiedad del host al comando de tokens de su proveedor. Aprovisione el directorio antes de ejecutar el script:

set -eu
TOKEN_DIR="/var/run/secrets/openai.com"
TOKEN_FILE="$TOKEN_DIR/identity-token"
umask 077
TOKEN_TEMP="$(mktemp "$TOKEN_DIR/.identity-token.XXXXXX")"
trap 'rm -f -- "$TOKEN_TEMP"' EXIT
trap 'exit 1' HUP INT TERM
your-identity-provider-command > "$TOKEN_TEMP"
test -s "$TOKEN_TEMP"
mv -f -- "$TOKEN_TEMP" "$TOKEN_FILE"

Ejecute el proceso de actualización fuera de cualquier shell o herramienta que Codex pueda controlar. Mantenga la denegación de lectura durante la actualización y la limpieza. Aunque una detención forzada deje un archivo temporal, este debe permanecer dentro del directorio denegado. No coloque la configuración de identidad de carga de trabajo en config.toml.

Verifique la conexión

Cargue el entorno descargado e inspeccione el método de autenticación seleccionado:

. ./workload-identity-idpm_example.env
codex login status

En PowerShell:

$env:OPENAI_FEDERATION_RULE_ID = "idpm_..."
$env:OPENAI_IDENTITY_TOKEN_FILE = "C:\run\openai\identity-token"
codex login status

Una comprobación correcta muestra Logged in using workload identity. Esto confirma que Codex intercambió un token mediante la regla de federación configurada. El comando no muestra el espacio de trabajo, la entidad principal ni la regla resueltos. Confirme esos valores en Admin Portal antes de iniciar la carga de trabajo. Si Codex informa de otro método de autenticación, las dos variables WIF obligatorias no llegaron al proceso.

Si el proveedor utiliza Impedir la reproducción de aserciones y la aserción contiene un claim jti, esta comprobación consume ese jti. Escriba una aserción recién emitida con un jti nuevo antes de iniciar otro proceso de Codex.

Ejecute una solicitud pequeña desde el mismo entorno:

codex exec "Reply with only: workload identity is working"

Codex intercambia el token ascendente y conserva el token de acceso de OpenAI en memoria. No escribe ninguna de las credenciales en auth.json, el llavero del sistema ni config.toml.

Mantenga actualizado el token

Actualice el archivo del token de identidad antes de que caduque el token ascendente. Codex vuelve a leer el archivo cuando necesita otro token de acceso de OpenAI. El token de OpenAI caduca en la fecha que ocurra primero entre la caducidad del token ascendente y la duración de la regla de federación, y nunca dura más de una hora.

Cuando un administrador activa la protección contra reproducción, cada JWT ascendente debe tener un jti único. Escriba una aserción recién emitida con un jti nuevo antes de cada intercambio, incluidas las actualizaciones de un proceso de larga duración. Las aserciones sin jti no reciben protección contra reproducción.

Codex comparte una única sesión de intercambio en memoria dentro de cada proceso host. Las solicitudes simultáneas de ese proceso reutilizan un token de acceso de OpenAI válido y comparten una única actualización cuando caduca. Los procesos independientes realizan intercambios independientes, por lo que necesitan aserciones cuyo uso permita el proveedor.

Precedencia de credenciales

Las dos variables obligatorias de identidad de carga de trabajo tienen precedencia sobre cualquier otro origen de credenciales:

1. Si está presente OPENAI_FEDERATION_RULE_ID o OPENAI_IDENTITY_TOKEN_FILE, Codex selecciona la identidad de carga de trabajo.
2. Si solo está presente una de las variables obligatorias, Codex devuelve un error. No recurre a una API key, un token de acceso ni un inicio de sesión almacenado.
3. OPENAI_WORKLOAD_IDENTITY_CONTEXT por sí sola no selecciona la identidad de carga de trabajo.
4. Cuando no está presente ninguna de las variables WIF obligatorias, Codex aplica las reglas de credenciales normales para esa superficie. En las superficies que permiten la autenticación mediante API key, CODEX_API_KEY tiene precedencia en codex exec, codex review, TypeScript SDK y codex exec-server --remote. Otras superficies pueden utilizar CODEX_ACCESS_TOKEN o un inicio de sesión almacenado.

Una opción apiKey de SDK se convierte en CODEX_API_KEY, pero WIF sigue teniendo precedencia cuando está presente cualquiera de las variables WIF obligatorias. Omita la opción al utilizar WIF para que la carga de trabajo no mantenga una credencial de larga duración sin utilizar.

Para migrar una carga de trabajo existente sin tiempo de inactividad, configure WIF mientras su credencial actual siga disponible. Inicie un proceso nuevo con las dos variables WIF obligatorias; WIF tiene precedencia aunque la credencial anterior siga presente. Cuando la carga de trabajo funcione correctamente con WIF, elimine la credencial anterior de su entorno de ejecución y del almacén de secretos y, a continuación, revóquela. Antes de revocarla, puede revertir el cambio eliminando las dos variables WIF obligatorias e iniciando un proceso nuevo.

Superficies de Codex compatibles

Configure la identidad de carga de trabajo en el equipo propietario del proceso de Codex.

Los clientes remotos de app-server y exec-server nunca envían el token de identidad ascendente a través de sus protocolos.

Cambie o elimine el acceso

Los cambios en los subjects, las audiencias, los claims, la condición CEL, los ámbitos o la duración del token de una regla se aplican a los intercambios nuevos. Un token emitido antes del cambio puede seguir siendo válido hasta que finalice su duración.

Deshabilite un proveedor o una regla para detener el acceso inmediatamente. La deshabilitación bloquea los intercambios nuevos y revoca los tokens de acceso de OpenAI ya emitidos mediante ese recurso. Archivar tiene el mismo efecto sobre el acceso y no se puede deshacer. Cambiar la confianza del proveedor también revoca los tokens emitidos antes de que entre en vigor la nueva confianza.

Audite los cambios

La creación, actualización y archivado de proveedores y reglas de federación generan eventos de auditoría. Utilice la Compliance API y las indicaciones sobre eventos de auditoría para exportar los eventos que admita su espacio de trabajo. Correlaciónelos con los registros de emisión de su proveedor de identidad y no registre aserciones ascendentes ni tokens de acceso de OpenAI en ninguno de los dos sistemas.

Cuando el proceso proporciona OPENAI_WORKLOAD_IDENTITY_CONTEXT, los eventos de auditoría de emisión correcta de tokens también contienen el ID de atribución estable y el contexto normalizado descritos anteriormente.

Solucione problemas

Para obtener información sobre la verificación del proveedor, los límites y CEL, consulte la referencia de reglas de federación.