> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # Set Up User Authentication and Authorization with LDAP **Note:** Starting with MongoDB 8.0, LDAP (Lightweight Directory Access Protocol) authentication and authorization is deprecated. The feature is available and will continue to operate without changes throughout the lifetime of MongoDB 8. LDAP (Lightweight Directory Access Protocol) will be removed in a future major release. For details, see [LDAP Deprecation.](https://www.mongodb.com/docs/manual/core/LDAP-deprecation/) **Note:** This feature is not available for any of the following deployments: - Free clusters - Flex clusters To learn more, see [Limits.](https://www.mongodb.com/docs/atlas/reference/limitations.md#std-label-limits) Atlas provides the ability to manage user authentication and authorization from all MongoDB clients using your own Lightweight Directory Access Protocol (LDAP (Lightweight Directory Access Protocol)) server over TLS (Transport Layer Security). A single LDAPS (Secure Lightweight Directory Access Protocol) (LDAP (Lightweight Directory Access Protocol) over TLS (Transport Layer Security)) configuration applies to all clusters in a project. If you enable user authorization with LDAP (Lightweight Directory Access Protocol), you can create LDAP (Lightweight Directory Access Protocol) groups on the `admin` database by mapping LDAP (Lightweight Directory Access Protocol) groups to MongoDB roles on your Atlas databases. To use LDAP (Lightweight Directory Access Protocol) groups effectively, [create additional projects](https://www.mongodb.com/docs/atlas/tutorial/manage-projects.md#std-label-manage-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 (Lightweight Directory Access Protocol) group to a role in the Atlas project to provide access to the desired deployment. **Note:** When you enable user authorization and an LDAP (Lightweight Directory Access Protocol) user doesn't belong to any LDAP (Lightweight Directory Access Protocol) 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 (Lightweight Directory Access Protocol) user. If you have multiple departments with their own billing needs, alert settings, and project members, consider creating a new set of [projects](https://www.mongodb.com/docs/atlas/tutorial/manage-projects.md#std-label-manage-projects) or a new [organization](https://www.mongodb.com/docs/atlas/tutorial/manage-organizations.md#std-label-manage-org-access) for each department or business unit. **Note:** An explanation of LDAP (Lightweight Directory Access Protocol) is out of scope for the MongoDB documentation. Please review [RFC 4515](https://tools.ietf.org/html/4515) and [RFC 4516](https://tools.ietf.org/html/4516) or refer to your preferred LDAP (Lightweight Directory Access Protocol) documentation. ## Required Access To manage LDAP (Lightweight Directory Access Protocol) users or groups, you must have [`Organization Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Organization-Owner) or [`Project Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Owner) access to Atlas. ## Prerequisites You must meet the following prerequisites to manage user authentication and authorization using LDAP (Lightweight Directory Access Protocol) in Atlas: - Atlas cluster using MongoDB 7.0 or later. - LDAP (Lightweight Directory Access Protocol) server using TLS (Transport Layer Security) that your Atlas clusters can access over the network using either [VPC](https://www.mongodb.com/docs/atlas/security-vpc-peering.md#std-label-vpc-peering) or VNet peering connection or the cluster nodes' public IP addresses. - LDAP (Lightweight Directory Access Protocol) group memberships embedded as an attribute for each user in the LDAP (Lightweight Directory Access Protocol) entry for user authorization only. ## Recommendation For your LDAPS (Secure Lightweight Directory Access Protocol) service to access Atlas clusters, MongoDB recommends one of two configurations: Using a VPC (Virtual Private Cloud) or VNet: 1. Run your LDAP (Lightweight Directory Access Protocol) server in a VPC (Virtual Private Cloud) or VNet. 2. Establish a peering connection to your Atlas project. 3. Use a public FQDN (fully qualified domain name) that resolves to the private IP address of your LDAP (Lightweight Directory Access Protocol) server. Using your data center: 1. Run your LDAP (Lightweight Directory Access Protocol) server with a public FQDN (fully qualified domain name) that resolves to a public IP address. 2. Configure the LDAP (Lightweight Directory Access Protocol) server to allow inbound access from the Atlas cluster nodes' public IP addresses and the [Atlas Gateway IP addresses](https://www.mongodb.com/docs/atlas/setup-cluster-security.md#std-label-atlas-required-gateway-access). LDAP (Lightweight Directory Access Protocol) traffic can originate from either the data node or the Atlas Gateway, so include both sets of IP addresses in your access list. ## Considerations When you enable LDAP (Lightweight Directory Access Protocol) authentication and authorization, consider the following: ### Limitations You cannot use both LDAP (Lightweight Directory Access Protocol) and SCRAM authentication for the same database user. You cannot use OIDC (OpenID Connect) authentication when LDAP (Lightweight Directory Access Protocol) authorization is enabled. When you enable LDAP (Lightweight Directory Access Protocol) authorization, the LDAP (Lightweight Directory Access Protocol) server handles all authorization decisions, including for any external authentication mechanisms. Therefore, if you try to connect to Atlas by using OIDC (OpenID Connect), the connection fails. You must disable LDAP (Lightweight Directory Access Protocol) authorization in order to use OIDC (OpenID Connect) authentication. ### Conflicts between LDAP Authorization and X.509 Users If you enable LDAP authorization, you can't connect to your clusters with users that authenticate with an Atlas-managed X.509 certificate. After you enable LDAP authorization, you *can* connect to your clusters with users that authenticate with an [self-managed X.509 certificate](https://www.mongodb.com/docs/atlas/security-self-managed-x509.md#std-label-self-managed-x509). 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. ### Usernames Atlas uses the full Distinguished Name (DN) of users in your LDAP (Lightweight Directory Access Protocol) server as the Atlas username. For example, an example LDAP (Lightweight Directory Access Protocol) user named `ralph` has the following username in Atlas: `cn=ralph,cn=Users,dc=aws-atlas-ldap-01,dc=myteam,dc=com` ### Connection String If the administrator enables user authentication or both user authentication and authorization with LDAP (Lightweight Directory Access Protocol), 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`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) authenticates an LDAP (Lightweight Directory Access Protocol) user named `rob`: ```sh mongosh "mongodb+srv://cluster0-tijis.mongodb.net/test?authSource=%24external" \ --authenticationMechanism PLAIN \ --username cn=rob,cn=Users,dc=ldaps-01,dc=myteam,dc=com ``` To copy the connection string: 1. In Atlas, go to the Clusters page for your project. If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar. If it's not already displayed, select your desired project from the Projects menu in the navigation bar. In the sidebar, click Clusters under the Database heading. The [Clusters](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fclusters) page displays. 2. Locate the connection string. Click Connect. 3. Edit the connection string. 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.](https://www.mongodb.com/docs/atlas/troubleshoot-connection.md#std-label-special-pass-characters) ### Using Public IP Addresses 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 (Lightweight Directory Access Protocol) server. If you do this, be aware that [certain activities](https://www.mongodb.com/docs/atlas/reference/faq/networking.md#std-label-atlas-faq-networking) trigger a change in the Atlas cluster's public IP addresses. If you allowed LDAP (Lightweight Directory Access Protocol) server access based on public IP addresses, changes to the Atlas cluster's public IP address prevent LDAP (Lightweight Directory Access Protocol) access. To restore LDAP (Lightweight Directory Access Protocol) access, add the new Atlas cluster public IP addresses to the LDAP (Lightweight Directory Access Protocol) access list. ## Procedures ### Configure Authentication with LDAP ### Atlas CLI **Note:** You can use the same Atlas CLI command to configure LDAP (Lightweight Directory Access Protocol) authentication and LDAP (Lightweight Directory Access Protocol) authorization. To save one LDAP configuration for the project you specify using the Atlas CLI, run the following command: ```sh atlas security ldap save [options] ``` To learn more about the command syntax and parameters, see the Atlas CLI documentation for [atlas security ldap save.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-security-ldap-save/) ### Configure Authorization ### Atlas CLI **Note:** You can use the same Atlas CLI command to configure LDAP (Lightweight Directory Access Protocol) authentication and LDAP (Lightweight Directory Access Protocol) authorization. To save one LDAP configuration for the project you specify using the Atlas CLI, run the following command: ```sh atlas security ldap save [options] ``` To learn more about the command syntax and parameters, see the Atlas CLI documentation for [atlas security ldap save.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-security-ldap-save/) ### Add an LDAP Database User or Group ### Atlas CLI To create a database user for your project using the Atlas CLI, run the following command: ```sh atlas dbusers create [builtInRole]... [options] ``` To learn more about the command syntax and parameters, see the Atlas CLI documentation for [atlas dbusers create.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-dbusers-create/) ### View LDAP Configuration ### Atlas CLI To return the details for one LDAP configuration using the Atlas CLI, run the following command: ```sh atlas security ldap get [options] ``` To learn more about the command syntax and parameters, see the Atlas CLI documentation for [atlas security ldap get.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-security-ldap-get/) ### Disable LDAP Configuration ### Atlas CLI **Note:** You can use the same Atlas CLI command to disable LDAP (Lightweight Directory Access Protocol) authentication settings and LDAP (Lightweight Directory Access Protocol) authorization settings. To delete one LDAP configuration using the Atlas CLI, run the following command: ```sh atlas security ldap delete [options] ``` To learn more about the command syntax and parameters, see the Atlas CLI documentation for [atlas security ldap delete.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-security-ldap-delete/) ## Tutorials for Third-Party LDAP Providers Use the following tutorials to configure Atlas to authenticate and authorize users from third-party LDAP providers: - [Set Up Authentication and Authorization with Entra Domain Services](https://www.mongodb.com/docs/atlas/security-ldaps-azure.md#std-label-security-ldaps-azure) - [Configure User Authentication and Authorization with Okta LDAP Interface](https://www.mongodb.com/docs/atlas/security-ldaps-okta.md#std-label-security-ldaps-okta) - [Configure User Authentication and Authorization with OneLogin VLDAP](https://www.mongodb.com/docs/atlas/security-ldaps-onelogin.md#std-label-security-ldaps-onelogin)