Federação de identidades de cargas de trabalho

Com a federação de identidades de cargas de trabalho, uma carga de trabalho confiável pode usar uma identidade que já possui, sem precisar armazenar uma chave de API da OpenAI ou uma credencial do ChatGPT. A carga de trabalho apresenta um token de curta duração emitido pelo seu provedor de identidade, e a OpenAI o troca por um token de acesso da OpenAI, também de curta duração.

As cargas de trabalho da API da OpenAI também podem usar a federação de identidades com X.509 para trocar uma identidade verificada por certificado por um token de acesso.

Você pode usar a federação de identidades de cargas de trabalho com a API da OpenAI ou com 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 em comum e pelas orientações sobre provedores de identidade a seguir. Depois, siga a seção do produto que sua carga de trabalho usa.

• API da OpenAI: Prossiga para Usar a identidade da carga de trabalho com a API da OpenAI.
• Codex: Consulte Usar a identidade da carga de trabalho com o Codex.

Consulte a referência sobre regras de federação do Codex para entender como as regras funcionam ao longo do ciclo de vida.

Como funciona

Antes que a carga de trabalho se conecte, um administrador configura três elementos:

1. Um provedor de identidade indica à OpenAI em qual emissor externo confiar e como verificar os tokens assinados por ele ou as identidades atestadas por certificado.
2. Uma regra de acesso define quais atributos de token a OpenAI aceita e qual identidade da OpenAI a carga de trabalho pode assumir. Na configuração da API da OpenAI, essa regra se chama mapeamento de conta de serviço. Na configuração do Codex, ela se chama regra de federação.
3. Uma entidade de segurança da OpenAI recebe o acesso concedido. Na API da OpenAI, essa entidade é uma conta de serviço da Plataforma de API. No Codex, é um usuário ou uma conta de serviço do ChatGPT em um espaço de trabalho gerenciado.

Em tempo de execução:

1. A carga de trabalho recebe um token de curta duração, que pode ser um JWT OIDC ou um JWT-SVID SPIFFE. Como alternativa, uma carga de trabalho da API da OpenAI pode apresentar 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 o certificado e, em seguida, avalia o mapeamento ou a regra que o administrador configurou.
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 ou um projeto, nem adiciona membros a um espaço de trabalho. Os administradores criam ou selecionam esses recursos durante a configuração.

Obter um token de identidade

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

Nas configurações documentadas, a OpenAI aceita tokens de sujeito no formato JWT compatíveis com OIDC, incluindo tokens JWT-SVID SPIFFE. Para usar a API da OpenAI com um provedor OIDC que não esteja na lista, entre em contato com o suporte da OpenAI. Para usar o Codex, selecione 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 as etapas de emissão do token e volte para Usar a identidade da carga de trabalho com o Codex. As instruções de configuração na OpenAI e os exemplos de SDK desses guias se aplicam à API da OpenAI. A federação com X.509 está disponível apenas para a API da OpenAI.

Usar a identidade da carga de trabalho com a API da OpenAI

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

Acesse Configurações da organização > Segurança > Provedor de identidade de cargas de trabalho. Primeiro, crie o provedor. Depois, na página de detalhes dele, configure os mapeamentos de contas de serviço.

Provedores X.509

Um provedor X.509 deriva os atributos de identidade da carga de trabalho de um certificado de cliente. A OpenAI verifica esse certificado usando a configuração de TLS mútuo que sua organização já possui. O provedor 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 o 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 da ativação, os hosts mTLS, o funcionamento das cadeias de certificados, os filtros CEL e a rotação de certificados.

Em seguida, crie o provedor X.509, derive um único valor não vazio para openai.subject e mapeie essa identidade para uma conta de serviço do projeto que tenha 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 esse token e um certificado de cliente aceito ao endpoint mTLS da API.

Siga o guia de configuração de certificados X.509 para ver todas as etapas de configuração no painel e de envio de requisições.

Configurar um provedor OIDC de identidade de cargas de trabalho

Crie um provedor de identidade de cargas de trabalho para cada emissor externo em que você confia. Para autenticar cargas de trabalho, a API da OpenAI aceita tokens de sujeito no formato JWT OIDC. A configuração do provedor inclui as seguintes opções:

A descoberta OIDC personalizada e o uso de um JWKS enviado são opções mutuamente exclusivas. Ao ativar a descoberta personalizada, o painel oculta a opção de usar um JWKS enviado. A URL de descoberta personalizada deve ser pública, usar HTTPS e não pode conter credenciais, porta personalizada, componente de consulta ou fragmento.

Se a opção Usar URL personalizada para descoberta OIDC não aparecer no painel, use a descoberta OIDC padrão ou ative Usar JWKS enviado para verificar tokens. Use o JWKS público que seu provedor de identidade publica 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 personalizada de descoberta OIDC como a URL do 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 a OpenAI obtém os metadados de descoberta e as chaves públicas de assinatura.

Transformar declarações de tokens com CEL

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

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

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 definida na especificação da linguagem CEL. Por exemplo, você pode ler os valores das declarações com expressões como assertion.sub ou assertion.repository. Se uma expressão usar sintaxe ou funções incompatíveis, a resolução do mapeamento falhará.

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

As transformações devem retornar valores escalares: strings, valores booleanos true ou false, inteiros ou números finitos. Arrays, objetos, valores nulos e erros de avaliação fazem a resolução do mapeamento falhar. A OpenAI converte os resultados escalares das transformações em strings antes de compará-los aos valores do mapeamento. Por exemplo, true se torna "true" e 7 se torna "7".

As chaves de mapeamento que começam com openai. obtêm seus valores exclusivamente das transformações de atributos. Declarações brutas do token de sujeito que já usam o prefixo openai. só influenciam a escolha do mapeamento se você configurar uma transformação correspondente.

Gerenciar o JWKS e a rotação de chaves

A OpenAI verifica os tokens de sujeito OIDC usando 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, em seguida, acessa o jwks_uri indicado nele. A OpenAI mantém os documentos de descoberta e o conteúdo dos JWKS remotos em cache por 600 segundos.
• Descoberta OIDC personalizada: A OpenAI busca /.well-known/openid-configuration a partir da URL base de descoberta personalizada e, em seguida, acessa o jwks_uri indicado no documento. A declaração iss do token ainda precisa corresponder ao valor de URL do emissor OIDC.
• Atualização quando a chave não é encontrada: Se o kid de um token não estiver no JWKS em cache, a OpenAI atualizará o JWKS e repetirá a busca antes de rejeitar o token.
• JWKS enviado: Quando a opção Usar JWKS enviado para verificar tokens está ativada, a OpenAI usa o JWKS enviado e armazenado no provedor, sem realizar a descoberta OIDC nem buscar um JWKS remoto. Assim que a atualização do provedor estiver disponível para o serviço de troca de tokens, as novas trocas passarão a usar 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 das chaves de assinatura, mantenha tanto as chaves públicas antigas quanto as novas publicadas no JWKS do emissor. Assim, os tokens assinados com a chave antiga continuam funcionando enquanto a OpenAI já aceita tokens assinados com a nova chave. Se você usa um JWKS enviado, atualize o provedor antes de emitir tokens com o novo kid. A OpenAI rejeita tokens assinados com uma chave que não esteja no JWKS configurado.

Configurar 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.

Nos provedores X.509, as chaves de mapeamento usam atributos openai.* derivados. Prefira um mapeamento por correspondência exata de openai.subject. Declarações brutas de JWT, como sub, aud e iss, aplicam-se apenas a provedores OIDC.

A configuração do mapeamento inclui as seguintes opções:

Os valores dos atributos devem ser valores JSON escalares. Strings podem terminar com um único curinga, desde que haja um prefixo não vazio, como em repo:example/*. Não é permitido usar um curinga sozinho ou no meio de um valor.

Valores válidos com curinga:

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

Valores não aceitos com curinga:

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

O painel exibe as restrições do mapeamento em Permissões. As respostas à troca de tokens apresentam as mesmas restrições como escopos OAuth na propriedade scope. Os mapeamentos não podem incluir escopos da API de administração. As verificações habituais de autorização continuam se aplicando às chamadas subsequentes à API.

Exemplo de resolução de mapeamento

A resolução do mapeamento começa depois que a OpenAI verifica a identidade externa. A OpenAI busca os mapeamentos para os valores de identity_provider_id e service_account_id informados na requisição, ignora os mapeamentos desativados e avalia apenas os atributos necessários para cada mapeamento. Ela só emite um token se exatamente um mapeamento ativo 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 precisam corresponder. Como o valor de sub termina com um curinga, ele corresponde a qualquer valor que comece com repo:my-org/my-repo:. O valor da chave openai.repository_ref vem da transformação de atributo. Uma declaração bruta do token com esse nome não fornece o valor da chave.

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

Conectar a carga de trabalho

Use o exemplo de SDK no guia do seu provedor de identidade ou chame diretamente o endpoint de troca de tokens. Para saber quais são os campos de requisição e resposta, como funciona a autorização e quais são as limitações atuais, consulte a referência sobre a troca de tokens de identidade de cargas de trabalho.

Renovar 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 horário, levando em conta possíveis diferenças entre relógios e a latência das requisições.

O campo expires_in indica a 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. Para mais detalhes, consulte os campos da resposta.

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 externa válido ou um certificado de cliente válido.

Usar a identidade da carga de trabalho com o Codex

Use esta opção para automações confiáveis do Codex em um espaço de trabalho 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.

A referência sobre regras de federação explica como uma única regra pode aceitar vários sujeitos externos e mapeá-los para uma única entidade de segurança do ChatGPT.

Solucionar problemas de conexão

A OpenAI rejeita o token de identidade

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

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

O mapeamento da API da OpenAI não corresponde à requisição

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

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

Confirme se as duas variáveis de ambiente obrigatórias de identidade da carga de trabalho estão definidas no processo do Codex e se OPENAI_IDENTITY_TOKEN_FILE contém o caminho absoluto de um arquivo com um token válido. Verifique as permissões do arquivo e do diretório que o contém.

O Codex usa outra credencial

Carregue as duas variáveis obrigatórias de identidade da carga de trabalho no processo do Codex. Quando pelo menos uma delas está definida, o Codex dá prioridade à federação de identidades de cargas de trabalho (WIF) em relação a chaves de API, tokens de acesso e logins salvos. Inicie um novo processo com a configuração baixada já carregada e execute codex login status novamente.

Recomendações de segurança

• Use uma entidade de segurança dedicada para cada aplicativo ou carga de trabalho.
• Separe os ambientes de produção dos demais ambientes.
• Prefira correspondências exatas de declarações a padrões abrangentes.
• Conceda apenas o acesso necessário para a carga de trabalho.
• Use tokens de acesso de curta duração.
• Revise os provedores, mapeamentos e regras e remova os que não estiverem em uso.
• Analise os erros de troca de tokens e os padrões de acesso inesperados.

Documentação relacionada

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