Referência das regras de federação do Codex

Uma regra de federação determina quais identidades verificadas de cargas de trabalho podem atuar como um único usuário ou uma única conta de serviço do ChatGPT. A OpenAI avalia apenas a regra indicada pelo processo do Codex. Ela não percorre todas as regras em busca de uma correspondência.

Cada regra tem uma única entidade de segurança de destino e pode aceitar uma ou mais identidades de origem. Para aceitar um conjunto de sujeitos na mesma regra, use um prefixo de sujeito com um curinga no final ou uma condição CEL. Você também pode criar várias regras para a mesma entidade de segurança.

Modelo de regra

Antes da troca de tokens, a entidade de segurança já deve existir e fazer parte do espaço de trabalho. Quando uma carga de trabalho se conecta, a regra não cria usuários, contas de serviço nem vínculos com o espaço de trabalho.

Como as verificações de identidade se combinam

Uma regra pode usar as verificações a seguir.

Configure pelo menos uma verificação de sujeito, de declaração exata ou de condição CEL. O público aceito, por si só, não identifica uma carga de trabalho. Se você configurar mais de um tipo de verificação, o token deverá passar por todos eles.

A verificação do provedor ocorre primeiro. A regra não pode ignorar as verificações do provedor relativas ao emissor, à assinatura, à expiração, ao período de validade da asserção, à reutilização da asserção ou às condições CEL definidas no provedor.

Correspondência de sujeitos

Use um sujeito exato sempre que um valor estável de sub identificar a carga de trabalho.

repo:example-company/payments:environment:production

Um único * no final indica uma correspondência por prefixo.

system:serviceaccount:production:codex-*

O curinga deve ser o último caractere e vir após um prefixo não vazio. A OpenAI não aceita *, repo:*:production nem repo/*/main.

Não use um prefixo amplo quando uma declaração mais estável permitir distinguir cargas de trabalho privilegiadas. Por exemplo, uma regra do GitHub deve identificar um repositório, um arquivo de fluxo de trabalho, uma referência ou um ambiente protegido. Evite regras que aceitem todos os repositórios de uma organização.

Declarações exatas

A verificação de declarações exatas compara declarações JWT de nível superior sem converter seus tipos. Uma string só corresponde a uma string idêntica, um booleano só corresponde ao mesmo valor booleano e um número corresponde ao mesmo valor numérico. A verificação não aceita listas nem objetos como valores exatos.

Exemplo de mapa de declarações exatas:

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

Não inclua sub no mapa de declarações exatas. Use o campo de sujeito ou uma condição CEL. Use CEL para verificar declarações aninhadas do provedor ou testar se um valor pertence a uma lista.

Condições CEL

As condições CEL recebem o mapa completo de declarações verificadas do JWT em assertion e devem retornar true ou false. A OpenAI oferece suporte a um subconjunto limitado de CEL para manter a avaliação das regras previsível.

Para permitir um conjunto de sujeitos exatos na mesma regra, use uma condição como esta.

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

A condição a seguir exige um repositório específico e uma de duas referências.

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

Para ler uma declaração aninhada ou opcional, use uma condição como esta.

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

Entre os recursos disponíveis estão has, size, contains, startsWith e endsWith. A OpenAI não oferece suporte a correspondência por expressão regular, macros que percorrem coleções, como all ou exists, funções arbitrárias nem identificadores diferentes de assertion. Use expressões curtas e prefira verificações exatas quando elas puderem expressar a mesma política.

A OpenAI rejeita a troca se uma declaração estiver ausente, se a operação não tiver suporte, se o resultado não for booleano ou se ocorrer um erro de avaliação.

Correspondência de públicos

O provedor pode definir um público esperado. Como alternativa, a regra pode definir um ou mais públicos aceitos. Quando a regra tem uma lista de públicos, pelo menos um valor da declaração aud do token deve constar nessa lista.

Use um público exclusivo para a OpenAI quando o provedor oferecer essa opção. As regras SPIFFE JWT-SVID devem definir um público aceito. Uma regra OIDC também deve definir um público aceito se o provedor não definir um público em sua própria configuração.

A verificação de público e as verificações de identidade são cumulativas. Mesmo que o público corresponda, o token também deve passar por todas as verificações configuradas de sujeito, de declaração exata ou de condição CEL.

Número de entidades de segurança por regra

Cada regra corresponde a exatamente uma entidade de segurança.

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

Isso permite que réplicas de cargas de trabalho, tarefas ou sujeitos aprovados atuem como o mesmo usuário ou a mesma conta de serviço. Uma regra não pode escolher uma entidade de segurança diferente com base nas declarações. Crie regras separadas quando as cargas de trabalho precisarem de entidades de segurança, espaços de trabalho, escopos ou períodos de validade de token diferentes.

Várias regras podem ter a mesma entidade de segurança como destino. Use regras separadas quando precisar controlar o ciclo de vida de cada carga de trabalho de forma independente ou identificar com mais clareza, em uma auditoria, qual carga de trabalho realizou cada ação.

Escopos e autorização

A regra pode restringir os escopos OAuth do token de acesso emitido. Ela não pode conceder permissões que a entidade de segurança de destino ou o espaço de trabalho ainda não tenham.

Se você omitir os escopos, a OpenAI usará os escopos padrão do Codex: openid, profile, email e acesso local ao Codex. Se definir os escopos pela API de administração, inclua chatgpt.workspace.feature.allow-codex-local-access.access e use apenas valores dentre os quatro permitidos.

Primeiro, escolha a entidade de segurança e as permissões do espaço de trabalho seguindo o princípio do menor privilégio. Use os escopos da regra como uma restrição adicional. As permissões da entidade e do espaço de trabalho definem o limite principal de autorização.

Validade do token

Defina a validade do token de acesso da OpenAI entre 60 e 3.600 segundos. A OpenAI usa o menor dos dois períodos a seguir.

• O tempo de validade restante do token de identidade de origem.
• O período de validade do token de acesso configurado na regra.

Uma validade mais curta reduz o tempo que um token já emitido pode continuar válido após uma alteração na política, mas exige trocas mais frequentes. Comece com 10 minutos, a menos que sua carga de trabalho exija outro equilíbrio entre validade e frequência de troca.

Proteção contra reutilização de asserções

A proteção contra reutilização no provedor usa a declaração jti do JWT. Quando um administrador ativa Impedir a reutilização de asserções e o token contém um jti não vazio, a OpenAI aceita esse jti uma única vez para aquele provedor até que a asserção expire.

Antes de cada troca, a carga de trabalho deve obter uma nova asserção com um novo jti. Isso também vale para novas tentativas após uma troca cujo resultado seja desconhecido. Asserções sem jti continuam válidas para troca, mas não têm proteção contra reutilização. Se o valor de jti estiver vazio, for nulo ou não for uma string, a validação falhará.

Alterações, desativação e arquivamento

Alterações comuns nas verificações de identidade, nos escopos ou na validade do token se aplicam às novas trocas. Tokens de acesso emitidos antes da alteração podem continuar válidos até o fim do prazo de validade (TTL) original.

Desativar uma regra ou um provedor bloqueia novas trocas e revoga os tokens de acesso da OpenAI emitidos por meio desse recurso. O arquivamento tem o mesmo efeito e é irreversível. Alterar as configurações de confiança do provedor, como as do emissor ou do JWKS, revoga os tokens emitidos antes que a nova configuração entre em vigor.

Desative o recurso quando precisar interromper as trocas em uma emergência ou pausá-las temporariamente. Arquive o recurso apenas quando não precisar mais dele.

Limites

Crie provedores separados para domínios de confiança que precisem de controles independentes de emissor, chaves, reutilização de asserções ou ciclo de vida. Crie regras separadas no mesmo provedor para cargas de trabalho que compartilhem a mesma configuração de confiança, mas precisem de entidades de segurança ou políticas de acesso diferentes.