O TLS mútuo da OpenAI permite que as organizações configurem uma camada adicional de segurança para o tráfego da API da OpenAI. Depois de configuradas, as solicitações de API devem ser feitas para https://mtls.api.openai.com (ou https://mtls-eu.api.openai.com para clientes de residência de dados na UE), e o tráfego só será aceito se a chave de API e o certificado de cliente corretos forem fornecidos. O mTLS não se aplica ao painel https://platform.openai.com. Este recurso está atualmente em beta.
Como configuro a integração mTLS?
Na barra de navegação de configurações, você verá uma guia “TLS mútuo”.
Carregar certificado
Ativar certificado
Depois de carregar seu certificado, a próxima etapa é ativar seu certificado. Depois que um certificado for ativado para um projeto, todas as solicitações de API destinadas a esse projeto também passarão a exigir um certificado de cliente correspondente. Se um projeto tiver vários certificados ativados, você poderá passar qualquer certificado de cliente correspondente. Se um certificado for ativado para a organização, ele será aplicado a todas as solicitações de API e será “herdado” por todos os projetos.
Requisitos de certificado de CA
Você pode carregar qualquer certificado de CA X.509 em formato PEM que atenda aos seguintes requisitos:
assina diretamente os certificados de cliente que você pretende usar ou ancora uma cadeia de certificados válida apresentada pelo seu cliente.
tem as extensões Certificate Authority, Subject Key Identifier e Authority Key Identifier (no formato KeyIdentifier)
tem as permissões Key Usage: “Certificate Sign, CRL Sign”
não está configurado para expirar dentro de 1 dia
o tamanho total do certificado deve ser inferior a 16 kb.
Requisitos de certificado de cliente
Se o suporte a cadeias de certificados estiver ativado para sua organização, seu cliente poderá apresentar um certificado de cliente folha e os certificados intermediários necessários para criar uma cadeia válida até um certificado carregado ativo. Caso contrário, os certificados de cliente devem ser assinados diretamente por certificados que você carregou com antecedência. Além disso, seus certificados de cliente devem atender aos seguintes requisitos:
tem as extensões Subject Key Identifier e Authority Key Identifier (no formato KeyIdentifier)
tem as permissões Key Usage: “Digital Signature, Key Encipherment”
tem a permissão Extended Key Usage: “TLS Web Client Authentication”
tem a extensão Subject Alternate Name
Suporte a cadeias de certificados para mTLS da API
O suporte a cadeias de certificados permite que seu cliente apresente um certificado de cliente folha com os certificados intermediários necessários para criar uma cadeia válida até um certificado carregado ativo.
Isso pode permitir que você rotacione certificados intermediários sem carregar cada novo intermediário, desde que o certificado carregado ativo usado como âncora de confiança continue válido.
No momento, o suporte a cadeias de certificados está disponível mediante solicitação. Entre em contato com seu Diretor de Contas ou abra um chamado de suporte para solicitar acesso.
Seu cliente deve apresentar todos os certificados intermediários necessários. A OpenAI não busca certificados intermediários ausentes por meio de AIA. Verificações CRL e OCSP continuam sem suporte.
Perguntas frequentes
Posso configurar mTLS via API?
Sim — você pode consultar a Referência da API em https://platform.openai.com/docs/api-reference/ para obter mais informações.
Quais endpoints são compatíveis com mTLS?
Durante este período beta, o mTLS é oficialmente compatível com
/v1/chat/completions (with all supported extensions e.g. image, audio, streaming, etc.)/v1/completions/v1/embeddings/v1/audio/transcriptions/v1/audio/speech/v1/files/v1/batches/v1/responses/v1/images/v1/moderations/v1/realtime (via server-side web sockets)/v1/fine_tuning/v1/tunnels
Como envio certificados de cliente com minha solicitação?
Para uma solicitação cURL, você pode usar as opções --cert e --key (consulte a página de manual aqui). Na maioria dos outros clientes HTTP, também há maneiras de passar certificados de cliente. Exemplos: requests em Python, fetch em JS. Por meio dos nossos SDKs oficiais, também oferecemos suporte à substituição do cliente HTTP — veja aqui um exemplo em Python.
Quando o suporte a cadeias de certificados estiver ativado, configure seu cliente HTTP para apresentar o certificado de cliente folha e todos os certificados intermediários necessários. A configuração exata depende do seu cliente HTTP.
Antes de exigir mTLS para o tráfego de produção, verifique se o cliente HTTP que você está usando funciona bem com solicitações de certificado de cliente (alguns, como WebSockets em determinados navegadores, não funcionam). Observe que nosso servidor não fornece uma lista certificate_authorities na solicitação de certificado de cliente.
Quem pode acessar e modificar certificados?
Por meio da interface do painel https://platform.openai.com/settings/organization/mtls, os proprietários da organização podem acessar e modificar certificados. Qualquer pessoa com uma chave de API de administrador (https://platform.openai.com/settings/organization/admin-keys) também pode acessar/modificar certificados, mas atenção — se você ativar o TLS mútuo no nível da organização, também imporá certificados a essas solicitações de API. Todas as alterações de mTLS ficam visíveis nos logs de auditoria.
Quantos certificados posso ter?
Cada organização pode carregar até 50 certificados, que podem ser compartilhados entre projetos, mas não com outras organizações. Você pode ativar/desativar um certificado de forma atômica para 10 projetos por vez. Como alternativa, você pode ativar/desativar 10 certificados por vez para sua organização ou para 1 projeto específico.
Posso atualizar ou excluir certificados?
Você pode atualizar os nomes dos seus certificados, mas não o conteúdo. Você também pode excluir certificados se eles não estiverem ativos no momento em nenhum escopo.
Como funciona a revogação de certificados?
No momento, não oferecemos suporte a verificações CRL ou OCSP. A alternativa recomendada é excluir ou rotacionar sua chave de API. Você também pode trocar seus certificados de CA ou usar certificados de cliente com períodos de validade mais curtos.
Posso usar cadeias de certificados mais longas?
Sim, se o suporte a cadeias de certificados estiver ativado para sua organização. Seu cliente deve apresentar o certificado de cliente folha e todos os certificados intermediários necessários para que a OpenAI possa verificar a cadeia até um certificado carregado ativo. Entre em contato com seu Diretor de Contas ou abra um chamado de suporte para solicitar acesso.
Qual é a configuração recomendada?
Ao configurar inicialmente este recurso, recomendamos começar com um projeto de staging que não atenda tráfego oficial de produção. Aproveite essa oportunidade para garantir que seus certificados estejam configurados corretamente em suas máquinas e que você consiga enviar tráfego de API com sucesso. Além disso, recomendamos consultar a equipe de segurança da sua organização para entender melhor suas necessidades.
Suporte adicional
Você pode usar o recurso mTLS de forma totalmente autônoma pelo painel e pela API. No entanto, se quiser habilitar o mTLS inicialmente em modo sombra, fale com seu Diretor de Conta ou abra um chamado de suporte iniciando um novo chat no canto inferior direito desta página.
Apêndice: Terminologia
Certificado de CA: um dos seus certificados confiáveis usados para verificar certificados de cliente. Ele pode assinar diretamente os certificados de cliente que você envia com as solicitações ou ancorar uma cadeia de certificados apresentada pelo seu cliente. Você pode usar certificados de CA autoassinados.
Carregar um certificado: adicionar um certificado de CA à sua conta. Ele ainda não é aplicado em nenhum lugar para mTLS, mas você já pode começar a configurá-lo.
Escopo: um projeto específico ou toda a sua organização.
Ativar um certificado de CA em um escopo: habilita mTLS especificamente para esse escopo, e todas as solicitações baseadas em chave de API devem incluir um certificado de cliente que possa ser verificado em relação ao certificado de CA ativo.
Desativar um certificado de CA em um escopo: desabilita o uso deste certificado para verificar solicitações nesse escopo. Se não restar nenhum certificado para o escopo, o mTLS ficará efetivamente desativado.
Herdar um certificado: se você ativar um certificado para sua organização, ele também será ativado para todos os projetos.