## Set up MongoDB Atlas

URL: https://docs.atlan.com/apps/connectors/database/mongodb/how-tos/set-up-mongodb

> Atlan supports the basic authentication method for fetching metadata from MongoDB. This method uses a username and password to fetch metadata

Atlan supports the basic authentication method for fetching metadata from MongoDB. This method uses a [username and password](#create-database-user-in-mongodb) to fetch metadata.

## Prerequisites

:::warning Who can do this?
 You need your MongoDB [_Organization Owner_ or _Project Owner_](https://www.mongodb.com/docs/atlas/references/user-roles/) to complete these steps - you may not have access yourself.

:::

Before you begin, make sure you have the following [connection details](#retrieve-connection-details) from your MongoDB database deployment:

- Host name of your MongoDB database
- Host name of the SQL (or JDBC) endpoint of your MongoDB database obtained via [Data Federation](https://www.mongodb.com/products/platform/atlas-data-federation)
- Name of the default database
- Name of the authentication database

## Create database user in MongoDB

You need to create a database user in MongoDB to enable Atlan to [crawl MongoDB](https://docs.atlan.com/llms/connectors/mongodb/crawl-mongodb/llms.txt). A database user's access is determined by the role assigned to that user.

You can either:

- Create a database user with a [built-in role](https://www.mongodb.com/docs/atlas/mongodb-users-roles-and-privileges/#std-label-atlas-user-privileges) - provides read-only access to all databases.
- Create a database user with a [custom role](https://www.mongodb.com/docs/atlas/security-add-mongodb-roles/#std-label-mongodb-roles) - provides restricted access to selected databases and requires allowed actions.

### Create database user with built-in role

To [add a database user](https://www.mongodb.com/docs/atlas/security-add-mongodb-users/#add-database-users) with a built-in role for [crawling MongoDB](https://docs.atlan.com/llms/connectors/mongodb/crawl-mongodb/llms.txt):

1. Sign in to your MongoDB database.
2. From the left menu of the _Data Services_ page, under the _Security_ heading, click **Database Access**.
3. In the upper right of the _Database Access_ page, click **Add New Database User**.
4. In the _Add New Database User_ dialog, enter the following details:
 1. For _Authentication Method_, keep the default **Password**.
 2. For _Password Authentication_, there are two text fields:
 1. Enter a username for the new database user in the top text field - for example, `atlan_user`.
 2. Enter a password in the lower text field or click the **Autogenerate Secure Password** button to copy and use an autogenerated password.
 3. To assign database privileges to the new user, for _Database Privileges_, under _Built-in Role_, click the **Add Built-in Role** dropdown to select a [built-in role](https://www.mongodb.com/docs/atlas/security-add-mongodb-users/#std-label-atlas-user-privileges):
 1. From the _Select role_ dropdown, click **Only read any database** to assign read-only access to your MongoDB databases.
 4. (Optional) By default, users can access all the clusters and federated database instances in the project. To restrict access to specific clusters and federated database instances:
 1. Toggle on **Restrict Access to Specific Clusters/Federated Database Instances**.
 2. For _Grant Access To_, check the boxes next to the clusters and federated database instances to which you want to grant access to the new database user.
 5. At the bottom of the dialog, click **Add User** to finish setup.

### Create database user with custom role

If you have a large number of databases, you can programmatically create a custom role in MongoDB using Atlas API instead - refer to [MongoDB documentation](https://www.mongodb.com/docs/atlas/references/api-resources-spec/v2/#operation/createCustomDatabaseRole) to learn more.

To [add a database user](https://www.mongodb.com/docs/atlas/security-add-mongodb-users/#add-database-users) with a custom role for [crawling MongoDB](https://docs.atlan.com/llms/connectors/mongodb/crawl-mongodb/llms.txt):

1. Sign in to your MongoDB database.
2. From the left menu of the _Data Services_ page, under the _Security_ heading, click **Database Access**.
3. In the _Database Access_ page, change to the **Custom Roles** tab.
4. In the upper right of the _Custom Roles_ page, click **Add New Custom Role**.
5. In the _Add Custom Role_ dialog, for _Custom Role Name_, enter a meaningful name - for example, `atlan_integration`.
6. For _Action or Role_, click **Select Actions or Roles** and grant the following privileges to the custom role:
 - **listDatabases**, listed under _Global Actions and Roles_ - to list all existing databases in the cluster.
 - **sqlGetSchema**, listed under _Global Actions and Roles_ - to retrieve collection schema generated by MongoDB Atlas Data Federation without read or find permission on the database or collection.
 - **dbStats**, listed under _Database Actions and Roles_ - to retrieve database statistics such as storage size and collection count. This privilege is required for [preflight checks](https://docs.atlan.com/llms/connectors/mongodb/preflight-checks-for-mongodb-atlas/llms.txt) to pass.
 - For _Database_, specify all the databases you want to crawl in Atlan.
 - **listCollections**, listed under _Database Actions and Roles_ - to list collections in a database.
 - For _Database_, specify all the databases you want to crawl in Atlan.
 - For _Collection_, you can either specify collections within selected databases or leave blank to include all.
 - **collStats**, listed under _Collection Actions_ - to retrieve collection metadata such as average document size, document count, and more.
 - For _Database_, specify all the databases you want to crawl in Atlan.
 - For _Collection_, you can either specify collections within selected databases or leave blank to include all.
 - **find**, listed under _Collection Actions_ - Atlan requires this action for the MongoDB JDBC driver to validate Atlan's connection to the database. Although `find` grants read permission, you can restrict it to a nonexistent collection to prevent actual data access.
 - For _Database_, specify all the databases you want to crawl in Atlan.
 - For _Collection_, you can either specify collections within selected databases, leave blank to include all, or restrict read access by specifying a nonexistent collection such as `na`, `none`, or `-` for a selected database.
7. Click **Add Custom Role** to complete setup.
8. In the _Database Access_ page, change to the **Database Users** tab.
9. In the upper right of the _Database Access_ page, click **Add New Database User**.
10. In the _Add New Database User_ dialog, enter the following details:
 1. For _Authentication Method_, keep the default **Password**.
 2. For _Password Authentication_, there are two text fields:
 1. Enter a username for the new database user in the top text field - for example, `atlan_user`.
 2. Enter a password in the lower text field or click the **Autogenerate Secure Password** button to copy and use an autogenerated password.
 3. To assign database privileges to the new user, for _Database Privileges_, under _Custom Roles_, click the **Add Custom Role** dropdown. From the _Select role_ dropdown, select the custom role you created previously.
 4. (Optional) By default, users can access all the clusters and federated database instances in the project. To restrict access to specific clusters and federated database instances:
 1. Toggle on **Restrict Access to Specific Clusters/Federated Database Instances**.
 2. For _Grant Access To_, check the boxes next to the clusters and federated database instances to which you want to grant access to the new database user.
 5. At the bottom of the dialog, click **Add User** to finish setup.

[Data Federation](https://www.mongodb.com/products/platform/atlas-data-federation) enables a SQL-like interface for Atlan to interact with MongoDB. It also provides schema access to collections that are either generated automatically through sampling or manual updates. This enables Atlan to fetch metadata without read access to databases or collections through the `sqlGetSchema` permission.

## Retrieve connection details

To [retrieve connection details](https://www.mongodb.com/docs/manual/references/connection-string/#std-label-connections-standard-connection-string-format) for [crawling MongoDB](https://docs.atlan.com/llms/connectors/mongodb/crawl-mongodb/llms.txt):

1. Sign in to your MongoDB database.
2. From the left menu of the _Data Services_ page, under the _Overview_ heading, click **Database**.
3. On the _Database Deployment_ page, navigate to the database deployment you want to crawl in Atlan and click **Connect**. From the corresponding page, under _Connect to your application_:
 1. Click **Drivers**, and then navigate to the _Add your connection string into your application code_ section:
 1. Copy the host name of your MongoDB database from the code snippet and store it in a secure location. For example, in `mongodb://myDBReader:D1fficultP%40ssw0rd@mongodb0.example.com:27017/?authSource=admin`, `mongodb0.example.com` is the _MongoDB native host_.
 2. Close the dialog box and return to the _Connect to your application_ page.
 2. Click **Atlas SQL**, and then navigate to the _Select your driver_ heading:
 1. From the driver dropdown, click **JDBC Driver**.
 2. Navigate to the _Get Connection String_ heading, and then for _URL_, copy the following connection details and store them in a secure location. As an example, `jdbc:mongodb://atlas-sql-64c0b504b658f37cd67dc406-xtapf.a.query.mongodb.net/atlan_db?ssl=trueauth&Source=admin`:
 - Copy the host name of the SQL (or JDBC) endpoint of your MongoDB database `atlas-sql-64c0b504b658f37cd67dc406-xtapf.a.query.mongodb.net` to enter as the _SQL interface host name_.
 - Copy the name of the default database `atlan_db` to enter as the _Default database_.
 - Copy the name of the authentication database `admin` to enter as the _Authentication database_.

## Next steps

Now that you've set up the MongoDB Atlas connector and created a database user, you're ready to:

- [Crawl MongoDB Atlas](https://docs.atlan.com/llms/connectors/mongodb/crawl-mongodb/llms.txt): Configure and run metadata extraction from your MongoDB Atlas instance

---