TLS mútuo

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

Use mTLS quando a carga de trabalho puder armazenar com segurança uma chave privada de cliente e você quiser que a OpenAI verifique a identidade da carga de trabalho pelo 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 carga de trabalho.

Antes de configurar o mTLS

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

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

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

Antes de começar, providencie os seguintes itens.

• Um certificado de cliente e a respectiva chave privada para cada carga de trabalho.
• Todos os certificados intermediários necessários para formar um caminho do certificado de cliente até a âncora de confiança.
• Uma âncora de confiança estável em formato 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 já 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, o conteúdo de certificados nem credenciais de portador.

Enviar e ativar âncoras de confiança

O envio armazena o certificado. O mTLS só passa a ser exigido nas requisições quando você ativa o certificado.

1. Abra Configurações da organização > Segurança > TLS mútuo.
2. Envie uma âncora de confiança em formato PEM para cada objeto de certificado. Escolha um nome que identifique a autoridade e o ciclo de rotação.
3. Se quiser, adicione um filtro CEL para restringir quais certificados de cliente verificados a âncora pode aceitar.
4. Ative o certificado primeiro em um projeto não crítico. A partir de cada carga de trabalho prevista, envie requisições representativas por um host mTLS da API.
5. Após concluir a validação com sucesso, ative o certificado nos demais projetos ou na organização.

Você também pode gerenciar os certificados pela API.

Use uma credencial com a permissão api.mtls.read ou api.mtls.write, conforme a operação. Para consultar os schemas 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 em formato PEM por objeto de certificado. O arquivo enviado deve conter um certificado válido que expire mais de um dia após o envio. Para que a requisição possa ser verificada, o certificado de cliente deve incluir um identificador de chave da autoridade (AKI).

Para que uma requisição passe na verificação mTLS, é preciso atender aos seguintes requisitos.

• O certificado de cliente deve estar válido no momento da requisição e ser adequado à autenticação de cliente TLS.
• Deve ser possível formar um caminho válido do certificado de cliente até uma âncora de confiança ativa 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 de certificados do cliente devem passar pela validação padrão de caminho de certificação X.509 para certificados de cliente.

Se o arquivo enviado contiver mais de um certificado em formato PEM, a verificação da cadeia apresentada na requisição usará apenas o primeiro certificado configurado como âncora. Não presuma que o arquivo será tratado como um pacote de certificados PEM.

A OpenAI não busca certificados intermediários ausentes nas URLs de acesso às informações da autoridade (AIA) nem verifica a revogação por meio de listas de revogação de certificados (CRL) ou do protocolo de consulta online de status de certificados (OCSP). Apresente toda a cadeia necessária e, em caso de incidente, use a rotação e a desativação de certificados, além dos seus próprios controles de ciclo de vida dos certificados.

Entender a ordem de verificação

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

Quando há um certificado ativo, a OpenAI verifica a identidade do cliente na seguinte ordem.

1. A OpenAI tenta primeiro o caminho direto já existente. Nesse caminho, verifica o certificado de cliente diretamente com uma âncora ativa, sem usar certificados intermediários da requisição.
2. Se a verificação direta terminar normalmente sem encontrar uma correspondência, a OpenAI tenta verificar a cadeia da requisição usando o certificado de cliente e os certificados intermediários apresentados na conexão TLS.
3. Se a verificação de um dos caminhos for bem-sucedida, a OpenAI aplica o filtro CEL do certificado ativo, se houver, ao certificado de cliente verificado.

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

A OpenAI recorre à cadeia da requisição quando a verificação direta termina normalmente sem encontrar uma correspondência. Outros erros no caminho direto podem impedir essa tentativa. A requisição pode falhar sem que a OpenAI tente verificar a cadeia apresentada se os dados do certificado estiverem ausentes ou malformados, se faltar o AKI ou se ocorrer um erro determinístico depois que o caminho direto selecionar uma âncora.

Filtrar certificados de cliente com CEL

Você pode adicionar um filtro da linguagem de expressões comuns (CEL) a um certificado enviado para restringir quais certificados de cliente verificados a âncora aceita. A expressão deve retornar um valor booleano. Ela é avaliada com base no certificado de cliente verificado tanto no caminho direto quanto no caminho que usa a cadeia da requisição.

A CEL disponibiliza os seguintes 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 em que cada entrada contém type, value e oid. Os identificadores de tipo aceitos para nomes alternativos do titular (SAN) são DNS, EMAIL, IP_ADDRESS, URI e CUSTOM.

Por exemplo, use a expressão abaixo para exigir que a unidade organizacional seja a de produção e que o certificado tenha um SAN do tipo DNS em um namespace específico.

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

Se o certificado passar na verificação, mas não atender ao filtro, a requisição falhará com o erro certificate_attribute_verification_failed. Se você tentar salvar uma política que não passe na validação, a OpenAI a rejeitará.

Usar um host mTLS

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

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

O exemplo a seguir envia a credencial de portador habitual 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"

No arquivo da cadeia de certificados, coloque primeiro o certificado de cliente e, em seguida, todos os intermediários necessários. Não envie dados de certificados nos cabeçalhos HTTP nem no corpo das requisições.

A federação de identidade de carga de trabalho com X.509 usa um endpoint específico e separado para a troca de certificados, POST https://mtls.auth.openai.com/oauth/token. Essa troca gera um token de portador de curta duração e não permite autenticar chamadas à API apenas com o certificado. Para consultar a estrutura completa da requisição, veja a referência de troca de tokens de identidade de carga de trabalho.

Fazer a rotação de certificados

Durante a rotação, mantenha as duas âncoras de confiança ativas por um período para que as cargas de trabalho existentes continuem funcionando.

1. Envie a nova âncora de confiança sem desativar a antiga.
2. Ative a nova âncora em cada projeto previsto ou no nível da organização.
3. Atualize as cargas de trabalho para que apresentem certificados de cliente cuja cadeia chegue à nova âncora. Em seguida, teste cada host mTLS e cada interface da 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 na organização e em todos os projetos.

Você pode fazer a rotação dos certificados intermediários sem alterar a âncora de confiança configurada. Apresente a nova cadeia completa nas requisições subsequentes.

Solucionar problemas nas requisições

Use os 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 indica que o PEM enviado não passou na validação. O código expired_certificate indica que o certificado já expirou ou que o tempo restante até a expiração é insuficiente. Já mtls_cel_policy_invalid indica que o filtro não passou na validação, e certificate_in_use indica que você deve desativar o certificado antes de excluí-lo.

Limitações atuais

• Uma organização pode enviar até 50 objetos de certificado.
• O mTLS acrescenta a verificação do certificado à autenticação habitual da API. O certificado por si só não autoriza o acesso à API.
• A OpenAI não busca certificados intermediários por AIA nem faz verificações por CRL ou OCSP.
• O Private Link não é compatível com mTLS. Se você precisar de um caminho de rede privada do Azure, consulte Private Link.
• Os hosts mTLS compatíveis com a API são mtls.api.openai.com, mtls-us.api.openai.com e mtls-eu.api.openai.com. Não presuma que todos os demais hosts regionais da API tenham um host mTLS correspondente.
• A federação de identidade de carga de trabalho com X.509 não retorna um token de atualização nem usa DPoP, uma declaração cnf ou um token de portador vinculado ao certificado. Consulte Configurar a federação de identidade de carga de trabalho com certificados X.509.