Navigation
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.

Enable x.509 Authentication for your Ops Manager Group

On this page

Overview

Ops Manager enables you to configure the Authentication Mechanisms that the Ops Manager Agents use to connect to your MongoDB deployments from within the Ops Manager interface. You can enable multiple authentication mechanisms for your group, but you must choose a single mechanism for the Agents to use to authenticate to your deployment.

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

In Ops Manager, x.509 Client Certificate (MONGODB-X509) is only available on MongoDB Enterprise builds. If you have existing deployments running on a MongoDB Community build, you must upgrade them to MongoDB Enterprise before you can enable x.509 Client Certificate (MONGODB-X509) for your Ops Manager group.

Note

As of Ops Manager 2.0, using x.509 certificates for membership authentication is supported.

Prerequisites

Important

A full description of Public Key Infrastructure (PKI), including certificates and Certificate Authorities, is beyond the scope of this tutorial. This tutorial assumes prior knowledge of SSL and PKI as well as access to valid x.509 certificates.

To enable x.509 Authentication for Ops Manager, you must:

  • Obtain valid certificate files (PEM Key files) generated and signed by a single certificate authority (CA) for:

    • Certificate Only in PEM file:
      • The CA itself
    • Certificate and Private Key in PEM file:
      • Each agent (Automation, Monitoring if used and Backup if used)
      • Each hostname of a managed MongoDB server (if member X.509 authentication is used)
      • Each client that may attach to the MongoDB instance

  • Generate LDAPv3 distinguished name from each Agents’ PEM Key file. Consult the documentation for whichever SSL implementation you use.

    Example

    For OpenSSL, the command to generate the LDAPv3 DN from a PEM Key File called automation.pem is:

    openssl x509 -in automation.pem -inform PEM -subject -nameopt RFC2253

Note

See Client x.509 Certificate in the MongoDB Manual for certificate requirements.

Important

If at any point you wish to reset the authentication settings for your group and start again, see Clear Security Settings for more information.

Procedures

These procedures describe how to configure and enable x.509 authentication when using Automation. If Ops Manager does not manage your Monitoring or Backup agents, you must manually configure them to use x.509 authentication.

Note

See Configure the Monitoring Agent User for x.509 Client Certificate Authentication and Configure Backup Agent User for x.509 Client Certificate Authentication for instructions.

Prepare an Existing Deployment for x.509 Certificate Authentication

Important

X.509 Client Certificate authentication requires SSL. If Ops Manager manages one or more existing deployments, SSL must be enabled on each process in the MongoDB deployment before enabling x.509 authentication.

Note

If SSL is already enabled, you may skip this procedure.

1

Click the Deployment tab, then click the Deployment page.

2

Select the process that you wish to modify.

  1. Click the first icon to the right of Processes to switch to that view.
  2. Click the process that you wish to edit.
  3. Click the wrench icon to the right of that process to modify it.
3

Expand the Advanced Options area.

4

Set the SSL startup options.

  1. Click Add Option to add each option.

    Option Value
    sslmode Select requireSSL.
    sslPemKeyFile Provide the path to the client certificate.
    sslPemKeyPassword If you encrypted the PEM key file, provide its password.

  2. When you have added the required settings, click Apply.

Configure an Existing Deployment for x.509 Member Certificate Authentication

Note

This procedure is optional. It enables members of a replica set or sharded cluster to also use x.509 certificates to authenticate each other. If it is not configured, replica set and sharded cluster members can still authenticate with each other using keyFile authentication.

1

Click the Deployment tab, then click the Deployment page.

2

Select the process that you wish to modify.

  1. Click the first icon to the right of Processes to switch to that view.
  2. Click the process that you wish to edit.
  3. Click the wrench icon to the right of that process to modify it.
3

Expand the Advanced Options area.

4

Set the x.509 startup options.

  1. Click Add Option to add each option.

    Option Value
    clusterAuthMode Select x509.
    clusterFile Provide the path to the member PEM Key file.

  2. When you have added the required settings, click Apply.

When you have configured the SSL options for each deployed process, you can proceed to enable x.509 authentication for your Ops Manager group.

Enable x.509 Client Certificate Authentication for your Ops Manager Group

1

Click the Deployment tab, then click the Deployment page.

2
3

Check X.509 Client Certificate (MONGODB-X509), then click Next.

4

Enable and configure SSL.

  1. Provide the following settings:

    Setting Value
    Enable SSL Select Yes.
    SSL CA File Path Provide the path on the server to the certificate authority PEM Key file.
    Client Certificate Mode Select REQUIRED.

  2. Click Next.

5

Configure the Authentication Mechanism for the Agents.

If you enable more than one authentication mechanism, you must specify which one of the authentication mechanisms the Ops Manager agents should use to connect to your deployment.

  1. Select X.509 Client Certificate (MONGODB-X509) from the Agent Auth Mechanism drop-down menu.

  2. For each Agent, provide:

    Setting Value
    <Agent> Username Enter the LDAPv3 distinguished name derived from the Agent’s PEM Key file.
    <Agent> PEM Key file Provide the path and filename for the Agent’s PEM Key file on the server on the line for the appropriate operating system.
    <Agent> PEM Key Password Provide the password to the PEM Key file if it was encrypted.

  3. Click Save.

You do not need to configure all of the agents, only the ones you installed.

Example

If you did not install the Backup agent, you do not need to configure the Backup agent.

6

Click Review & Deploy to review your changes.

7

Review and approve your changes.

Ops Manager displays your proposed changes.

  1. If they are acceptable, click Confirm & Deploy.
  2. If they are unacceptable, click Cancel and you can make additional changes.

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.