Gerencie a identidade de cargas de trabalho do Codex com a API de administração

Use a API de administração da organização para gerenciar provedores de identidade de cargas de trabalho e regras de federação do Codex por meio de ferramentas de infraestrutura ou CI. A API expõe o mesmo modelo de provedores e regras do Portal de administração da OpenAI.

A API chama as regras de federação de mappings nos caminhos e objetos de resposta. Esta página usa regra de federação para o conceito do produto e mapping apenas quando se refere a um campo ou caminho da API.

Pré-requisitos

Você precisa de:

• Federação de identidades de cargas de trabalho habilitada para sua organização e seu workspace gerenciado do ChatGPT.
• Uma chave da API de administração cujo proprietário seja um administrador ativo com permissão para gerenciar a identidade de cargas de trabalho.
• O ID do workspace gerenciado do ChatGPT.
• O ID de usuário da OpenAI de uma conta humana ou de serviço existente e ativa nesse workspace.
• O emissor, o público-alvo e as declarações do token OIDC ou JWT-SVID SPIFFE da carga de trabalho.

Os endpoints WIF usam IDs de recursos em vez de nomes. Eles não listam nem criam workspaces do ChatGPT ou entidades de segurança. Forneça esses IDs a partir do seu sistema de provisionamento. Se você não gerencia esses recursos programaticamente, use o Portal de administração da OpenAI para criar ou selecionar a entidade de segurança e conectar essa carga de trabalho.

Defina a chave da API de administração no seu ambiente:

export OPENAI_ADMIN_KEY="<admin-api-key>"

As chaves da API de administração são credenciais de longa duração. Armazene a chave em um gerenciador de segredos, não a inclua em commits e não a use para autenticação do Codex em tempo de execução.

Endpoints

Todas as solicitações usam https://api.openai.com e uma chave da API de administração no cabeçalho de autorização Bearer.

As respostas de listagem usam { "object": "list", "data": [...] }. Os endpoints não usam paginação.

Crie um provedor OIDC

Crie um provedor para cada emissor e limite de confiança que você queira gerenciar de forma independente. Substitua o emissor e o público-alvo do exemplo pelos valores exatos de um token de amostra. Inspecione localmente as declarações iat e exp do token e escolha um tempo de vida aceito para a asserção que cubra a faixa esperada de exp - iat do emissor. A OpenAI verifica essa duração total, e não a validade restante do token.

Para o Microsoft Entra, não presuma que a asserção tenha duração de uma hora. Os tempos de vida dos tokens de acesso variam, e a Microsoft não oferece suporte à configuração dos tempos de vida dos tokens de identidade gerenciada. Substitua MAX_ASSERTION_LIFETIME_SECONDS por um número inteiro aprovado entre 1 e 176.400. Esse limite do provedor é independente do tempo de vida do token de acesso da OpenAI emitido por uma regra de federação.

1234567891011121314151617181920212223MAX_ASSERTION_LIFETIME_SECONDS="<accepted-issuer-lifetime-seconds>"

jq -n \
  --argjson max_assertion_lifetime_seconds "$MAX_ASSERTION_LIFETIME_SECONDS" \
  '{
    name: "entra-production",
    type: "oidc",
    issuer: "https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.0",
    audience: "api://openai-codex-production",
    description: "Production Codex workloads in Microsoft Azure",
    max_assertion_lifetime_seconds: $max_assertion_lifetime_seconds,
    check_jti: true
  }' > provider.json

curl --fail-with-body --silent --show-error \
  https://api.openai.com/v1/organization/workload_identity/providers \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  --data @provider.json \
  --output provider-response.json

PROVIDER_ID="$(jq -r .id provider-response.json)"
printf 'Created provider %s\n' "$PROVIDER_ID"

A saída esperada começa com um ID de provedor de identidade:

Created provider idp_...

Por padrão, um provedor OIDC usa a descoberta na URL do emissor. Use custom_url quando o documento público de descoberta estiver em outro local, jwks_uri para uma URL pública explícita de JWKS ou jwks_local: true com jwks para enviar chaves públicas. Não inclua material de chave privada.

Crie um provedor JWT-SVID SPIFFE

Defina type como spiffe_jwt, defina issuer como o domínio de confiança canônico e forneça uma URL pública de pacote ou um pacote SPIFFE enviado por upload. Uma regra SPIFFE também deve definir audiences.

12345678{
  "name": "spiffe-production",
  "type": "spiffe_jwt",
  "issuer": "spiffe://example.com",
  "jwks_uri": "https://spiffe.example.com/bundle.json",
  "max_assertion_lifetime_seconds": 3600,
  "check_jti": true
}

Para um pacote enviado por upload, defina jwks_local como true, substitua jwks_uri pelo objeto jwks e inclua pelo menos uma chave pública cujo use seja jwt-svid.

Crie uma regra de federação

Uma regra tem como destino uma entidade de segurança existente e pode corresponder a uma ou várias identidades externas de cargas de trabalho. Este exemplo aceita um sujeito de identidade gerenciada do Azure:

1234567891011121314151617181920212223242526export WORKSPACE_ID="<managed-chatgpt-workspace-id>"
export PRINCIPAL_ID="<existing-openai-user-id>"

jq -n \
  --arg workspace_id "$WORKSPACE_ID" \
  --arg principal_id "$PRINCIPAL_ID" \
  '{
    name: "entra-payments-production",
    description: "Production payments workload",
    workspace_id: $workspace_id,
    principal_id: $principal_id,
    external_subject: "11111111-2222-3333-4444-555555555555",
    audiences: ["api://openai-codex-production"],
    access_token_lifetime_seconds: 600,
    enabled: true
  }' > rule.json

curl --fail-with-body --silent --show-error \
  "https://api.openai.com/v1/organization/workload_identity/providers/$PROVIDER_ID/mappings" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  --data @rule.json \
  --output rule-response.json

FEDERATION_RULE_ID="$(jq -r .id rule-response.json)"
printf 'Created federation rule %s\n' "$FEDERATION_RULE_ID"

A saída esperada começa com um ID de mapeamento. Esse é o valor que o Codex usa como OPENAI_FEDERATION_RULE_ID:

Created federation rule idpm_...

Para definir um conjunto de sujeitos permitidos em uma regra, omita external_subject e use uma condição CEL:

123{
  "condition": "assertion.sub in [\"workload-a\", \"workload-b\"]"
}

Defina pelo menos um dos campos external_subject, claims ou condition. Todas as verificações de identidade configuradas devem ser aprovadas. Consulte a referência de regras de federação para saber mais sobre cardinalidade, CEL, público-alvo, escopo e comportamento do tempo de vida.

Liste e reconcilie recursos

Liste os provedores antes de criar um para que sua automação possa comparar a configuração desejada com o estado atual:

123curl --fail-with-body --silent --show-error \
  https://api.openai.com/v1/organization/workload_identity/providers \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" | jq .

Em seguida, liste as regras de um provedor:

123curl --fail-with-body --silent --show-error \
  "https://api.openai.com/v1/organization/workload_identity/providers/$PROVIDER_ID/mappings" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" | jq .

A API não define um contrato para chaves de idempotência. Armazene os IDs retornados no seu estado de configuração aprovado, leia o recurso atual antes de alterá-lo e atualize pelo ID. Não crie um substituto a cada execução.

Atualize ou desative um recurso

As atualizações usam POST apenas com os campos que você deseja alterar. Este exemplo altera o tempo de vida da regra:

123456curl --fail-with-body --silent --show-error \
  -X POST \
  "https://api.openai.com/v1/organization/workload_identity/providers/$PROVIDER_ID/mappings/$FEDERATION_RULE_ID" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"access_token_lifetime_seconds": 300}' | jq .

Desative uma regra para interrompê-la imediatamente:

123456curl --fail-with-body --silent --show-error \
  -X POST \
  "https://api.openai.com/v1/organization/workload_identity/providers/$PROVIDER_ID/mappings/$FEDERATION_RULE_ID" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}' | jq .

Defina enabled como false no caminho do provedor para interromper todas as regras desse provedor. A desativação bloqueia novas trocas e revoga os tokens de acesso emitidos por meio do recurso. Você pode reativá-lo depois que sua entidade de segurança, seu workspace, seu vínculo e seu provedor estiverem ativos.

Edições comuns de regras afetam apenas novas trocas. Os tokens emitidos antes da edição podem permanecer válidos até o fim do TTL. Edições nas configurações de confiança do provedor revogam os tokens emitidos antes que as novas configurações entrem em vigor.

Arquive um recurso

DELETE arquiva um provedor ou uma regra em vez de apagá-lo. O arquivamento bloqueia novas trocas, revoga os tokens emitidos, oculta o recurso dos resultados normais de listagem e não pode ser desfeito.

Arquive uma regra:

1234curl --fail-with-body --silent --show-error \
  -X DELETE \
  "https://api.openai.com/v1/organization/workload_identity/providers/$PROVIDER_ID/mappings/$FEDERATION_RULE_ID" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY"

Arquive um provedor:

1234curl --fail-with-body --silent --show-error \
  -X DELETE \
  "https://api.openai.com/v1/organization/workload_identity/providers/$PROVIDER_ID" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY"

Arquivar um provedor revoga o acesso de suas regras do Codex. Você deve remover qualquer mapeamento de produto que não seja do Codex antes de poder arquivar esse provedor. Isso protege a configuração existente de identidade de cargas de trabalho da API da OpenAI.

Campos do provedor

A criação exige name e issuer. A atualização aceita os campos mutáveis, exceto type.

A descoberta e o uso de chaves explícitas ou enviadas são modos alternativos de verificação. As URLs de emissor, descoberta e JWKS têm requisitos de validação descritos na visão geral de identidade de cargas de trabalho.

Campos da regra de federação

A criação exige workspace_id e principal_id, além de pelo menos uma verificação de identidade. Não é possível alterar o workspace ou a entidade principal após a criação.

As respostas de provedores usam workload_identity_provider; as respostas de regras usam workload_identity_mapping. Ambas incluem id, enabled, created_at e updated_at. Os registros de data e hora são expressos em segundos Unix.

Limites e erros

Uma organização pode ter até 50 provedores não arquivados. Um provedor pode ter até 50 regras não arquivadas. A API retorna:

• 400 para erros nos campos da solicitação, nas configurações de confiança do provedor, nas condições de regras, nos escopos ou quando a associação da entidade principal está inativa.
• 403 quando o proprietário da chave da API de administração não pode gerenciar a identidade de cargas de trabalho.
• 404 quando a organização não está associada a um locatário ou quando o recurso solicitado está fora dos limites da organização e do locatário.
• 409 para limites de provedores ou regras, conflitos de sujeito, vínculos inativos ou conflitos de ciclo de vida.

Trate 404 como uma resposta que não divulga informações: o serviço não revela um provedor ou uma regra pertencente a outra organização ou a outro locatário. Repita as solicitações que receberem respostas transitórias 429 e 5xx com intervalos limitados que aumentem a cada tentativa. Não repita uma solicitação após um erro de validação ou permissão sem alterar a solicitação ou o estado do administrador.