> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # Configure User Authentication and Authorization with Okta LDAP Interface **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) This guide shows you how to enable Atlas to authenticate and authorize database users (not Atlas users) from [Okta](https://okta.com), a third-party LDAP (Lightweight Directory Access Protocol) provider. You can enable LDAP (Lightweight Directory Access Protocol) authentication only or you can enable both LDAP (Lightweight Directory Access Protocol) authentication and authorization: - If you enable LDAP (Lightweight Directory Access Protocol) authentication only, you add individual users to Atlas and assign database access privileges to each user you add. - If you enable LDAP (Lightweight Directory Access Protocol) authentication and authorization, you add user groups to Atlas and assign database access privileges to each group. Users inherit the database access privileges from the LDAP (Lightweight Directory Access Protocol) group they belong to. Atlas supports: - Authenticating database users from Okta Active Directory synchronization. - Authenticating database users from Okta. - Authorizing database users in Okta groups. ## Limitations - You must deploy `M10` or larger Atlas clusters to enable LDAP (Lightweight Directory Access Protocol) integration. LDAP (Lightweight Directory Access Protocol) integration is an Atlas Enterprise feature. - Atlas does not support authorizing database users in Okta Active Directory synchronization groups. - Atlas does not support single sign-on integration for database users. To learn about single-sign on integration for the Atlas administrative web interface, see [Configure Federated Authentication.](https://www.mongodb.com/docs/atlas/security/federated-authentication.md#std-label-atlas-federated-authentication) ## 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. ## Procedures ### Configure Okta for LDAP Authentication The following procedure configures Okta for authentication with Atlas: 1. Set up the Okta LDAP interface. To learn more about setting up the Okta LDAP (Lightweight Directory Access Protocol) interface, see the [Okta documentation.](https://help.okta.com/en/prod/Content/Topics/Directory/LDAP-interface-main.htm) Note your ``. You must provide it in several places during the configuration process. The instance name is located in the URL you use to sign in to your Okta account: ```sh https://.admin.okta.com ``` 2. Create a bind user. [Create a new Okta user](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/usgp-add-users.htm) to use as the Atlas bind user. The bind user is an Okta user that you use to query the account and to authenticate database users' credentials when they connect to an Atlas database. **Important:** Don't use your own user account for the bind user. Use the following template to determine the full Distinguished Name (DN) of your bind user: ```sh uid=,dc=,dc=okta,dc=com ``` For example, if your `` is `bind@example.com` and your `` is `mdb-example`, your bind user's DN is: ```sh uid=bind@example.com,ou=users,dc=mdb-example,dc=okta,dc=com ``` 3. Create database users in Okta. If they don't exist already, create users in Okta that you want to grant database access to: Navigate to your Okta People page. Click Add Person. Enter the user's details. Use email addresses for usernames. **Note:** Avoid entering email addresses with plus symbols (`+`). The Atlas LDAP (Lightweight Directory Access Protocol) integration may encounter issues with email addresses containing plus symbols. Click Save. ### Configure Atlas for LDAP Authentication The following procedure enables Atlas to authenticate database users from Okta LDAP (Lightweight Directory Access Protocol): 1. In Atlas, go to the Advanced page for your project. If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar. If it's not already displayed, select your project from the Projects menu in the navigation bar. In the sidebar, click Database & Network Access under the Security heading. In the sidebar, click Advanced. The [Advanced](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fsecurity%2Fadvanced) page displays. 2. Toggle the button next to LDAP Authentication to On. **Note:** You might incur additional costs when you enable this feature. See [Advanced Security.](https://www.mongodb.com/docs/atlas/billing/additional-services.md#std-label-advanced-security) 3. Enter the server details and bind credentials for all of your LDAP servers in the Configure Your LDAP Server panel. You may list multiple servers separated by commas. You cannot use different ports. 4. Add a User to DN Mapping. Add a User to DN mapping similar to the following example to allow clients to provide their email addresses instead of full DNs when they connect to Atlas databases: ```sh [ { "match": "(.+)", "substitution": "uid={0},ou=users,dc=,dc=okta,dc=com" } ] ``` 5. Enter certificates issued from a Certificate Authority (CA) for your LDAP servers, separated by commas, in the CA Root Certificate field. You may provide self-signed certificates. 6. Click Verify and Save. 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. 7. In Atlas, go to the Database & Network Access page for your project. If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar. If it's not already displayed, select your project from the Projects menu in the navigation bar. In the sidebar, click Database & Network Access under the Security heading. The [Database & Network Access](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fsecurity%2Fdatabase) page displays after you complete the preceding steps. 8. Add LDAP (Lightweight Directory Access Protocol) users to Atlas. **Note:** [Skip this step](https://www.mongodb.com/docs/atlas/security-ldaps-okta.md#std-label-configure-okta-authz) if you want to enable LDAP authorization. Add users managed in the Okta LDAP (Lightweight Directory Access Protocol) to Atlas. Click Add New Database User. Click LDAP User. Perform one of the following: If you have not entered a User to DN Mapping, enter the full DN of the LDAP (Lightweight Directory Access Protocol) user. Follow this template: ```sh uid=,ou=users,dc=,dc=okta,dc=com ``` For example, if your `` is `jane@example.com` and your `` is `mdb-example`, your user's DN is: ```sh uid=jane@example.com,ou=users,dc=mdb-example,dc=okta,dc=com ``` If you entered a User to DN Mapping, enter the username or email address that your mapping requires. Select the database access level to grant to the user. Click Add User. ### Configure Okta for LDAP Authorization **Note:** [Skip this section](https://www.mongodb.com/docs/atlas/security-ldaps-onelogin.md#std-label-skip-onelogin-authz) if you don't want to enable LDAP (Lightweight Directory Access Protocol) authorization. The following procedure configures Atlas to authorize users who belong to Okta LDAP (Lightweight Directory Access Protocol) database access groups. **Important:** - You must enable authentication with LDAP (Lightweight Directory Access Protocol) before enabling authorization. - When you enable and configure LDAP (Lightweight Directory Access Protocol) authorization, database users who are only configured for LDAP (Lightweight Directory Access Protocol) authentication will no longer be able to access databases. 1. Create Okta database access groups. Atlas LDAP (Lightweight Directory Access Protocol) authorization uses LDAP (Lightweight Directory Access Protocol) groups to determine if users are authorized to perform database actions. Create separate Okta groups for each level of access that you want to grant to users. For example, you create one group for read access to one database, another for read and write access, and so on. Navigate to your Okta Groups page by clicking Directory, then Groups. Click Add Group. Enter a group name, for example `db-read`. Click Add Group. 2. Add Okta users to database access groups. Assign users to groups based on the level of access each user requires. Click the group you want to add users to. Click Manage People. Add users to the group, and then click Save. 3. Assign privileges to the bind user. The bind user must have `Read Only Administrator` privileges to authorize users against specific Okta groups and to perform LDAP searches. To assign the bind user `Read Only Administrator` privileges: Navigate to your Okta Administrators page by clicking Security, then Administrators. Click Add Administrator. Search for your bind user, then select the Read Only Administrator role. Click Add Administrator. ### Configure Atlas for LDAP Authorization **Note:** [Skip this section](https://www.mongodb.com/docs/atlas/security-ldaps-onelogin.md#std-label-skip-onelogin-authz) if you don't want to enable LDAP (Lightweight Directory Access Protocol) authorization. The following procedure adds the Okta database access groups to Atlas and enables database user authorization in Atlas: 1. In Atlas, go to the Database & Network Access page for your project. If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar. If it's not already displayed, select your project from the Projects menu in the navigation bar. In the sidebar, click Database & Network Access under the Security heading. The [Database & Network Access](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fsecurity%2Fdatabase) page displays after you complete the preceding steps. 2. Add the database access LDAP (Lightweight Directory Access Protocol) groups to Atlas. Add each of the Okta database groups you created to Atlas. Members of groups that you add are authorized to perform database actions granted to the group. Click Add New Database User. 1. Click LDAP Group, and then enter the full DN of the group containing your database users, even if you enabled User to DN Mapping. Follow this template: ```sh cn=,ou=groups,dc=,dc=okta,dc=com ``` For example, if your `` is `db-read` and your `` is `mdb-example`, your bind user's DN is: ```sh cn=db-read,ou=groups,dc=mdb-example,dc=okta,dc=com ``` 1) Select the database access level to grant to users in this group. 2) Click Add User. 3. In Atlas, go to the Advanced page for your project. If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar. If it's not already displayed, select your project from the Projects menu in the navigation bar. In the sidebar, click Database & Network Access under the Security heading. In the sidebar, click Advanced. The [Advanced](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fsecurity%2Fadvanced) page displays. 4. Toggle the button next to LDAP Authorization to On. 5. Verify the server details and bind credentials for your LDAP server are correct in the Configure Your LDAP Server panel. 6. Enter a query template in Query Template. When a user attempts to perform an action, Atlas executes the [LDAP query template](https://www.mongodb.com/docs/manual/reference/configuration-options/#security.ldap.authz.queryTemplate) 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.](https://www.rfc-editor.org/rfc/rfc4515) If you want to identify what group a user is a member of, you can use the following Query Template: ```sh ou=groups,dc=,dc=okta,dc=com?dn?sub?(&(objectClass=groupofUniqueNames)(uniqueMember={USER})) ``` **Note:** Other query templates may also work. Using the default template of `{USER}?memberOf?base` may result in longer search times. 7. Click Verify and Save. 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. ### Connect to your Cluster Using `mongosh` The following procedure verifies that LDAP (Lightweight Directory Access Protocol) authentication (and LDAP (Lightweight Directory Access Protocol) authorization, if enabled) is configured correctly: **Note:** When LDAP (Lightweight Directory Access Protocol) authentication is enabled, database users must override the following parameters in the connection string for their clients: - `authSource` must be `$external` - `authenticationMechanism` must be `PLAIN` 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. Connect to your cluster with the user credentials that you added to Atlas. Use [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) to connect to your cluster. To copy the connection string: Click Connect. Click LDAP, and then click Copy. Paste and edit the string with your User DN and password. **Note:** Connect to your cluster with a user's full DN if User to DN Mapping is not enabled. 3. After connecting to your cluster, run commands to verify the user has the read or write privileges you assigned them. ## Troubleshoot LDAP Connection Issues **Note:** In Okta, the bind user must have `Read Only Administrator` privileges to perform LDAP searches. [Make sure that your bind user has these privileges](#assign-privileges-to-the-bind-user) before running `ldapsearch`. Use `ldapsearch` to determine if the query template you configured Atlas to use returns user DNs the way you expect. The query template may not be returning the correct user DNs if LDAP (Lightweight Directory Access Protocol) authentication works but LDAP (Lightweight Directory Access Protocol) authorization doesn't. Use the following `ldapsearch` template: ```sh ldapsearch -H 'ldaps://.ldap.okta.com' -D "" -w "" -b 'ou=groups,dc=,dc=okta,dc=com' '(&(objectClass=groupofUniqueNames)(uniqueMember=)) ``` For example, if your `bind-user-dn` is `uid=jane@example.com,ou=users,dc=mdb-example,dc=okta,dc=com` and your `` is `mdb-example`, use the following command: ```sh ldapsearch -H 'ldaps://mdb-example.ldap.okta.com' -D "uid=jane@example.com,dc=mdb-example,dc=okta,dc=com" -w "REDACTED" -b 'ou=groups,dc=mdb-example,dc=okta,dc=com' '(&(objectClass=groupofUniqueNames)(uniqueMember=uid=jane@example.com,ou=users,dc=mdb-example,dc=okta,dc=com))' ``` **Note:** Other query templates may also work. Using the default template of `{USER}?memberOf?base` may result in longer search times.