Connect to a TLS-Enabled Replica Set

Connect to your deployment with mongosh

Connect mongosh to your replica set using the following options:

mongosh "mongodb://mongo0.example.com:27017,mongo1.example.com:27017,mongo2.example.com:27017" \
    --tls --tlsCAFile /etc/ssl/mongodb/ca.pem

• --tls enables TLS encryption for the connection.

• --tlsCAFile is set to the CA certificate that signed the server certificates so that mongosh can verify the server's certificates.

Connecting without a client certificate establishes a TLS-encrypted session but does not authenticate you. To run most commands, you must authenticate with a mechanism such as SCRAM.

Authenticate user

Use the db.auth() method to authenticate with your admin username and password.

Verify your connection

Run the following to confirm your authentication state:

db.adminCommand({ connectionStatus: 1 })

Confirm that authInfo.authenticatedUsers includes the expected user.

Generate a client certificate

Generate a client certificate using the process described in Obtain TLS Server Certificates. Make the following adjustments:

• In your configuration file, set extendedKeyUsage = clientAuth instead of serverAuth.

• The CA that signed your node client-authentication certificates must also sign your client certificate. Generally, this is ca.pem. However, if you obtained separate certificates for client authentication, you might have a different CA for client certificates.

• Name your output files client.key, client.crt, and client.pem instead of the node-specific names used in the certificate tutorial.

After completing the process, copy client.pem to a secure location on the machine where you run mongosh:

cp client.pem /etc/ssl/mongodb/client.pem

Identify your client subject

Identify the subject of your client certificate. You need this value to confirm that you authenticated with the expected client certificate after connecting.

To view the subject, run the following command:

openssl x509 -in /etc/ssl/mongodb/client.pem -noout -subject

Take note of the output, which looks similar to the following:

subject=C=US, ST=New-York, L=New York City, O=MongoDB, CN=myUser

Save the subject name to use later in this tutorial. In this example, the subject name is C=US, ST=New-York, L=New York City, O=MongoDB, CN=myUser.

Connect to your deployment with your client certificate

Connect mongosh to your replica set using the following options:

mongosh "mongodb://mongo0.example.com:27017,mongo1.example.com:27017,mongo2.example.com:27017" \
    --tls \
    --tlsCAFile /etc/ssl/mongodb/ca.pem \
    --tlsCertificateKeyFile /etc/ssl/mongodb/client.pem

• --tls enables TLS encryption for the connection.

• --tlsCAFile is set to the CA certificate that signed the server certificates so that mongosh can verify the server connection.

• --tlsCertificateKeyFile presents the client certificate and private key which the server uses to authenticate your connection with X.509.

This connects you to your MongoDB deployment over TLS.

Authenticate as an admin user

Use the db.auth() method to authenticate with your admin username and password.

Create a user in the $external database

Create a user in the $external database that corresponds to your client certificate's subject name with the db.createUser() method. Replace the username with the subject of your client certificate that you identified previously:

db.getSiblingDB("$external").runCommand({
   createUser: "C=US, ST=New-York, L=New York City, O=MongoDB, CN=myUser",
   roles: [
      { role: "readWriteAnyDatabase", db: "admin" }
   ]
})

After you create a user, use the db.auth() method to authenticate to the $external database using X.509:

db.getSiblingDB("$external").auth({
    mechanism: "MONGODB-X509",
    user: "C=US, ST=New-York, L=New York City, O=MongoDB, CN=myUser"
})

Verify your connection

Run the following to confirm your authentication state:

db.adminCommand({ connectionStatus: 1 })

Confirm that authInfo.authenticatedUsers includes the expected user.