Federação de identidades de cargas de trabalho

A federação de identidades de cargas de trabalho permite que uma carga de trabalho confiável use uma identidade que já possui, em vez de armazenar uma chave da API OpenAI ou uma credencial do ChatGPT. A carga de trabalho apresenta um token de curta duração do seu provedor de identidade, e a OpenAI o troca por um token de acesso à OpenAI de curta duração.

As cargas de trabalho da API OpenAI também podem trocar uma identidade de certificado verificada por meio da federação de identidades de cargas de trabalho X.509.

Você pode usar a federação de identidades de cargas de trabalho com a API OpenAI ou o Codex:

As duas opções usam o mesmo modelo de confiança, mas diferem na administração e na configuração em tempo de execução. Comece pelos conceitos compartilhados e pelas orientações sobre provedores de identidade abaixo. Depois, siga a seção do produto que sua carga de trabalho usa.

• API OpenAI: Continue em Use a identidade de cargas de trabalho com a API OpenAI.
• Codex: Siga Use a identidade de cargas de trabalho com o Codex para concluir a configuração no Portal de Administração e em tempo de execução.

Os administradores também podem gerenciar provedores e regras do Codex com a API de Administração. Consulte a referência de regras de federação do Codex para entender o comportamento das regras e do ciclo de vida.

Como funciona

Um administrador configura três elementos antes de a carga de trabalho se conectar:

1. Um provedor de identidade informa à OpenAI em qual emissor externo confiar e como verificar seus tokens assinados ou identidades de certificado.
2. Uma regra de acesso descreve quais atributos de token a OpenAI aceita e qual identidade da OpenAI a carga de trabalho pode assumir. Na configuração da API OpenAI, isso é chamado de mapeamento de conta de serviço. Na configuração do Codex, é chamado de regra de federação.
3. Uma entidade de segurança da OpenAI recebe o acesso resultante. Para a API OpenAI, essa entidade é uma conta de serviço da Plataforma. Para o Codex, é um usuário ou uma conta de serviço do ChatGPT em um workspace gerenciado.

Em tempo de execução:

1. A carga de trabalho recebe um OIDC JWT ou SPIFFE JWT-SVID de curta duração, ou uma carga de trabalho da API OpenAI apresenta um certificado X.509.
2. A carga de trabalho apresenta sua identidade externa com os IDs exigidos pelo produto que usa.
3. A OpenAI verifica o token ou certificado e, em seguida, avalia o mapeamento ou a regra configurada.
4. A OpenAI retorna um token de acesso de curta duração para a entidade de segurança mapeada.

A troca de tokens nunca cria uma entidade de segurança, um projeto ou um vínculo de membro com um workspace. Os administradores criam ou selecionam esses recursos durante a configuração.

Obtenha um token de identidade

Escolha o guia do ambiente em que sua carga de trabalho é executada:

A OpenAI oferece suporte a tokens de sujeito JWT compatíveis com OIDC nas configurações documentadas, incluindo SPIFFE JWT-SVIDs. Para a API OpenAI, entre em contato com o suporte da OpenAI se o seu provedor OIDC não estiver listado. Para o Codex, escolha OIDC personalizado no Portal de Administração da OpenAI.

Cada guia de provedor OIDC explica como emitir e inspecionar um token. Para o Codex, siga apenas essas etapas de emissão de tokens e depois volte para Use a identidade de cargas de trabalho com o Codex. As instruções de configuração da OpenAI e os exemplos de SDK desses guias se aplicam à opção da API OpenAI. A federação X.509 oferece suporte apenas à opção da API OpenAI.

Use a identidade de cargas de trabalho com a API OpenAI

Use esta opção quando sua carga de trabalho chamar a API OpenAI diretamente. Você precisa de permissão para gerenciar provedores de identidade de cargas de trabalho e mapeamentos de contas de serviço da organização.

Acesse Configurações da organização > Segurança > Provedor de identidade de cargas de trabalho. Crie primeiro o provedor e depois configure seus mapeamentos de contas de serviço na página de detalhes do provedor.

Provedores X.509

Um provedor X.509 deriva atributos de identidade de cargas de trabalho de um certificado de cliente que a OpenAI verifica com base na configuração de TLS mútuo existente da sua organização. Ele não armazena certificados nem mantém um repositório de confiança separado.

Antes de criar o provedor, configure e ative o certificado confiável que serve de âncora de confiança para seu certificado de cliente em Configurações da organização > Segurança > TLS mútuo. O guia de TLS mútuo explica as permissões, os requisitos de certificado, o escopo de ativação, os hosts mTLS, o comportamento da cadeia de certificados, os filtros CEL e a rotação.

Em seguida, crie o provedor X.509, derive um valor não vazio de openai.subject e mapeie essa identidade para uma conta de serviço do projeto com apenas as permissões necessárias para a carga de trabalho. A carga de trabalho apresenta seu certificado ao endpoint de tokens X.509 para obter um token de portador de curta duração. Depois, envia o token de portador e um certificado de cliente aceito ao endpoint mTLS da API.

Siga o guia de configuração de certificados X.509 para conhecer o fluxo completo no painel e nas requisições.

Configure um provedor de identidade de cargas de trabalho OIDC

Crie um provedor de identidade de cargas de trabalho para cada emissor externo em que você confia. A identidade de cargas de trabalho da API da OpenAI oferece suporte a tokens de sujeito JWT OIDC. Sua configuração inclui:

A descoberta OIDC personalizada e o JWKS enviado são mutuamente exclusivos. Habilitar a descoberta personalizada oculta a opção de JWKS enviado. A URL de descoberta personalizada deve usar HTTPS público e não pode conter credenciais, porta personalizada, parâmetros de consulta ou fragmento.

Se Usar URL personalizada para descoberta OIDC não aparecer no seu painel, use a descoberta OIDC padrão ou habilite Usar JWKS enviado para verificação de tokens como alternativa. Use o JWKS público publicado pelo seu provedor de identidade e atualize-o quando o provedor fizer a rotação das chaves de assinatura.

Quando o emissor do token e o host de descoberta forem diferentes, defina URL do emissor OIDC como o valor da declaração iss do token e URL de descoberta OIDC personalizada como o host que publica o documento de descoberta do provedor. A OpenAI continua verificando o token em relação ao emissor configurado; a URL personalizada determina apenas de onde são obtidos os metadados de descoberta e as chaves públicas de assinatura.

Transforme declarações de tokens com CEL

As transformações de atributos usam Common Expression Language (CEL). A OpenAI oferece suporte aos operadores CEL padrão especificados em langdef.md e não adiciona funções personalizadas de federação de identidades de cargas de trabalho. Cada expressão recebe um objeto raiz:

• assertion: o conjunto de declarações JWT verificadas.

O painel aplica automaticamente o prefixo openai.. Insira o sufixo, como subject, e uma expressão, como assertion.sub. A API armazena o atributo derivado como openai.subject.

12345678910[
  {
    "attribute": "openai.subject",
    "expression": "assertion.sub"
  },
  {
    "attribute": "openai.repository",
    "expression": "assertion.repository"
  }
]

Use a sintaxe CEL definida pela especificação da linguagem CEL. Por exemplo, você pode ler valores de declarações com expressões como assertion.sub ou assertion.repository. Sintaxe ou funções sem suporte causam falha na resolução do mapeamento.

12345678910[
  {
    "attribute": "openai.repository_ref",
    "expression": "assertion.repository + \"@\" + assertion.ref"
  },
  {
    "attribute": "openai.production",
    "expression": "assertion.ref == \"refs/heads/main\""
  }
]

Os resultados das transformações devem ser valores escalares: strings, valores true ou false, inteiros ou números finitos. Arrays, objetos, valores nulos e erros de avaliação causam falha na resolução do mapeamento. A OpenAI converte os resultados escalares das transformações em strings antes de compará-los com os valores do mapeamento. Por exemplo, true se torna "true" e 7 se torna "7".

Chaves de mapeamento que começam com openai. são resolvidas apenas a partir de transformações de atributos. Declarações brutas do token de sujeito que já usam o prefixo openai. não afetam as decisões de mapeamento, a menos que você configure uma transformação correspondente.

Gerencie o JWKS e a rotação de chaves

A OpenAI verifica os tokens de sujeito OIDC com a fonte de chaves configurada no provedor de identidade de cargas de trabalho:

• Descoberta OIDC: a OpenAI busca o documento /.well-known/openid-configuration do emissor e depois acessa o jwks_uri descoberto. A OpenAI armazena em cache os documentos de descoberta e os conteúdos de JWKS remotos por 600 segundos.
• Descoberta OIDC personalizada: a OpenAI busca /.well-known/openid-configuration na URL base de descoberta personalizada configurada e depois acessa o jwks_uri descoberto. A declaração iss do token ainda deve corresponder à URL do emissor OIDC.
• Atualização de chaves quando não encontradas: se o kid de um token não for encontrado no JWKS em cache, a OpenAI atualiza o JWKS e tenta fazer a busca novamente antes de rejeitar o token.
• JWKS enviado: quando Usar JWKS enviado para verificação de tokens está habilitado, a OpenAI usa o JWKS enviado armazenado no provedor e não realiza a descoberta OIDC nem busca JWKS remotos. Depois que uma atualização do provedor fica disponível para a troca de tokens, as novas trocas usam o JWKS salvo.
• Conjuntos de chaves: um JWKS pode conter mais de uma chave pública. Cada chave deve ter um kid exclusivo e não vazio.

Durante a rotação de chaves de assinatura, publique as chaves públicas antigas e novas no JWKS do emissor durante a janela de rotação. Isso permite que os tokens assinados com a chave antiga continuem funcionando enquanto a OpenAI aceita tokens assinados com a nova chave. Para JWKS enviados, atualize o provedor antes de emitir tokens com o novo kid; a OpenAI rejeita tokens assinados com uma chave ausente do JWKS configurado.

Configure um mapeamento de conta de serviço

Um mapeamento de conta de serviço define quais identidades externas podem gerar tokens de acesso para uma conta de serviço da OpenAI.

Para provedores X.509, as chaves de mapeamento usam atributos openai.* derivados. Prefira um mapeamento exato de openai.subject. Declarações JWT brutas, como sub, aud e iss, se aplicam apenas a provedores OIDC.

Sua configuração inclui:

Os valores dos atributos devem ser valores JSON escalares. Strings podem usar um único curinga no final, com um prefixo não vazio, como repo:example/*. Não há suporte a um curinga isolado ou no meio de um valor.

Valores válidos com curingas:

• repo:openai/*
• repository:my-org/*

Valores com curingas sem suporte:

• *
• repo:*:prod
• repo/*/main

O painel exibe as restrições do mapeamento como Permissões. As respostas da troca de tokens expõem as mesmas restrições como escopos OAuth na propriedade scope. Os mapeamentos não podem incluir escopos da API de administração, e as regras normais de autorização das APIs chamadas continuam se aplicando.

Exemplo de resolução de mapeamento

A resolução de mapeamentos começa depois que a OpenAI verifica a identidade externa. A OpenAI busca mapeamentos para os valores solicitados de identity_provider_id e service_account_id, ignora os mapeamentos que não estão habilitados, avalia apenas os atributos necessários para cada mapeamento e emite um token somente se exatamente um mapeamento habilitado corresponder a todos os atributos configurados.

Suponha que um token do GitHub Actions contenha estas declarações:

1234567{
  "iss": "https://token.actions.githubusercontent.com",
  "aud": "https://api.openai.com/v1",
  "sub": "repo:my-org/my-repo:ref:refs/heads/main",
  "repository": "my-org/my-repo",
  "ref": "refs/heads/main"
}

O provedor pode derivar um atributo:

123456[
  {
    "attribute": "openai.repository_ref",
    "expression": "assertion.repository + \"@\" + assertion.ref"
  }
]

O mapeamento da conta de serviço pode então exigir tanto atributos brutos quanto derivados:

Os três valores devem corresponder. O valor de sub usa um curinga no final, portanto corresponde a qualquer valor com o prefixo repo:my-org/my-repo:. A chave openai.repository_ref é resolvida a partir da transformação de atributos, e não de uma declaração bruta do token com esse nome.

Se mais de um mapeamento habilitado corresponder a uma troca, a OpenAI a rejeitará. A OpenAI exige um mapeamento único para cada par (provider, service account) e não combina permissões de mapeamentos diferentes.

Conecte a carga de trabalho

Use o exemplo do SDK no guia do seu provedor de identidade ou chame o endpoint de troca de tokens diretamente. Para consultar os campos de requisição e resposta, o comportamento de autorização e as limitações atuais, veja a referência de troca de tokens de identidade de cargas de trabalho.

Renove o token de acesso

Se você gerencia a troca de tokens diretamente, mantenha access_token e expires_at juntos ao passar a credencial de um serviço de tokens para um aplicativo. O campo expires_at indica o instante absoluto de expiração em UTC, expresso como um timestamp Unix em segundos. Programe a renovação antes desse instante, considerando diferenças entre relógios e a latência das requisições.

O campo expires_in indica o prazo de validade do token em segundos a partir da emissão. Por exemplo, um token emitido às 12:00 UTC com expires_in: 3600 expira às 13:00 UTC, mesmo que outro serviço o receba às 12:05 UTC. O tempo de transporte e processamento não prolonga a validade do token. Consulte os campos da resposta para obter detalhes.

A troca de tokens não retorna um token de atualização. Para renovar o token de acesso, repita a troca com um token de identidade externo válido ou um certificado de cliente válido.

Use identidade de cargas de trabalho com o Codex

Use esta opção para automações confiáveis do Codex em um workspace gerenciado do ChatGPT. O Codex mapeia a carga de trabalho para um usuário ou uma conta de serviço do ChatGPT, em vez de uma conta de serviço da Plataforma de API.

Siga o guia Use identidade de cargas de trabalho com o Codex para ver o procedimento completo de administração e execução. Ele aborda fontes de tokens específicas de cada provedor, regras de federação, a configuração obrigatória do arquivo de token, a precedência de credenciais, as interfaces do Codex compatíveis, a rotação e a verificação. Para atribuição opcional em auditorias, o Codex aceita OPENAI_WORKLOAD_IDENTITY_CONTEXT; o guia do Codex define seu esquema, limites de privacidade e comportamento de auditoria.

Use a API de administração para gerenciar os provedores e as regras do Codex programaticamente. A referência de regras de federação explica como uma regra pode aceitar mais de um sujeito externo e mapeá-los para um único principal do ChatGPT.

Solucione problemas de conexão

A OpenAI rejeita o token de identidade

Decodifique o token localmente e compare suas declarações iss, aud, sub, exp, iat e as específicas do provedor com o provedor configurado. Não cole tokens de produção em ferramentas JWT de terceiros.

Para a API da OpenAI, compare também os atributos do token com o mapeamento da conta de serviço selecionado. Para o Codex, compare-os com a regra de federação selecionada.

O mapeamento da API da OpenAI não corresponde

Confirme se a requisição usa os IDs do provedor de identidade e da conta de serviço pretendidos, se o mapeamento está ativo e se exatamente um mapeamento corresponde. Consulte a referência de erros de troca de tokens para ver as categorias de erro em detalhes.

O Codex informa que a configuração está incompleta

Confirme se o processo do Codex tem as duas variáveis do ambiente obrigatórias para identidade de cargas de trabalho e se OPENAI_IDENTITY_TOKEN_FILE contém um caminho absoluto para um token atual. Verifique as permissões do arquivo e do diretório pai.

O Codex usa outra credencial

Carregue as duas variáveis obrigatórias de identidade de cargas de trabalho no processo do Codex. A presença de qualquer uma delas dá prioridade à WIF sobre chaves de API, tokens de acesso e logins armazenados. Inicie um novo processo com a configuração baixada carregada e execute codex login status novamente.

Recomendações de segurança

• Use um principal dedicado para cada aplicativo ou carga de trabalho.
• Separe os ambientes de produção dos demais ambientes.
• Prefira a correspondência exata de declarações a padrões abrangentes.
• Conceda apenas o acesso necessário para a carga de trabalho.
• Use prazos de validade curtos para os tokens de acesso.
• Revise e remova provedores, mapeamentos e regras que não são usados.
• Analise erros de troca de tokens e padrões de acesso inesperados.

Documentação relacionada

• Use identidade de cargas de trabalho com o Codex
• Referência de regras de federação do Codex
• Gerencie a identidade de cargas de trabalho do Codex com a API de administração
• Referência de troca de tokens de identidade de cargas de trabalho
• Autenticação do Codex
• Variáveis do ambiente do Codex
• Modo não interativo do Codex