Docs Menu

Set up User Authentication and Authorization with LDAP

On this page

  • Prerequisites
  • Recommendation
  • Considerations
  • Procedures
  • Tutorials for Third-Party LDAP Providers
Note
Feature unavailable in Free and Shared-Tier Clusters

This feature is not available for M0 free clusters, M2, and M5 clusters. To learn more about which features are unavailable, see Atlas M0 (Free Cluster), M2, and M5 Limitations.

Important
Serverless Instances are in Preview

Serverless instances are in preview and do not support this feature at this time. To learn more, see Serverless Instance Limitations.

Atlas provides the ability to manage user authentication and authorization from all MongoDB clients using your own Lightweight Directory Access Protocol (LDAP) server over TLS. A single LDAPS (LDAP over TLS) configuration applies to all clusters in a project.

If you enable user authorization with LDAP, you can create LDAP groups on the admin database by mapping LDAP groups to MongoDB roles on your Atlas databases. To use LDAP groups effectively, create additional projects within Atlas to control access to specific deployments in your organization, such as creating separate Atlas projects for development and production environments. You can then map an LDAP group to a role in the Atlas project to provide access to the desired deployment.

Note

When you enable user authorization and an LDAP user doesn't belong to any LDAP group, Atlas doesn't assign any database roles to the user. When you enable user authentication and you disable user authorization, Atlas assigns MongoDB database roles to the LDAP user.

If you have multiple departments with their own billing needs, alert settings, and project members, consider creating a new set of projects or a new organization for each department or business unit.

Note

An explanation of LDAP is out of scope for the MongoDB documentation. Please review RFC 4515 and RFC 4516 or refer to your preferred LDAP documentation.

You must meet the following prerequisites to manage user authentication and authorization using LDAP in Atlas:

  • Atlas cluster using MongoDB 3.6 or later.
  • LDAP server using TLS that your Atlas clusters can access over the network using either VPC or VNet peering connection or the cluster nodes' public IP addresses.
  • LDAP group memberships embedded as an attribute for each user in the LDAP entry for user authorization only.

For your LDAPS service to access Atlas clusters, MongoDB recommends one of two configurations:

Using a VPC or VNet:

  1. Run your LDAP server in a VPC or VNet.
  2. Establish a peering connection to your Atlas project.
  3. Use a public FQDN that resolves to the private IP address of your LDAP server.

Using your data center:

  1. Run your LDAP server with a public FQDN that resolves to a public IP address.
  2. Configure the LDAP server to allow inbound access from the Atlas cluster nodes' public IP addresses.

If you enable LDAP authorization, you can't connect to your database deployments with users that authenticate with an Atlas-managed X.509 certificate.

After you enable LDAP authorization, you can connect to your database deployments with users that authenticate with an self-managed X.509 certificate. However, the user's Common Name in their X.509 certificate must match the Distinguished Name of a user who is authorized to access your database with LDAP.

Atlas uses the full Distinguished Name (DN) of users in your LDAP server as the Atlas username. For example, an example LDAP user named ralph has the following username in Atlas:

cn=ralph,cn=Users,dc=aws-atlas-ldap-01,dc=myteam,dc=com

If the administrator enables user authentication or both user authentication and authorization with LDAP, database users must override the following parameters in the connection string for their clients.

  • authSource must be $external
  • authenticationMechanism must be PLAIN
Example

The following connection string for mongosh authenticates an LDAP user named rob:

mongosh "mongodb+srv://cluster0-tijis.mongodb.net/test?authSource=%24external" --authenticationMechanism PLAIN --username cn=rob,cn=Users,dc=atlas-ldaps-01,dc=myteam,dc=com

To copy the connection string:

  1. Click Databases in the top-left corner of Atlas.
  2. Click Connect on the Database Deployments page.
  3. Edit the string with your User DN and password.
Note

If your passwords, database names, or connection strings contain reserved URI characters, you must escape the characters. For example, if your password is @bc123, you must escape the @ character when specifying the password in the connection string, such as %40bc123. To learn more, see Special Characters in Connection String Password.

If you change your LDAP configuration, Atlas performs a rolling restart of your cluster. This restart allows Atlas to use the correct settings to authenticate users.

You can use public IP addresses that refer to other internal or private IP addresses using Network Address Translation to allow Atlas traffic to your LDAP server. If you do this, be aware that certain activities trigger a change in the Atlas cluster's public IP addresses.

If you allowed LDAP server access based on public IP addresses, changes to the Atlas cluster's public IP address prevent LDAP access. To restore LDAP access, add the new Atlas cluster public IP addresses to the LDAP access list.

You cannot use both LDAP and SCRAM authentication for the same database user.

Use the following procedure to configure user authentication with LDAP for all clusters in a project.

1
2

Navigate to the Advanced page for your project.

  1. If it is not already displayed, select the organization that contains your desired project from the 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. Click Advanced in the sidebar.
3
Note

You might incur additional costs when you enable this feature. See Advanced Security.

4

You may list multiple servers separated by commas. You cannot use different ports.

5

You may provide self-signed certificates.

6

Wait for Atlas to deploy your changes. Atlas verifies that your clusters can connect to, authenticate with, and query your LDAP servers using the configuration details that you provided.

Use the following procedure to configure user authorization with LDAP for all clusters in a project:

Important
  • You must enable authentication with LDAP before enabling authorization.
  • When you enable and configure LDAP authorization, database users who are only configured for LDAP authentication will no longer be able to access databases.
1
2

Navigate to the Advanced page for your project.

  1. If it is not already displayed, select the organization that contains your desired project from the 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. Click Advanced in the sidebar.
3
4
5

When a user attempts to perform an action, Atlas executes the LDAP query template to obtain the LDAP groups to which the authenticated user belongs. Atlas permits the action if the query returns at least one group that is authorized to perform the action. Atlas does not permit the action if the query returns no groups that are authorized to perform the action.

Atlas substitutes the authenticated username in the {USER} placeholder when it runs the query. The query is relative to the host specified in Server Hostname.

The formatting for the query must conform to RFC4515

If you do not provide a query template, Atlas applies the default value: {USER}?memberOf?base.

6

Wait for Atlas to deploy your changes. Atlas verifies that your clusters can connect to, authenticate with, and query your LDAP server using the configuration details that you provide.

Use the following tutorials to configure Atlas to authenticate and authorize users from third-party LDAP providers:

On this page

Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center

Support

Social

© 2021 MongoDB, Inc.