SSL Connections

Mongoose supports connecting to MongoDB clusters that require SSL connections. Setting the ssl option to true in mongoose.connect() or your connection string is enough to connect to a MongoDB cluster using SSL:

  1. mongoose.connect('mongodb://localhost:27017/test', { ssl: true });
  3. // Equivalent:
  4. mongoose.connect('mongodb://localhost:27017/test?ssl=true');

The ssl option defaults to false for connection strings that start with mongodb://. However, the ssl option defaults to true for connection strings that start with mongodb+srv://. So if you are using an srv connection string to connect to MongoDB Atlas, SSL is enabled by default.

If you try to connect to a MongoDB cluster that requires SSL without enabling the ssl option, mongoose.connect() will error out with the below error:

  1. MongooseServerSelectionError: connection <monitor> to 127.0.0.1:27017 closed
  2.     at NativeConnection.Connection.openUri (/node_modules/mongoose/lib/connection.js:800:32)
  3.     ...

SSL Validation

By default, Mongoose validates the SSL certificate against a certificate authority to ensure the SSL certificate is valid. To disable this validation, set the sslValidate option to false.

  1. mongoose.connect('mongodb://localhost:27017/test', {
  2.   ssl: true,
  3.   sslValidate: false
  4. });

In most cases, you should not disable SSL validation in production. However, sslValidate: false is often helpful for debugging SSL connection issues. If you can connect to MongoDB with sslValidate: false, but not with sslValidate: true, then you can confirm Mongoose can connect to the server and the server is configured to use SSL correctly, but there’s some issue with the SSL certificate.

For example, a common issue is the below error message:

  1. MongooseServerSelectionError: unable to verify the first certificate

This error is often caused by self-signed MongoDB certificates or other situations where the certificate sent by the MongoDB server is not registered with an established certificate authority. The solution is to set the sslCA option, which essentially sets a list of allowed SSL certificates.

  1. await mongoose.connect('mongodb://localhost:27017/test', {
  2.   ssl: true,
  3.   sslValidate: true,
  4.   // For example, see https://medium.com/@rajanmaharjan/secure-your-mongodb-connections-ssl-tls-92e2addb3c89
  5.   // for where the `rootCA.pem` file comes from.
  6.   // Please note that, in Mongoose >= 5.8.3, `sslCA` needs to be
  7.   // the **path to** the CA file, **not** the contents of the CA file
  8.   sslCA: `${__dirname}/rootCA.pem`
  9. });

Another common issue is the below error message:

  1. MongooseServerSelectionError: Hostname/IP does not match certificate's altnames: Host: hostname1. is not cert's CN: hostname2

The SSL certificate’s common name must line up with the host name in your connection string. If the SSL certificate is for hostname2.mydomain.com, your connection string must connect to hostname2.mydomain.com, not any other hostname or IP address that may be equivalent to hostname2.mydomain.com. For replica sets, this also means that the SSL certificate’s common name must line up with the machine’s hostname.