Menu Docs
Página inicial do Docs
/
Idiomas
/
JavaScript
/
Node.js
/
Fundamentals
/
Conexão

Habilitar TLS em uma conexão

Nesta página

  • Visão geral
  • Habilitar TLS
  • Configurar certificados
  • Certificados de referência em um cliente
  • Crie um objeto SecureContext para armazenar certificados
  • Forneça caminhos de arquivo de certificados
  • Criar objetos de buffer para armazenar certificados
  • Exemplo de SecureContext
  • Informações adicionais
  • Documentação da API

Visão geral

Neste guia, você verá como se conectar a instâncias do MongoDB com o protocolo de segurança TLS.

Para configurar sua conexão para usar TLS, habilite a opção TLS e forneça seus certificados para validação.

Dica

Para saber mais sobre o TLS, consulte a página da Wikipedia sobre Transport Layer Security.

Habilitar TLS

Você pode habilitar o TLS em uma conexão com sua instância MongoDB das seguintes maneiras:

  • Definindo a opção tls como true no seu objeto MongoClientOptions

  • Definindo a opção tls para true em sua connection string

Observação

Se você usar um registro SRV DNS quando se conectar ao MongoDB especificando a modificação +srv em sua string de conexão, você habilita o TLS na conexão por padrão. Para desativá-lo, defina o valor do parâmetro tls ou ssl como false em sua string de conexão ou objeto MongoClientOptions.

Para saber mais sobre o comportamento da conexão ao usar uma lista de sementes DNS, consulte a seção Formato de conexão SRV no manual do servidor.

Além da opção tls do cliente, o driver fornece opções adicionais para configurar o TLS na sua conexão. Para fins de teste, você pode definir as opções tlsAllowInvalidHostnames, tlsAllowInvalidCertificates e tlsInsecure do cliente.

Definir a opção tlsAllowInvalidHostnames como true desabilita a verificação do nome do host, e definir o tlsAllowInvalidCertificates como true desabilita a validação do certificado. Definir a opção tlsInsecure como true desabilita a validação tanto do certificado quanto do nome do host.

Aviso

Ao especificar qualquer uma dessas opções em um ambiente de produção, seu aplicativo ficará desprotegido e potencialmente vulnerável a certificados expirados e a processos externos que se apresentam como instâncias de cliente válidas.

Para obter uma lista completa das opções de clientes, veja Opções de conexão.

Configurar certificados

Para iniciar com êxito uma solicitação de TLS, um aplicativo deve provar sua identidade fazendo referência a certificados criptográficos. Para se conectar ao MongoDB com TLS, seus certificados devem estar armazenados como arquivos PEM.

Importante

Para uso em produção, seu deployment do MongoDB deve usar certificados válidos gerados e assinados pela mesma autoridade de certificação. Para testar, você pode usar certificados auto assinados.

A lista abaixo descreve os componentes necessários para estabelecer uma conexão com o TLS:

Componente TLS
Descrição
Autoridade de certificação (CA)
Uma ou mais autoridades de certificação para confiar ao fazer uma conexão TLS.
Certificado de cliente
Um certificado digital e uma chave que permitem que o servidor verifique a identidade do seu aplicativo para estabelecer uma conexão de rede criptografada.
Chave de certificado
O arquivo de chave privada de certificado do cliente. Essa chave geralmente é incluída no próprio arquivo de certificado.
Senha
A senha para descriptografar a chave de cliente privada se estiver criptografada.

Dica

Para saber mais sobre o formato PEM, veja o Wikipedia sobre Privacy-Enhanced Mail.

Certificados de referência em um cliente

Você deve fazer referência aos seus certificados em seu objeto MongoClientOptions para que o servidor possa validá-los antes que o cliente se conecte. Você pode fazer referência a seus certificados das seguintes maneiras:

  • Crie um objeto SecureContext para armazenar certificados (Recomendado)

  • Forneça strings de caminho de arquivo que apontam para seus certificados

  • Criar objetos Buffer para armazenar certificados

Crie um objeto SecureContext para armazenar certificados

Recomendamos que você use a opção secureContext para configurar sua conexão TLS. Objetos SecureContext são nativos do Node.js e permitem que você mantenha todas as suas opções de TLS em um único objeto reutilizável.

Para criar um objeto SecureContext, importe o método createSecureContext() do módulo tls. Em seguida, chame o método createSecureContext() e passe o conteúdo dos seus certificados no parâmetro de opções. Este método gera um objeto SecureContext que você pode usar no objeto MongoClientOptions.

O seguinte código mostra como criar um objeto SecureContext e transmiti-lo ao seu cliente:

// Create a SecureContext object
const secureContext = tls.createSecureContext({
  ca: fs.readFileSync(`<path to CA certificate>`),
  cert: fs.readFileSync(`<path to public client certificate>`),
  key: fs.readFileSync(`<path to private client key>`),
});
// Pass the SecureContext as a client option
const client = new MongoClient(uri, { tls: true, secureContext });

Para saber mais sobre o método createSecureContext() e o pacote tls, consulte a documentação da API TLS do Node.js.

Para um exemplo executável que utiliza um objeto SecureContext, consulte o Exemplo de SecureContext.

Forneça caminhos de arquivo de certificados

Você pode incluir os caminhos de arquivo para seus certificados como opções de cliente para recuperar seus certificados durante a conexão com TLS.

O código abaixo mostra como fornecer caminhos de arquivo de certificado como opções em seu MongoClient:

// Pass filepaths as client options
const client = new MongoClient(uri, {
  tls: true,
  tlsCAFile: `<path to CA certificate>`,
  tlsCertificateFile: `<path to public client certificate>`,
  tlsCertificateKeyFile: `<path to private client key>`,
});

Criar objetos de buffer para armazenar certificados

Você pode passar o conteúdo dos seus arquivos de certificado como objetos Buffer nas suas opções de cliente para se conectar ao TLS.

O seguinte código mostra como ler o conteúdo dos seus arquivos de certificado e passar os objetos Buffer resultantes como opções em seu MongoClient:

// Read file contents
const ca = fs.readFileSync(`<path to CA certificate>`);
const cert = fs.readFileSync(`<path to public client certificate>`);
const key = fs.readFileSync(`<path to private client key>`);
// Pass Buffers as client options
const client = new MongoClient(uri, { tls: true, ca, cert, key });

Exemplo de SecureContext

Esse exemplo mostra como criar um objeto SecureContext e uma instância MongoClient que inclui opções TLS. O exemplo se conecta ao MongoDB e executa uma query de localização:

import { MongoClient } from "mongodb";
import * as fs from "fs";
import * as tls from "tls";
// Replace the uri string with your connection string.
const uri = "<connection uri>";
// Replace the filepaths with your certificate filepaths.
const secureContext = tls.createSecureContext({
  ca: fs.readFileSync(`<path to CA certificate>`),
  cert: fs.readFileSync(`<path to public client certificate>`),
  key: fs.readFileSync(`<path to private client key>`),
});
// Create a client with the secureContext option
const client = new MongoClient(uri, { tls: true, secureContext });
async function run() {
  try {
    const db = client.db("myDB");
    const myColl = db.collection("myColl");
    const doc = await myColl.findOne({});
    console.log(doc);
  } finally {
    await client.close();
  }
}
run().catch(console.dir);

Informações adicionais

Para obter mais informações sobre como habilitar o TLS em uma conexão, consulte a seguinte documentação de manual do servidor:

Documentação da API

← Compactação de rede
Stable API →

Nesta página