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

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

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

Para conferir o procedimento de configuração, consulte Use a identidade de cargas de trabalho com o Codex. Para gerenciar regras por código, consulte a API de administração de identidade de cargas de trabalho.

Modelo de regra

A entidade de segurança e seu vínculo com o workspace devem existir antes da troca. Uma regra não cria um usuário, uma conta de serviço nem um vínculo com o workspace quando uma carga de trabalho se conecta.

Como as verificações de identidade se combinam

Uma regra pode usar estas verificações:

Configure pelo menos uma verificação de sujeito, de declaração exata ou CEL. Um público-alvo aceito, por si só, não identifica uma carga de trabalho. Se você configurar mais de um tipo de verificação, todos devem ser satisfeitos.

As verificações do provedor ocorrem primeiro. Uma regra não pode se sobrepor às verificações de emissor, assinatura, expiração, prazo de validade da asserção, reutilização de asserções ou CEL no nível do provedor.

Correspondência de sujeito

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

repo:example-company/payments:environment:production

Um * no final realiza 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 puder distinguir cargas de trabalho privilegiadas. Por exemplo, uma regra do GitHub deve corresponder a um repositório, arquivo de fluxo de trabalho, referência ou ambiente protegido, em vez de abranger todos os repositórios de uma organização.

Declarações exatas

As declarações exatas comparam declarações JWT de nível superior sem converter seus tipos. Uma string corresponde apenas à mesma string, um booleano corresponde apenas ao mesmo booleano e um número corresponde ao mesmo valor numérico. Listas e objetos não são aceitos como valores exatos.

Por exemplo:

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 CEL. Use CEL para declarações aninhadas do provedor e para verificar se um valor pertence a uma lista.

Condições CEL

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

Para permitir um conjunto de sujeitos exatos em uma regra:

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

Para exigir um repositório 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:

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

Os recursos auxiliares disponíveis incluem has, size, contains, startsWith e endsWith. Não há suporte a correspondência por expressões regulares, macros de iteração sobre coleções, como all ou exists, funções arbitrárias ou identificadores diferentes de assertion. Mantenha as expressões curtas e prefira verificações exatas quando elas puderem expressar a mesma política.

Uma declaração ausente, uma operação não compatível, um resultado não booleano ou um erro de avaliação faz com que a troca seja rejeitada.

Correspondência de público-alvo

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

Use um público-alvo dedicado à OpenAI quando seu provedor oferecer essa opção. As regras SPIFFE JWT-SVID devem definir um público-alvo aceito. Uma regra OIDC também deve definir um se o provedor não definir um público-alvo no nível do provedor.

A correspondência de público-alvo e as verificações de identidade são cumulativas. Um público-alvo correspondente não compensa uma falha na verificação de sujeito, de declaração exata ou CEL.

Cardinalidade das entidades de segurança

Uma regra é mapeada para 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, jobs ou sujeitos aprovados atuem como o mesmo usuário ou a mesma conta de serviço. Isso não permite que uma regra escolha 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, workspaces, escopos ou prazos de validade de tokens diferentes.

Mais de uma regra pode ter o mesmo principal como destino. Use regras separadas quando precisar de controles independentes de ciclo de vida ou de uma atribuição mais clara de cada carga de trabalho nos registros de auditoria.

Escopos e autorização

A regra pode restringir os escopos OAuth no token de acesso emitido. Ela não pode conceder permissões que o principal de destino ou o workspace ainda não tenha.

Quando você omite os escopos, a OpenAI usa os escopos padrão do Codex: openid, profile, email e acesso local ao Codex. Se definir escopos pela API de administração, inclua chatgpt.workspace.feature.allow-codex-local-access.access e use apenas esses quatro valores compatíveis.

Primeiro, escolha o principal e as permissões do workspace seguindo o princípio do menor privilégio. Trate os escopos da regra como uma restrição adicional, não como o principal limite de autorização.

Tempo de vida do token

Defina o tempo de vida do token de acesso da OpenAI entre 60 e 3.600 segundos. A OpenAI usa o menor dos seguintes valores:

• O tempo de vida restante do token de identidade do provedor de origem.
• O tempo de vida do token de acesso configurado na regra.

Tempos de vida mais curtos reduzem o período em que um token emitido pode continuar válido após uma alteração na política, mas aumentam a frequência das trocas. Um tempo de vida de 10 minutos é um ponto de partida prático, a menos que sua carga de trabalho precise de um equilíbrio diferente.

Proteção contra reutilização

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

A carga de trabalho deve obter uma nova asserção com um novo jti antes de cada troca, inclusive em novas tentativas após uma troca cujo resultado seja desconhecido. Asserções sem jti continuam utilizáveis, mas não recebem proteção contra reutilização. Valores de jti vazios, nulos ou que não sejam strings não passam na validação.

Alterações, desativação e arquivamento

Alterações comuns nas verificações de identidade, nos escopos ou no tempo de vida do token se aplicam às novas trocas. Os tokens de acesso emitidos antes da alteração podem continuar válidos até o fim do TTL já definido.

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 não pode ser desfeito. Alterar a configuração de confiança do provedor, como as configurações do emissor ou de JWKS, revoga os tokens emitidos antes que a nova configuração de confiança entre em vigor.

Use a desativação para uma interrupção de emergência ou uma pausa temporária. Arquive um recurso somente quando não precisar mais dele.

Limites

Crie provedores separados para limites de confiança que precisem de controles independentes de emissor, chaves, reutilização ou ciclo de vida. Crie regras separadas em um mesmo provedor para cargas de trabalho que compartilhem a mesma confiança, mas precisem de principais ou políticas de acesso diferentes.