This version of the documentation is archived and no longer supported. To learn how to upgrade your version of MongoDB Ops Manager, refer to the upgrade documentation.
You were redirected from a different version of the documentation. Click here to go back.
This version of the manual is no longer supported.

Configure the Monitoring Agent User for x.509 Client Certificate Authentication

Ops Manager enables you to configure the Authentication Mechanisms that all clients, including the Ops Manager Agents, use to connect to your MongoDB deployments. You can enable multiple authentication mechanisms for each of your projects, but you must choose only one mechanism for the Agents.

MongoDB supports x.509 certificate authentication for use with a secure TLS/SSL connection. The x.509 client authentication allows clients to authenticate to servers with certificates rather than with a username and password.


Ops Manager can manage Agent authentication for you if you enable Automation. With Automation, Ops Manager creates the users for each Agent and configures the Agent appropriately. To learn more about authentication, see Enable x.509 Authentication for your Ops Manager Project.


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.


To enable x.509 Authentication for Ops Manager, you must obtain valid certificates generated and signed by a single certificate authority. Refer to the Client x.509 Certificate in the MongoDB Manual for more about the certificate requirements.

x.509 Client Certificate Authentication requires you to enable and configure TLS/SSL for the deployment.


This tutorial assumes that you have already configured your MongoDB deployment to use x.509 certificate authentication and SSL. If you have not done so, refer to the Use x.509 Certificates to Authenticate Clients and Configure mongod and mognos for TLS/SSL tutorials.

Create MongoDB User for the subject

In order for the Monitoring Agent to connect to your MongoDB deployment, you must create a user for the Monitoring Agent in the $external database.

For x.509 certificate authentication, use the subject value of your client certificate as the username.

Use the following commands to create the users from a mongo shell connected to your MongoDB deployment:

use $external
      user: "<x.509 subject>",
      roles: [ { role: "clusterMonitor", db: "admin" } ]

See Required Access for Monitoring Agent for more information on the required access.

You can only associate an x.509 client certificate with a single user: each user must have its own certificate. However, you may use the same user for both the Monitoring and Backup Agents. If you choose to use the same user for both agents, ensure that the user possesses the required permissions for both the monitoring agent and the Backup Agent.

Edit Agent Configuration File

x.509 requires that you configure the agent for SSL:


Specify path to trusted CA certificate.

If your MongoDB deployment uses SSL, then you must configure the Monitoring Agent to use SSL. To configure the agent to use SSL, you must have a trusted CA certificate that signed the MongoDB instance’s certificate.

In the agent’s install directory, edit the monitoring-agent.config file to set sslTrustedServerCertificates field to the path of a file containing one or more certificates in PEM format. For example if you would use the following command to connect through the mongo shell:

mongo --ssl --sslCAFile /etc/ssl/ca.pem

Then you would set:


By default, the sslRequireValidServerCertificates setting is true, and a valid trusted certificate is required to connect to MongoDB instances using SSL.

When the Monitoring is managed by the Automation, this setting cannot be set to false. However, you can set sslRequireValidServerCertificates to false if you install and configure the Monitoring manually. When sslRequireValidServerCertificates is false, you do not need to set the sslTrustedServerCertificates setting because Ops Manager will not verify the certificates.


Setting sslRequireValidServerCertificates to false makes connections between the Monitoring and MongoDB databases susceptible to man-in-the-middle attacks. Setting sslRequireValidServerCertificates to false is recommended only for testing and not for production.

For additional information on these settings, including client certificate support, see MongoDB TLS Settings.


Restart the agent.

Configure Monitoring Agent for SSL provides more details about configuring the Monitoring Agent for SSL.

Once you have configured the Monitoring agent, you still need to configure the x.509 Authentication mechanism in the Ops Manager interface, as described in Enable x.509 Authentication for your Ops Manager Project.