• Security >
• Enable Authentication for a Cloud Manager Project >
• Enable x.509 Authentication for your Cloud Manager Project

Enable x.509 Authentication for your Cloud Manager Project

Cloud Manager enables you to configure the Authentication Mechanisms that all clients, including the Cloud 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 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.

Note

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

Prerequisites

Important

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.

Procedures

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

Note

To learn more, see Configure the MongoDB Agent for X.509 Authentication.

Prepare an Existing Deployment for x.509 Certificate Authentication

Important

Using x.509 client certificate authentication requires TLS/SSL. If Cloud Manager manages one or more existing deployments, TLS/SSL must be enabled on each process in the MongoDB deployment before enabling x.509 authentication.

Note

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

1

Navigate to the Clusters view for your deployment.

1. If it is not already displayed, select the organization that contains your desired project from the office icon Organizations menu in the navigation bar.
2. If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
3. If it is not already displayed, click Deployment in the sidebar.
4. Click the Clusters view.

2

On the line listing the process, click Modify.

3

Expand the Advanced Configuration Options section.

4

Set the TLS/SSL startup options.

1. 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.
   tlsFIPSMode	Optional	Select true if you want to enable FIPS mode.

2. After adding each option, click Add.

3. When you have added the required options, click Save.

5

Click Save.

6

Click Review & Deploy to review your changes.

7

Click Confirm & Deploy to deploy your changes.

Otherwise, click Cancel and you can make additional changes.

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.

This Procedure is Irreversible

If you enable x.509 member certificate authentication for any deployment in a project, you can’t disable x.509 member certificate authentication for the deployment or disable x.509 client authentication at the project level. The project must use x.509 client authentication.

Enabling x.509 member certificate authentication for a deployment in a project doesn’t enable or require x.509 member certificate authentication for other deployments in the project. You can optionally enable each other deployment in the project to use x.509 member certificate authentication.

1

Navigate to the Clusters view for your deployment.

1. If it is not already displayed, select the organization that contains your desired project from the office icon Organizations menu in the navigation bar.
2. If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
3. If it is not already displayed, click Deployment in the sidebar.
4. Click the Clusters view.

2

On the line listing the process, click Modify.

3

Expand the Advanced Configuration Options section.

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. After each option, click Add.

5

Click Save.

6

Click Review & Deploy to review your changes.

7

Click Confirm & Deploy to deploy your changes.

Otherwise, click Cancel and you can make additional changes.

When you have configured the TLS/SSL options for each deployed process, you can proceed to enable x.509 authentication for your Cloud Manager project.

Enable x.509 Client Certificate Authentication for your Cloud Manager Project

1

Navigate to the Authentication & TLS Settings dialog for your deployment.

1. If it is not already displayed, select the organization that contains your desired project from the office icon Organizations menu in the navigation bar.
2. If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
3. If it is not already displayed, click Deployment in the sidebar.
4. Click the Security tab.
5. Click the Authentication & SSL tab.
6. Click Edit Settings.

2

Select X.509 Certificates.

1. Select X.509 Client Certificate (MONGODB-X509).
2. Click Next.

3

Configure the LDAP Authorization Settings. (Optional)

Important

Using LDAP Authorization, MongoDB 3.4 allows authenticating users via LDAP, Kerberos, or X.509 certificates without requiring local user documents in the $external database. When such a user successfully authenticates, MongoDB performs a query against the LDAP server to retrieve all groups which that LDAP user possesses and transforms those groups into their equivalent MongoDB roles.

This feature is available only for MongoDB 3.4 or later.

If you do not use LDAP Authorization, you can click Skip.

If you use LDAP Authorization, complete the following steps.

1. Enter values for the following fields:

   Setting	Value
   Authorization Query Template	Specify a template for an LDAP query URL to retrieve the list of LDAP groups for an LDAP user.
   User to Distinguished Name Mapping	Specify an array of JSON documents that provide the ordered transformation(s) MongoDB performs on the authenticated MongoDB usernames. MongoDB then matches the transformed username against the LDAP DNs.

2. Click Use LDAP Authorization.

3. Provide the following values:

   Setting	Value
   Servers	Specify the hostname:port combination of one or more LDAP servers.
   Transport Security	Select TLS to encrypt your LDAP queries. If you do not need to encrypt the LDAP queries, select None.
   Timeout (ms)	Specify how long an authentication request should wait before timing out.
   Bind Method	Select either Simple or SASL. Important If you choose the Simple bind method, select TLS from the Transport Security because the Simple bind method passes the password in plain text.
   SASL Mechanisms	Specify which SASL authentication service MongoDB uses with the LDAP server.
   Query User	Specify the LDAP Distinguished Name to which MongoDB binds when connecting to the LDAP server.
   Query Password	Specify the password with which MongoDB binds when connecting to an LDAP server.
   LDAP User Cache Invalidation Interval (s)	Specify how long MongoDB waits to flush the LDAP user cache. Defaults to 30 seconds.
   Validate LDAP Server Config	Select True to validate the LDAP server configuration or False to skip validation. If True and the configuration is invalid, the MongoDB deployment will not start.

4. Click Next.

4

Enable and configure SSL.

1. Provide the following settings:

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

2. Click Next.

5

Configure X.509 Client Certificate (MONGODB-X509) for the Agents.

You can enable more than one authentication mechanism for your MongoDB deployment, but the Cloud Manager Agents can only use one authentication mechanism. Select X.509 Client Certificate (MONGODB-X509) to connect to your MongoDB deployment.

1. Click X.509 Client Certificate (MONGODB-X509) in 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.
   <Agent> LDAP Group DN	Enter the Distinguished Name for the Agent’s LDAP Group. Note You only need to provide the Agent’s LDAP Group DN if you use LDAP Authorization.

3. Click Save.

Only configure the Agents you installed.

Example

If you did not install the Backup, do not configure the Backup.

6

Click Review & Deploy to review your changes.

7

Click Confirm & Deploy to deploy your changes.

Otherwise, click Cancel and you can make additional changes.

8

Create MongoDB Roles for LDAP Groups. (Optional)

After enabling LDAP Authorization, you need to create custom MongoDB roles for each LDAP Group you specified for LDAP Authorization.

←   Enable Kerberos Authentication for your Cloud Manager Project Manage MongoDB Users and Roles  →

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