Referencia de reglas de federación de Codex

Una regla de federación determina qué identidades de carga de trabajo verificadas pueden actuar como un usuario o una cuenta de servicio de ChatGPT. OpenAI evalúa únicamente la regla que especifica el proceso de Codex. No busca coincidencias en todas las reglas.

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

Para conocer el procedimiento de configuración, consulta Usar la identidad de carga de trabajo con Codex. Para administrar reglas mediante código, consulta la API de administración de identidades de carga de trabajo.

Modelo de reglas

La entidad de seguridad debe existir y pertenecer al espacio de trabajo antes del intercambio. Una regla no crea un usuario, una cuenta de servicio ni una membresía cuando se conecta una carga de trabajo.

Cómo se combinan las comprobaciones de identidad

Una regla puede usar estas comprobaciones:

Configura al menos una comprobación de sujeto, de declaración exacta o de CEL. Una audiencia aceptada por sí sola no identifica una carga de trabajo. Si configuras más de un tipo de comprobación, todas deben superarse.

La verificación del proveedor se realiza primero. Una regla no puede anular las comprobaciones del proveedor relativas al emisor, la firma, el vencimiento, el tiempo de vida de la aserción, la reutilización ni las comprobaciones CEL a nivel del proveedor.

Coincidencia de sujetos

Usa un sujeto exacto siempre que un 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 estar precedido por un prefijo no vacío. OpenAI no acepta *, repo:*:production ni repo/*/main.

No uses un prefijo amplio cuando una declaración más estable permita distinguir las cargas de trabajo con privilegios. Por ejemplo, una regla de GitHub debería buscar coincidencias con un repositorio, un archivo de flujo de trabajo, una referencia o un entorno protegido, en lugar de todos los repositorios de una organización.

Declaraciones exactas

Las comprobaciones de declaraciones exactas comparan las declaraciones JWT de nivel superior sin convertir sus tipos. Una cadena solo coincide con la misma cadena, un booleano solo coincide con el mismo 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 CEL. Usa CEL para las declaraciones anidadas del proveedor y para comprobar la pertenencia a listas.

Condiciones CEL

Las condiciones CEL reciben el mapa completo de declaraciones JWT verificadas como 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 regla:

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

Para exigir un repositorio 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 se incluyen has, size, contains, startsWith y endsWith. No se admiten las coincidencias mediante expresiones regulares, las macros de iteración sobre colecciones como all o exists, las funciones arbitrarias ni los identificadores distintos de assertion. Mantén las expresiones breves y da preferencia a las comprobaciones exactas cuando permitan expresar la misma política.

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, se rechaza el intercambio.

Coincidencia de audiencias

El proveedor puede establecer una audiencia esperada. Como alternativa, una regla puede establecer una o más audiencias aceptadas. Cuando una regla tiene una lista de audiencias, al menos un valor de la declaración aud del token debe aparecer en esa lista.

Usa una audiencia dedicada a OpenAI cuando tu proveedor lo admita. Las reglas JWT-SVID de SPIFFE deben establecer una audiencia aceptada. Una regla OIDC también debe establecerla si el proveedor no define una audiencia a nivel del proveedor.

La coincidencia de audiencias y las comprobaciones de identidad son acumulativas. Una audiencia coincidente no compensa una comprobación de sujeto, de declaración exacta o de CEL que no se supere.

Cardinalidad de las entidades de seguridad

Una regla se asocia con exactamente una entidad de seguridad:

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

Esto permite que réplicas de cargas de trabajo, trabajos o sujetos aprobados actúen como el mismo usuario o la misma cuenta de servicio. No permite que una regla elija una entidad de seguridad diferente en función de las declaraciones. Crea reglas separadas cuando las cargas de trabajo necesiten distintas entidades de seguridad, espacios de trabajo, ámbitos o tiempos de vida de los tokens.

Varias reglas pueden tener como destino la misma entidad de seguridad. Usa reglas separadas cuando necesites controles independientes del ciclo de vida o una atribución más clara de cada carga de trabajo en las auditorías.

Ámbitos y autorización

La regla puede restringir los ámbitos de OAuth del token de acceso emitido. No puede otorgar permisos que la entidad de seguridad de destino o el espacio de trabajo no tengan ya.

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

Primero, elige la entidad de seguridad y los permisos del espacio de trabajo con los privilegios mínimos necesarios. Considera los ámbitos de la regla como una restricción adicional, no como el límite principal de autorización.

Tiempo de vida del token

Establece el tiempo de vida del token de acceso de OpenAI entre 60 y 3600 segundos. OpenAI usa el menor de los siguientes valores:

• El tiempo de vida restante del token de identidad del proveedor externo.
• El tiempo de vida del token de acceso configurado en la regla.

Los tiempos de vida más cortos reducen el tiempo durante el cual un token emitido puede seguir siendo válido después de modificar una política, pero aumentan la frecuencia de los intercambios. Un tiempo de vida de 10 minutos es un punto de partida práctico, a menos que tu carga de trabajo necesite un equilibrio diferente.

Protección contra la repetición

La protección contra la repetición a nivel de proveedor usa la declaración jti del JWT. Cuando un administrador activa Impedir la repetición de aserciones y el token tiene un jti no vacío, OpenAI acepta ese jti una sola vez para ese proveedor hasta que venza la aserción.

La carga de trabajo debe obtener una nueva aserción con un nuevo jti antes de cada intercambio, incluidos los reintentos posteriores a un intercambio cuyo resultado se desconoce. Las aserciones sin jti se pueden seguir usando, pero no cuentan con protección contra la repetición. Los valores de jti vacíos, nulos o que no sean cadenas no pasan la validación.

Cambios, desactivación y archivado

Los cambios habituales en las verificaciones de identidad, los ámbitos o el tiempo de vida del token se aplican a los nuevos intercambios. Los tokens de acceso emitidos antes del cambio pueden seguir siendo válidos hasta que venza su TTL actual.

Desactivar una regla o un proveedor bloquea los nuevos intercambios y revoca los tokens de acceso de OpenAI emitidos a través de esa regla o ese proveedor. Archivarlos tiene el mismo efecto y no se puede deshacer. Cambiar la configuración de confianza del proveedor, como la del emisor o la de JWKS, revoca los tokens emitidos antes de que se active la nueva configuración de confianza.

Usa la desactivación para una detención de emergencia o una pausa temporal. Archiva un recurso solo cuando ya no lo necesites.

Límites

Crea proveedores separados para los límites de confianza que necesiten controles independientes del emisor, las claves, la repetición 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 necesiten distintas entidades de seguridad o políticas de acceso.