/ /

Habilitar TLS en una Conexión

Overview

En esta guía, puedes aprender cómo conectarte a instancias de MongoDB con el protocolo de seguridad TLS.

Para configurar tu conexión para usar TLS, habilita la opción TLS y proporciona tus certificados para la validación.

Tip

Para aprender más información sobre TLS, consulta la entrada de Wikipedia sobre Seguridad de la capa de transporte.

Habilitar TLS

Puedes habilitar TLS en una conexión a tu instancia de MongoDB de las siguientes maneras:

Configurar la opción tls en true en su objeto MongoClientOptions
Establecer la opción tls en true en tu cadena de conexión

Una instancia de MongoClient puede conectarse con TLS si estableces tls en true en tu objeto MongoClientOptions:

const client = new MongoClient(uri, { tls: true });

Una instancia de MongoClient puede conectarse con TLS si configura la opción tls en true en su cadena de conexión:

const uri = "mongodb://<hostname>:<port>?tls=true";
const client = new MongoClient(uri, myClientSettings);

Nota

Si usas un registro DNS SRV al conectarte a MongoDB especificando la modificación +srv en tu cadena de conexión, activas TLS en tu conexión por defecto. Para desactivarlo, establece el valor del parámetro tls o ssl en false en tu cadena de conexión u objeto MongoClientOptions.

Para obtener más información sobre el comportamiento de conexión cuando se utiliza una lista de nodos iniciales DNS, consulte la sección SRV Connection Format en el manual del Servidor.

Nota

Solución para un error de "renegociación heredada insegura deshabilitada"

El controlador Node.js depende de OpenSSL por defecto. Los proxies SSL obsoletos pueden causar un error unsafe legacy renegotiation disabled en entornos que usan OpenSSL 3.0 o posterior. Puedes resolver este error configurando la opción SSL_OP_LEGACY_SERVER_CONNECT, como se muestra en el siguiente ejemplo:

import { MongoClient } from 'mongodb';
import crypto from 'crypto';
const client = new MongoClient("mongodb+srv://...", {
   secureContext: {
      secureOptions: crypto.constants.SSL_OP_LEGACY_SERVER_CONNECT
   }
});

Además de la opción del cliente tls, el controlador ofrece más opciones para configurar TLS en tu conexión. Para propósitos de prueba, puedes configurar las opciones del cliente tlsAllowInvalidHostnames, tlsAllowInvalidCertificates y tlsInsecure.

Configurar la opción tlsAllowInvalidHostnames en true deshabilita la verificación del nombre de host, y configurar tlsAllowInvalidCertificates en true deshabilita la validación del certificado. Configurar la opción tlsInsecure en true desactiva tanto la validación del certificado como la del nombre de host.

Advertencia

Especificar cualquiera de estas opciones en un entorno de producción hace que tu aplicación sea insegura y potencialmente vulnerable a certificados caducados y a procesos externos que se hagan pasar por instancias de cliente válidas.

Para ver una lista completa de las opciones del cliente, consulta Especificar opciones de conexión.

Configurar certificados

Para iniciar correctamente una solicitud TLS, una aplicación debe demostrar su identidad haciendo referencia a certificados criptográficos. Para conectarte a MongoDB con TLS, tus certificados deben almacenarse como archivos PEM.

Importante

Para el uso en producción, recomendamos que tu implementación de MongoDB use certificados válidos generados y firmados por la misma autoridad certificadora. Para pruebas, puedes utilizar certificados autofirmados.

La siguiente lista describe los componentes necesarios para establecer una conexión con TLS:

Componente TLS	Descripción
Autoridad certificadora (CA)	Una o más autoridades de certificación en las que confiar al realizar una conexión TLS.
Certificado de cliente	Un certificado digital y una clave que permiten al servidor verificar la identidad de su aplicación para establecer una conexión de red cifrada.
Clave del certificado	El archivo de clave privada del certificado de cliente. Esta clave a menudo se incluye dentro del propio archivo de certificado.
Frase de contraseña	La contraseña para descifrar la clave privada del cliente si está cifrada.

Tip

Para obtener más información sobre el formato PEM, consulta la entrada de Wikipedia sobre Correo Mejorado en Privacidad.

Certificados de referencia en un cliente

Debe referenciar sus certificados en su objeto MongoClientOptions para que el servidor pueda validarlos antes de que el cliente se conecte. Puedes hacer referencia a tus certificados de las siguientes maneras:

Crea un objeto SecureContext para almacenar certificados (Recomendado)
Proporcione cadenas de ruta de archivo que apunten a sus certificados
Crear Buffer objetos para almacenar certificados

Crea un objeto SecureContext para almacenar los certificados

Recomendamos que utilice la opción secureContext para configurar la conexión TLS. Los objetos SecureContext son nativos de Node.js y permiten mantener todas las opciones TLS en un único objeto reutilizable.

Para crear un objeto SecureContext, importa el método createSecureContext() del módulo tls. A continuación, llama al método createSecureContext() y pasa el contenido de tus certificados en el parámetro options. Este método devuelve un objeto SecureContext que puedes usar en tu objeto MongoClientOptions.

El siguiente código muestra cómo crear un objeto SecureContext y pasarlo a tu 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 obtener más información sobre el método createSecureContext() y el paquete tls, consulta la Documentación de la API TLS de Node.js.

Para un ejemplo ejecutable que utilice un objeto SecureContext, consulta el Ejemplo de SecureContext.

Proporcione las rutas de archivos de los certificados

Puedes incluir las rutas de los archivos de tus certificados como opciones del cliente para recuperar tus certificados al conectarte con TLS. El driver lee estos archivos cuando llamas al método connect() en tu instancia de MongoClient.

El siguiente código muestra cómo proporcionar rutas de archivos de certificados como opciones en su MongoClient:

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

Nota

Archivos CRL

Tu configuración TLS podría requerir que presentes una lista de revocación de certificados (CRL) al conectarte a MongoDB. A partir de la versión 6.0 del driver, puedes proporcionar la ruta de archivo de tu archivo CRL en la opción tlsCRLFile de tu cadena de conexión o en tu instancia MongoClientOptions.

Crear objetos intermedios para almacenar los certificados

Puedes pasar el contenido de tus archivos de certificados como objetos de Buffer en las opciones de tu cliente para conectarte con TLS.

El siguiente código muestra cómo leer el contenido de los archivos del certificado y pasar los objetos resultantes de Buffer como opciones en tu 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 });

Ejemplo de SecureContext

Este ejemplo muestra cómo crear un objeto SecureContext y una instancia MongoClient que incluya opciones de TLS. El ejemplo se conecta a MongoDB y ejecuta una query:

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);

Información Adicional

Para obtener más información sobre cómo habilitar TLS en una conexión, consulte la siguiente documentación del manual del servidor:

Documentación de la API

Volver

Encriptación en uso

Proxy SOCKS