TLS mútuo

O TLS mútuo (mTLS) adiciona a verificação de certificados de cliente TLS às requisições à API da OpenAI. Depois que você ativa um certificado confiável para uma organização ou projeto, as requisições nesse escopo devem apresentar um certificado de cliente aceito, além da credencial de portador habitual.

Use mTLS quando uma carga de trabalho puder armazenar com segurança uma chave privada de cliente e você quiser que a OpenAI verifique a identidade do certificado antes de autorizar uma requisição à API. O mTLS não substitui chaves de API, credenciais de contas de serviço nem tokens de acesso de identidade de cargas de trabalho.

Antes de configurar o mTLS

Qualquer organização da API pode gerenciar o mTLS por meio do controle de acesso baseado em funções (RBAC) habitual:

• api.mtls.read permite que uma entidade principal liste, visualize e teste as configurações de certificados.
• api.mtls.write permite que uma entidade principal envie, atualize, ative, desative e exclua certificados.

A função de proprietário da organização inclui essas permissões, mas você pode concedê-las por meio de uma função personalizada. Para saber mais, consulte Gerencie permissões na plataforma da OpenAI.

Prepare:

• Um certificado de cliente e sua chave privada para cada carga de trabalho.
• Todos os certificados intermediários necessários para construir um caminho do certificado de cliente até sua âncora de confiança.
• Uma âncora de confiança estável, codificada em PEM, que você possa ativar no nível da organização ou do projeto.
• Um projeto não crítico e um procedimento de recuperação testado antes de habilitar o mTLS para o tráfego de produção.

Mantenha as chaves privadas fora do controle de versão. Não registre em logs chaves privadas, conteúdo de certificados nem credenciais de portador.

Envie e ative âncoras de confiança

O envio armazena um certificado, mas não torna o mTLS obrigatório. A ativação é a etapa que altera o comportamento das requisições.

1. Abra Configurações da organização > Segurança > TLS mútuo.
2. Envie uma âncora de confiança codificada em PEM para cada objeto de certificado. Dê a ela um nome que identifique a autoridade e a geração da rotação.
3. Opcionalmente, adicione um filtro CEL que restrinja quais certificados de cliente verificados essa âncora pode aceitar.
4. Ative o certificado primeiro em um projeto não crítico. Envie requisições representativas por meio de um host mTLS da API a partir de cada carga de trabalho prevista.
5. Ative o certificado para outros projetos ou para a organização depois que a validação for bem-sucedida.

Você também pode gerenciar certificados pela API:

Use uma credencial com a permissão necessária, api.mtls.read ou api.mtls.write. Para consultar os esquemas de requisição e resposta, veja a referência da API de certificados da organização.

Requisitos dos certificados

Use uma âncora de confiança codificada em PEM por objeto de certificado. O arquivo enviado deve conter um certificado válido que expire mais de um dia após o envio. O certificado de cliente deve incluir um identificador de chave da autoridade (AKI) para a verificação das requisições.

Para que uma requisição passe pela verificação mTLS:

• O certificado de cliente deve estar válido no momento da requisição e ser adequado para autenticação de cliente TLS.
• Deve ser possível construir um caminho válido do certificado de cliente até uma âncora de confiança ativa no nível da organização ou do projeto.
• Se o caminho incluir certificados intermediários, o cliente deverá apresentá-los durante a negociação TLS.
• A âncora de confiança configurada e a cadeia do cliente devem passar pela validação padrão de caminho de certificados de cliente X.509.

Se um arquivo enviado contiver mais de um certificado codificado em PEM, a verificação da cadeia apresentada na requisição usará apenas o primeiro certificado configurado como âncora; não conte com a semântica de pacotes PEM.

A OpenAI não busca certificados intermediários ausentes nas URLs de Authority Information Access (AIA) nem realiza verificações de lista de revogação de certificados (CRL) ou de Online Certificate Status Protocol (OCSP). Apresente a cadeia completa exigida e gerencie a resposta a incidentes por meio da rotação e da desativação de certificados e dos seus próprios controles de ciclo de vida de certificados.

Entenda a ordem de verificação

A OpenAI verifica os certificados ativos no nível do projeto antes dos certificados ativos no nível da organização. Se nenhum dos escopos tiver um certificado ativo, o mTLS não adicionará uma verificação de certificado à requisição.

Quando existe um certificado ativo, a OpenAI verifica a identidade do cliente nesta ordem:

1. A OpenAI primeiro tenta o caminho direto existente, que verifica o certificado de cliente diretamente em relação a uma âncora ativa, sem usar certificados intermediários da requisição.
2. Quando o caminho direto simplesmente não encontra correspondência, a OpenAI tenta verificar a cadeia da requisição com o certificado de cliente e os certificados intermediários apresentados pela conexão TLS.
3. Se um caminho passar na verificação, a OpenAI avaliará o filtro CEL do certificado ativo, se houver, em relação ao certificado de cliente verificado.

A verificação da cadeia apresentada na requisição está disponível por padrão.

O caminho que usa a cadeia apresentada na requisição é uma alternativa quando simplesmente não há correspondência, não um procedimento de recuperação para todo erro do caminho direto. Dados de certificado ausentes ou malformados, um AKI ausente ou um erro determinístico após o caminho direto selecionar uma âncora podem fazer a requisição falhar sem tentar verificar a cadeia apresentada.

Filtre certificados de cliente com CEL

Associe um filtro opcional de Common Expression Language (CEL) a um certificado enviado para restringir os certificados de cliente verificados que essa âncora aceita. A expressão deve retornar um valor booleano e é executada sobre o certificado de cliente verificado tanto no caminho direto quanto no caminho que usa a cadeia apresentada na requisição.

A CEL expõe estes campos:

• subject.common_name, subject.country_code, subject.organization, subject.organizational_unit, subject.locality, subject.province, subject.street_address e subject.postal_code.
• subject_alt_names, uma lista cujas entradas expõem type, value e oid. Os identificadores de tipo SAN compatíveis são DNS, EMAIL, IP_ADDRESS, URI e CUSTOM.

Por exemplo, exija uma unidade organizacional de produção e um SAN do tipo DNS em um espaço de nomes específico:

subject.organizational_unit == "Production" &&
subject_alt_names.exists(san, san.type == DNS && san.value.endsWith(".example.com"))

Um certificado que passa na verificação, mas não corresponde ao filtro, falha com certificate_attribute_verification_failed. A OpenAI rejeita uma política que não passa na validação quando você a salva.

Use um host mTLS

Envie o tráfego da API para um host mTLS em vez de api.openai.com:

O mTLS funciona por host. Use a mesma rota /v1 que você chamaria na interface de API correspondente e teste cada API e modelo que sua carga de trabalho usa. A disponibilidade de rotas e modelos pode variar entre os hosts regionais.

Por exemplo, envie uma credencial de portador normal e um certificado de cliente ao host mTLS padrão:

1234567export OPENAI_MTLS_CERT_CHAIN="/path/to/client-chain.pem"
export OPENAI_MTLS_KEY="/path/to/client-key.pem"

curl https://mtls.api.openai.com/v1/models \
  --cert "$OPENAI_MTLS_CERT_CHAIN" \
  --key "$OPENAI_MTLS_KEY" \
  --header "Authorization: Bearer $OPENAI_API_KEY"

O arquivo da cadeia de certificados deve conter primeiro o certificado de cliente, seguido dos certificados intermediários necessários. Não envie dados de certificados em cabeçalhos HTTP ou corpos de requisições.

A federação de identidades de cargas de trabalho com X.509 usa um endpoint de troca específico e separado: POST https://mtls.auth.openai.com/oauth/token. Essa troca produz um token de portador de curta duração; ela não oferece autenticação de API baseada apenas em certificados. Para ver a estrutura completa da requisição, consulte a referência de troca de tokens de identidade de cargas de trabalho.

Rotacionar certificados

Rotacione as âncoras de confiança com um período de sobreposição para que as cargas de trabalho existentes continuem funcionando:

1. Faça o upload da nova âncora de confiança sem desativar a antiga.
2. Ative a nova âncora em cada projeto desejado ou no nível da organização.
3. Atualize as cargas de trabalho para apresentar certificados de cliente cuja cadeia alcance a nova âncora e teste cada host mTLS e interface de API que elas usam.
4. Desative a âncora antiga depois que todas as cargas de trabalho tiverem migrado.
5. Exclua o certificado antigo somente depois de desativá-lo para a organização e todos os projetos.

Você pode rotacionar os certificados intermediários sem alterar a âncora de confiança configurada. Apresente a nova cadeia completa nas requisições seguintes.

Solucionar problemas de requisições

Use códigos de erro estáveis para distinguir erros de configuração de erros temporários do serviço:

Nas requisições de gerenciamento, mtls_certificate_invalid significa que o PEM enviado não passou na validação, expired_certificate significa que ele expira em breve demais ou já expirou, mtls_cel_policy_invalid significa que o filtro não passa na validação e certificate_in_use significa que você deve desativar o certificado antes de excluí-lo.

Limitações atuais

• Uma organização pode fazer o upload de até 50 objetos de certificado.
• O mTLS adiciona a verificação de certificados à autenticação normal da API; ele não oferece autorização de API baseada apenas em certificados.
• A OpenAI não busca certificados intermediários via AIA nem realiza verificações de CRL ou OCSP.
• O Private Link não é compatível com mTLS. Consulte Private Link quando precisar de um caminho de rede privada no Azure como alternativa.
• Os hosts mTLS da API compatíveis são mtls.api.openai.com, mtls-us.api.openai.com e mtls-eu.api.openai.com. Não presuma que todos os outros hosts regionais da API tenham um equivalente mTLS.
• A federação de identidades de cargas de trabalho com X.509 não retorna um token de atualização e não usa DPoP, uma declaração cnf nem um token de portador vinculado a um certificado. Consulte Configurar a federação de identidades de cargas de trabalho com certificados X.509.