Enable TLS for a Deployment

On this page

Considerations

Prerequisite
Procedures

For Ops Manager to monitor, deploy, or back up a MongoDB deployment that uses TLS, you must enable TLS for the Ops Manager project.

Considerations

Topics Not in Scope

A full description of Transport Layer Security, public key infrastructure, X.509 certificates, and Certificate Authorities exceeds the scope of this tutorial. This tutorial assumes prior knowledge of TLS and access to valid X.509 certificates.

Note

If you want to reset Authentication and TLS settings for your project, first unmanage any MongoDB deployments that Ops Manager manages in your project.

Prerequisite

Get and Install the TLS Certificate on Each MongoDB Host

Acquire a TLS certificate for each host serving a MongoDB process. This certificate must include the FQDN for the hostname of this MongoDB host. The FQDN must be the Subject Alternative Name of this host. You must install this TLS certificate on the MongoDB host.

Warning

The MongoDB Agent from version 11.12.0.7384 requires that TLS certificates include a value in the Subject Alternative Name field. Before upgrading to 11.12.0.7384, ensure that all TLS certificates used in your MongoDB deployment contain a SAN. To learn more, see Ensure TLS Certificates Contain a Subject Alternative Name.

Procedures

Important

You must complete:

Set Existing Deployments to Use TLS, then
Enable TLS for the Project

before you click Review & Deploy.

Set Existing Deployments to Use TLS

Important

With the Client Certificate Mode setting, you can set if the client must present a TLS certificate to connect to the deployments in your project. If you enable TLS for your project, all deployment must use TLS.

If you wish to enable TLS for existing MongoDB deployments in your Ops Manager project:

Navigate to the Clusters view for your deployment.

If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
If it is not already displayed, click Deployment in the sidebar.

Click the Clusters view.

On the line listing the process, click Modify.

Expand the Advanced Configuration Options section.

Set the TLS/SSL startup options.

Click Add Option to add each of the following options:

Option	Required	Value
`tlsMode`	Required	Select `requireTLS`.
`tlsCertificateKeyFile`	Required	Provide the absolute path to the server certificate.
`tlsCertificateKeyFilePassword`	Required	Provide the PEM key file password if you encrypted it. IMPORTANT: If the encrypted private key for the `.pem` certificate file is in PKCS #8 format, it must use PBES2 encryption operations. The MongoDB Agent does not support PKCS #8 with other encryption operations.
`tlsFIPSMode`	Optional	Select `true` if you want to enable FIPS mode.

After adding each option, click Add.
When you have added the required options, click Save.

Enable TLS for the Project

Navigate to the Security Settings dialog for your deployment.

If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
If it is not already displayed, click Deployment in the sidebar.

Click the Security tab.
Click the Settings tab.
Perform one of the following actions:
- If this is your first time configuring TLS, authentication, or authorization settings for this project, click Get Started.
- If you have already configured TLS authentication, or authorization settings for this project, click Edit.

Choose your Authentication Mechanisms.

On the Select Authentication Mechanisms screen, enable one or more Authentication Mechanisms.
TLS works with all authentication mechanisms.
Click Next.

Specify the TLS Settings.

Field

Action

MongoDB Deployment Transport Layer Security (TLS)

Toggle this slider to ON.

TLS CA File Path

The TLS Certificate Authority file is a .pem-format certificate file that contains the root certificate chain from the Certificate Authority. The MongoDB Agent uses this same Certificate Authority file to connect to every item in your deployment.

The encrypted private key for the .pem certificate file must be in PKCS #1 format. The MongoDB Agent doesn't support the PKCS #8 format.

Type the file path to the TLS Certificate Authority file on every host running a MongoDB process:

Type the file path on all Linux hosts in the first box.
Type the file path on all Windows hosts in the second box.

This enables the net.tls.CAFile setting for the MongoDB processes in the project.

Click Validate to test that each host in your deployment has a TLS Certificate Authority at the paths you specified.

Cluster TLS CA File Path

The .pem file that contains the root certificate chain from the Certificate Authority used to validate the certificate presented by a client establishing a connection. Specify the file name of the .pem file using relative or absolute paths. net.tls.clusterCAFile requires that net.tls.CAFile is set.

If you do not specify the net.tls.clusterCAFile, the cluster uses the .pem file specified in the net.tls.CAFile option.

net.tls.clusterCAFile lets you use separate Certificate Authorities to verify the client-to-server and server-to-client portions of the TLS handshake.

Client Certificate Mode

Select if client applications or MongoDB Agents must present a TLS certificate when connecting to a TLS-enabled MongoDB deployments. Each MongoDB deployment checks for certificates from these client hosts when they try to connect. If you choose to require the client TLS certificates, make sure they are valid.

Accepted values are:

Optional	Every client may present a valid TLS certificate when connecting to MongoDB deployments. MongoDB Agents might use TLS certificates if you don't set the `mongod` `tlsMode` to `None`.
Required	Every MongoDB deployment in this project starts with TLS-encrypted network connections. All Agents must use TLS to connect to any MongoDB deployment.

Configure the MongoDB Agents.

In the Agent Auth Mechanism list, click the same authentication mechanisms that you did for the project.
Follow the procedure to configure the MongoDB Agent to use that authentication method:

Note

If you had TLS certificates for Legacy Agents, see What if I had TLS certificates for Legacy Backup or Monitoring Agents? at the end of this procedure for guidance.

Click Save to set your changes.

Click Review & Deploy to review your changes.

Ops Manager displays your proposed changes.

If you are satisfied, click Confirm & Deploy.
If you want to make further configuration changes, click Cancel. Click Modify for the cluster to make additional changes.

If you updated to the MongoDB Agent from deployments that used Automation, the MongoDB Agent manages the TLS settings.
If you updated to the MongoDB Agent from deployments that did not use Automation but you had Backup Agents, Monitoring Agents, or both, you can set your Backup Agent and Monitoring Agent-specific settings during the Agent update or through the following procedure:
1. Navigate to Deployment Agents Downloads & Settings Custom Configurations Edit Custom Configuration.
2. Click .
3. Under the Backup Configurations section:
  1. Type the desired setting in the Setting box and its corresponding value in the Value box.
  2. To add more than one Setting, click the + Add Setting link. Another row appears.
  3. Repeat until all settings have been added.
4. Under the Monitoring Configurations section:
  1. Type the desired setting in the Setting box and the corresponding value in the Value box.
  2. To add more than one Setting, click the + Add Setting link. Another row appears.
  3. Repeat until all settings have been added.
You can click the to remove any settings that you have added.

Back

Secure Connections to Application Database

Configure LDAP for Ops Manager Users