Federação de identidades de cargas de trabalho

A federação de identidades de cargas de trabalho permite que a automatização fidedigna utilize o Codex sem armazenar um token de acesso pessoal ou outra credencial OpenAI de longa duração. A sua carga de trabalho apresenta um token de identidade de curta duração de um fornecedor que já utiliza. A OpenAI verifica esse token e devolve um token de acesso de curta duração para um utilizador ou uma conta de serviço no seu espaço de trabalho ChatGPT gerido.

Utilize a identidade da carga de trabalho para processos Codex não assistidos em plataformas de cloud, Kubernetes, sistemas de CI e outros ambientes capazes de emitir tokens OIDC ou SPIFFE JWT-SVIDs. Para consultar o modelo de confiança partilhada e o fluxo separado da OpenAI API, consulte a descrição geral da identidade da carga de trabalho.

Antes de começar

Necessita de:

• Permissão para gerir identidades de cargas de trabalho no OpenAI Admin Portal.
• Um espaço de trabalho ChatGPT gerido.
• Um utilizador ou uma conta de serviço ChatGPT que seja membro ativo desse espaço de trabalho, ou permissão para criar um durante a configuração.
• Um token OIDC ou SPIFFE JWT-SVID cujo emissor, público e declarações de identificação conheça.
• Um ambiente de execução que consiga manter esse token atualizado num ficheiro protegido com um caminho absoluto.
• Codex 0.148.0 ou posterior.
• Uma política efetiva de autenticação do Codex que permita a autenticação do ChatGPT e o espaço de trabalho selecionado pela regra de federação. Consulte Impor um método de início de sessão ou espaço de trabalho.

A OpenAI não cria uma entidade principal nem uma associação ao espaço de trabalho durante a troca de tokens. Um administrador seleciona ou cria a entidade principal antes de a carga de trabalho se ligar. A criação de um utilizador humano ocupa um lugar no espaço de trabalho e segue as regras de associação desse espaço de trabalho.

No Windows nativo, utilize a sandbox do Windows elevada. Os outros modos de sandbox do Windows não conseguem proteger o ficheiro do token de identidade contra comandos controlados pelo modelo.

Obtenha um token de identidade

O ambiente de execução da sua carga de trabalho obtém e atualiza o token de identidade a montante. O Codex não chama serviços de metadados de cloud nem bibliotecas de cliente do fornecedor de identidade em seu nome.

Siga o guia do seu fornecedor para configurar a emissão de tokens e inspecionar um token de exemplo:

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

Descodifique localmente um token de exemplo e registe os respetivos iss, aud, sub e quaisquer outras declarações em que pretenda confiar. A descodificação não verifica a assinatura. Não cole um token de produção num site nem o escreva em registos.

Ligue a carga de trabalho

Um administrador cria o fornecedor e a regra de federação antes de iniciar o Codex.

1. Abra Workload identity no OpenAI Admin Portal e, em seguida, selecione Connect workload.
2. Reutilize um fornecedor configurado para o Codex ou crie um. As predefinições de fornecedores preenchem as definições comuns para GitHub Actions, Microsoft Entra ID, Google Cloud, AWS, Kubernetes, SPIFFE e fornecedores OIDC personalizados.
3. Selecione Codex e o espaço de trabalho gerido que a carga de trabalho pode utilizar.
4. Adicione as condições mais restritas que identificam a carga de trabalho. Faça a correspondência de um assunto, declarações exatas, uma condição CEL ou uma combinação. Adicione públicos aceites para restringir os tokens que a regra aceita. Todos os critérios de correspondência configurados têm de ser satisfeitos.
5. Associe a regra a um utilizador ou conta de serviço ChatGPT existente ou crie um durante a configuração.
6. Reveja o fornecedor, as condições, o espaço de trabalho, a entidade principal, os âmbitos e a duração do token de acesso. Selecione Connect workload e, em seguida, Download config.

O ficheiro transferido contém um ID não secreto da regra de federação e o caminho onde o Codex lerá o token de identidade. Não contém uma credencial.

Para automatizar a configuração, utilize a Admin API de identidade de cargas de trabalho. Para obter informações sobre o comportamento dos critérios de correspondência e exemplos, consulte a Referência de regras de federação.

Configure o processo Codex

O processo que inicia o Codex requer estas duas variáveis de identidade da carga de trabalho:

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

OPENAI_FEDERATION_RULE_ID não é um segredo. O ficheiro de tokens é. Utilize um caminho absoluto num diretório dedicado, como /var/run/secrets/openai.com, pertencente à conta da carga de trabalho com o modo 0700. Apenas processos anfitriões fidedignos devem escrever nesse local. Mantenha o diretório fora dos repositórios e de outros caminhos disponíveis para as ferramentas do Codex. Mantenha as credenciais fora dos registos, do histórico da shell e dos artefactos de compilação.

Adicione atribuição de auditoria

Quando as instâncias do ambiente de execução partilham uma regra de federação, pode identificar cada instância nos eventos de auditoria da emissão de tokens. Defina a variável opcional OPENAI_WORKLOAD_IDENTITY_CONTEXT como um objeto JSON codificado numa cadeia de carateres:

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

O objeto requer instance_id. Também pode conter display_name e até oito etiquetas. O objeto codificado pode ter até 1 024 bytes. instance_id e display_name podem ter até 128 carateres. As chaves das etiquetas podem ter até 64 carateres e os valores das etiquetas podem ter até 256 carateres.

Os identificadores têm de começar por uma letra ou um número ASCII. Em seguida, os valores podem conter letras, números, ., _, :, /, @ e -. As chaves das etiquetas suportam letras, números, ., _ e -.

A OpenAI trata este contexto como atribuição de auditoria comunicada pelo cliente, não como identidade verificada da carga de trabalho. Este não afeta a autenticação, a autorização, a correspondência de regras, os âmbitos, os limites de frequência, a revogação, as restrições de funcionalidades nem as métricas. Não inclua credenciais, segredos, dados pessoais, pedidos, resultados do modelo ou outro Customer Content neste contexto.

Para um contexto válido, a OpenAI deriva um ID de atribuição estável limitado ao inquilino, ao fornecedor, à regra de federação e a instance_id. Para efeitos de atribuição, o token de acesso contém o ID, mas não o contexto. O evento de auditoria de emissão de token bem-sucedida contém o ID e o contexto normalizado. Um contexto que exceda um limite ou viole este esquema faz com que a troca falhe com invalid_grant.

O Codex lê o contexto quando o processo é iniciado e não o transmite, nem transmite o ID da regra ou o caminho do ficheiro de tokens, a shells, hooks ou servidores MCP controlados pelo modelo. Reinicie o Codex depois de alterar o contexto.

Proteja e efetue a rotação do ficheiro de tokens

Para implementações geridas em Linux, macOS e WSL, adicione todo o diretório de tokens a permissions.filesystem.deny_read nos requisitos geridos:

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

Isto impede que comandos controlados pelo modelo leiam o token ativo ou uma substituição temporária, enquanto o processo anfitrião do Codex continua a poder utilizar o token para a troca. Para volumes de tokens projetados, bloqueie todo o ponto de montagem do token e quaisquer caminhos de destino subjacentes ou resolvidos fora deste. Os modos de ficheiro e a remoção de variáveis de ambiente, por si só, não protegem as credenciais de outro processo executado como o mesmo utilizador. No Windows nativo, utilize a sandbox elevada descrita acima.

Para origens de tokens que não projetem um ficheiro, faça com que um processo anfitrião fidedigno escreva cada substituição nesse diretório protegido e mude o respetivo nome no local. Uma mudança de nome atómica impede o Codex de ler um token parcial. Por exemplo, adapte este script de atualização pertencente ao anfitrião ao comando de tokens do seu fornecedor. Aprovisione o diretório antes de executar o 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"

Execute o processo de atualização fora de qualquer shell ou ferramenta que o Codex possa controlar. Mantenha o bloqueio de leitura durante a atualização e a limpeza. Mesmo que uma paragem forçada deixe um ficheiro temporário, esse ficheiro tem de permanecer dentro do diretório bloqueado. Não coloque definições da identidade da carga de trabalho em config.toml.

Verifique a ligação

Carregue o ambiente transferido e inspecione o método de autenticação selecionado:

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

No PowerShell:

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

Uma verificação bem-sucedida apresenta Logged in using workload identity. Isto confirma que o Codex trocou um token através da regra de federação configurada. O comando não apresenta o espaço de trabalho, a entidade principal ou a regra resolvidos. Confirme esses valores no Admin Portal antes de iniciar a carga de trabalho. Se o Codex indicar outro método de autenticação, as duas variáveis WIF obrigatórias não chegaram ao processo.

Se o fornecedor utilizar Prevent assertion replay e a asserção tiver uma declaração jti, esta verificação consome esse jti. Escreva uma asserção recém-emitida com um novo jti antes de iniciar outro processo Codex.

Execute um pequeno pedido no mesmo ambiente:

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

O Codex troca o token a montante e mantém o token de acesso da OpenAI na memória. Não escreve nenhuma das credenciais em auth.json, no porta-chaves do sistema ou em config.toml.

Mantenha o token atualizado

Atualize o ficheiro do token de identidade antes de o token a montante expirar. O Codex volta a ler o ficheiro quando necessita de outro token de acesso da OpenAI. O token da OpenAI expira no primeiro destes momentos: a expiração do token a montante ou o fim da duração da regra de federação; nunca dura mais de uma hora.

Quando um administrador ativa a proteção contra repetição, cada JWT a montante tem de ter um jti exclusivo. Escreva uma asserção recém-emitida com um novo jti antes de cada troca, incluindo as atualizações num processo de longa duração. As asserções sem jti não recebem proteção contra repetição.

O Codex partilha uma sessão de troca na memória em cada processo anfitrião. Os pedidos simultâneos nesse processo reutilizam um token de acesso da OpenAI válido e partilham uma atualização quando este expira. Os processos separados efetuam trocas separadas, pelo que necessitam de asserções que o fornecedor lhes permita utilizar.

Precedência das credenciais

As duas variáveis obrigatórias da identidade da carga de trabalho têm precedência sobre todas as outras origens de credenciais:

1. Se OPENAI_FEDERATION_RULE_ID ou OPENAI_IDENTITY_TOKEN_FILE estiver presente, o Codex seleciona a identidade da carga de trabalho.
2. Se estiver presente apenas uma variável obrigatória, o Codex devolve um erro. Não recorre a uma API key, a um token de acesso nem a um início de sessão armazenado.
3. OPENAI_WORKLOAD_IDENTITY_CONTEXT, por si só, não seleciona a identidade da carga de trabalho.
4. Quando nenhuma das variáveis WIF obrigatórias está presente, o Codex aplica as regras normais de credenciais para essa superfície. Para as superfícies que permitem autenticação por API key, CODEX_API_KEY tem precedência em codex exec, codex review, no TypeScript SDK e em codex exec-server --remote. Outras superfícies podem utilizar CODEX_ACCESS_TOKEN ou um início de sessão armazenado.

Uma opção apiKey do SDK torna-se CODEX_API_KEY, mas a WIF continua a ter precedência quando qualquer uma das variáveis WIF obrigatórias está presente. Omita a opção quando utilizar WIF para que a carga de trabalho não transporte uma credencial de longa duração não utilizada.

Para migrar uma carga de trabalho existente sem interrupção, configure a WIF enquanto a credencial atual ainda estiver disponível. Inicie um novo processo com ambas as variáveis WIF obrigatórias; a WIF tem precedência mesmo que a credencial antiga continue presente. Depois de a carga de trabalho funcionar corretamente com WIF, remova a credencial antiga do respetivo ambiente de execução e ficheiro de segredos e, em seguida, revogue-a. Antes da revogação, pode reverter removendo ambas as variáveis WIF obrigatórias e iniciando um novo processo.

Superfícies Codex suportadas

Configure a identidade da carga de trabalho na máquina que aloja o processo Codex.

Os clientes remotos do servidor da aplicação e do servidor de execução nunca enviam o token de identidade a montante através dos respetivos protocolos.

Altere ou remova o acesso

As alterações aos assuntos, públicos, declarações, à condição CEL, aos âmbitos ou à duração do token de uma regra aplicam-se a novas trocas. Um token emitido antes da alteração pode permanecer válido até ao fim da respetiva duração.

Desative um fornecedor ou uma regra para interromper imediatamente o acesso. A desativação bloqueia novas trocas e revoga os tokens de acesso da OpenAI já emitidos através desse recurso. O arquivamento tem o mesmo efeito no acesso e não pode ser anulado. A alteração da confiança no fornecedor também revoga os tokens emitidos antes de a nova confiança entrar em vigor.

Audite as alterações

A criação, as atualizações e o arquivamento de fornecedores e regras de federação geram eventos de auditoria. Utilize a Compliance API e as orientações sobre eventos de auditoria para exportar os eventos suportados pelo seu espaço de trabalho. Correlacione-os com os registos de emissão do seu fornecedor de identidade e não registe as asserções a montante nem os tokens de acesso da OpenAI em nenhum dos sistemas.

Quando o processo fornece OPENAI_WORKLOAD_IDENTITY_CONTEXT, os eventos de auditoria de emissão de tokens bem-sucedida também contêm o ID de atribuição estável e o contexto normalizado descrito acima.

Resolva problemas

Para obter detalhes sobre a verificação de fornecedores, os limites e CEL, consulte a referência de regras de federação.