Referencia de las reglas de federación de Codex

Una regla de federación determina qué identidades verificadas de cargas de trabajo pueden actuar en nombre de un usuario o una cuenta de servicio de ChatGPT. OpenAI evalúa únicamente la regla que el proceso de Codex indica por nombre. No busca coincidencias en las demás reglas.

Cada regla tiene una sola entidad de seguridad de destino y puede aceptar una o varias identidades de origen. Para aceptar un conjunto de sujetos en una misma regla, especifica un prefijo de sujeto seguido de un comodín o usa una condición CEL. También puedes crear varias reglas para la misma entidad de seguridad.

Componentes de una regla

Antes del intercambio, la entidad de seguridad debe existir y pertenecer al Espacio de trabajo. Cuando se conecta una carga de trabajo, la regla no crea usuarios ni cuentas de servicio ni los agrega al Espacio de trabajo.

Cómo se combinan las verificaciones de identidad

Una regla puede usar las siguientes verificaciones:

Configura al menos una verificación de sujeto, de declaraciones exactas o de CEL. Una audiencia aceptada por sí sola no identifica una carga de trabajo. Si configuras varios tipos de verificación, el token debe superar todas las verificaciones.

Primero se realizan las verificaciones del proveedor. Una regla no puede anular las verificaciones del proveedor sobre el emisor, la firma, el vencimiento, la vigencia o la reutilización de la aserción, ni sus verificaciones CEL.

Coincidencia de sujetos

Usa un sujeto exacto cuando un único valor estable de sub identifique la carga de trabajo:

repo:example-company/payments:environment:production

Un único * al final permite buscar coincidencias por prefijo:

system:serviceaccount:production:codex-*

El comodín debe ser el último carácter y debe ir después de un prefijo que no esté vacío. OpenAI no acepta *, repo:*:production ni repo/*/main.

Evita los prefijos demasiado amplios si una declaración más estable permite distinguir las cargas de trabajo con privilegios. Por ejemplo, una regla de GitHub debería verificar el repositorio, el archivo de flujo de trabajo, la referencia o el entorno protegido, en lugar de aceptar todos los repositorios de una organización.

Declaraciones exactas

Las verificaciones de declaraciones exactas comparan las declaraciones JWT de nivel superior sin convertir sus tipos. Una cadena solo coincide con la misma cadena, un valor booleano solo coincide con el mismo valor booleano y un número coincide con el mismo valor numérico. No se admiten listas ni objetos como valores exactos.

Por ejemplo:

12345{
  "repository": "example-company/payments",
  "ref": "refs/heads/main",
  "environment": "production"
}

No incluyas sub en el mapa de declaraciones exactas. Usa el campo de sujeto o una condición CEL. Usa CEL para verificar declaraciones anidadas del proveedor o comprobar si un valor pertenece a una lista.

Condiciones CEL

Las condiciones CEL reciben el mapa completo de declaraciones JWT verificadas en assertion y deben devolver true o false. OpenAI admite un subconjunto limitado de CEL para que la evaluación de las reglas sea predecible.

Para permitir un conjunto de sujetos exactos en una misma regla:

assertion.sub in [
  "repo:example-company/payments:environment:production",
  "repo:example-company/billing:environment:production"
]

Para exigir un repositorio específico y una de dos referencias:

assertion.repository == "example-company/payments" &&
assertion.ref in ["refs/heads/main", "refs/heads/release"]

Para leer una declaración anidada u opcional:

has(assertion.environment) &&
assertion.environment == "production"

Entre las funciones auxiliares admitidas están has, size, contains, startsWith y endsWith. No se admiten las búsquedas de coincidencias mediante expresiones regulares, las macros para recorrer colecciones como all o exists, las funciones arbitrarias ni los identificadores distintos de assertion. Usa expresiones breves y da preferencia a las verificaciones exactas cuando permitan expresar la misma política.

OpenAI rechaza el intercambio si falta una declaración, se usa una operación no admitida, el resultado no es booleano o se produce un error de evaluación.

Coincidencia de audiencias

El proveedor puede definir una audiencia esperada. Como alternativa, una regla puede definir una o varias audiencias aceptadas. Si la regla tiene una lista de audiencias, al menos uno de los valores de la declaración aud del token debe figurar en esa lista.

Usa una audiencia exclusiva para OpenAI si tu proveedor lo permite. Las reglas SPIFFE JWT-SVID deben definir una audiencia aceptada. Las reglas OIDC también deben definir una si el proveedor no tiene una audiencia propia configurada.

La verificación de audiencia y las verificaciones de identidad se aplican en conjunto. Aunque la audiencia coincida, el token debe superar todas las verificaciones configuradas de sujeto, de declaraciones exactas o de CEL.

Número de entidades de seguridad por regla

Cada regla se asocia con una sola entidad de seguridad:

many accepted external identities -> one federation rule -> one OpenAI principal

Así, las réplicas de una carga de trabajo, los trabajos o los sujetos aprobados pueden actuar en nombre del mismo usuario o de la misma cuenta de servicio. Una regla no puede seleccionar una entidad de seguridad distinta en función de las declaraciones. Crea reglas separadas si las cargas de trabajo necesitan distintas entidades de seguridad, Espacios de trabajo, alcances o períodos de vigencia de los tokens.

Varias reglas pueden tener la misma entidad de seguridad de destino. Usa reglas separadas si necesitas controlar el ciclo de vida de cada carga de trabajo de forma independiente o identificar con mayor claridad su actividad en las auditorías.

Alcances y autorización

La regla puede restringir los alcances OAuth del token de acceso que se emite. No puede otorgar permisos que la entidad de seguridad de destino o el Espacio de trabajo aún no tengan.

Si omites los alcances, OpenAI usa los alcances estándar de Codex: openid, profile, email y el acceso local de Codex. Si configuras los alcances mediante la API de administración, incluye chatgpt.workspace.feature.allow-codex-local-access.access y usa únicamente esos cuatro valores admitidos.

Primero, elige la entidad de seguridad y los permisos del Espacio de trabajo que otorguen los privilegios mínimos necesarios. Usa los alcances de la regla como una restricción adicional. El límite principal de autorización lo determinan los permisos.

Vigencia del token

Configura la vigencia del token de acceso de OpenAI entre 60 y 3600 segundos. OpenAI usa el menor de estos dos períodos:

• La vigencia restante del token de identidad de origen.
• La vigencia del token de acceso configurada en la regla.

Con una vigencia más corta, se reduce el tiempo durante el cual un token ya emitido puede seguir siendo válido después de un cambio de política, pero los intercambios son más frecuentes. Una vigencia de 10 minutos es un punto de partida práctico, a menos que tu carga de trabajo requiera un equilibrio distinto.

Protección contra la reutilización de aserciones

La protección contra la reutilización a nivel de proveedor usa la declaración jti del JWT. Si un administrador activa Impedir la reutilización de aserciones y el token contiene un jti que no está vacío, OpenAI acepta ese jti una sola vez para ese proveedor hasta que vence la aserción.

Antes de cada intercambio, la carga de trabajo debe obtener una nueva aserción con un jti nuevo. Esto también se aplica a los reintentos cuando se desconoce el resultado del intercambio anterior. Las aserciones sin jti se pueden seguir usando, pero carecen de protección contra la reutilización. Si el valor de jti está vacío, es nulo o no es una cadena, la validación falla.

Cambios, desactivación y archivado

Los cambios habituales en las verificaciones de identidad, los alcances o la vigencia del token se aplican a los nuevos intercambios. Los tokens de acceso emitidos antes del cambio pueden seguir siendo válidos hasta que termine su período de vigencia original (TTL).

Desactivar una regla o un proveedor bloquea los nuevos intercambios y revoca los tokens de acceso de OpenAI emitidos mediante esa regla o ese proveedor. El archivado tiene el mismo efecto y es irreversible. Si cambias la configuración de confianza del proveedor, por ejemplo, el emisor o la configuración de JWKS, los tokens emitidos se revocan antes de que entre en vigor la nueva configuración.

Desactiva el recurso si necesitas detener los intercambios por una emergencia o ponerlos en pausa temporalmente. Archiva el recurso solo cuando ya no lo necesites.

Límites

Crea proveedores separados para los límites de confianza que requieran controles independientes sobre el emisor, las claves, la reutilización de aserciones o el ciclo de vida. Crea reglas separadas en un mismo proveedor para las cargas de trabajo que compartan la configuración de confianza, pero requieran distintas entidades de seguridad o políticas de acceso.