# MongoDB

![MongoDB_ForestGreen.png](https://assets.relyanceuat.xyz/images/docs/24150418891917/24936173867149.png)
MongoDB is a powerful, document-oriented database that offers high performance, high availability, and easy scalability. It uses a flexible schema design, allowing for the storage of complex data structures in a way that is intuitive for developers to query and manipulate.

This integration guide outlines steps to specifically connect to your instance of MongoDB Atlas, which is a fully-managed cloud database service developed by MongoDB. To integrate Relyance AI with an on-prem version of MongoDB, please reach out to the Relyance AI support team.

The MongoDB integration has two options to connect:

1. [Using Certificate Authorization](#h_01HSCTCYCSW0XD7E7KWCT93K9Y)
2. [Using Credentials (Username and Password)](#h_01HSCTBNHDXXF5TDJVXD3VXDG6)

### Using Certificate Authorization

In order to integrate MongoDB with Relyance AI using certificate authorization, you will need:

1. A MongoDB user with read access to the databases that will be scanned
2. The **hostname** of the cluster that you want to connect to
3. The Relyance AI **Production NAT IP**
4. An **x.509 certificate** downloaded from MongoDB

#### In MongoDB:

1. Login to your MongoDB account with admin privileges.
2. **Allow-list the Relyance Production NAT IP**: The allow-listing of the production IP is needed to ensure secure access to your MongoDB clusters.
    1. Click on **Network Access** in the right side navigation menu under the **Security** section.

    2. Add the Relyance AI NAT IP addresses, by clicking the **+ADD IP ADDRESS** button and adding each IP address from the article [Relyance AI IP Addresses for Allow Lists](/docs/integrations/relyance-ai-ip-addresses-for-allow-lists/) to the **Access List Entry** field and provide a meaningful name (e.g. Relyance Production IP 1) in the **Comment** field.
    3. Repeat the above step for all the IP addresses in the above article.
3. **Create a new user for database access**:
    1. Click on **Database Access** from the left-hand navigation under **Security**.
    2. Click on the **+ADD NEW DATABASE USER** button.
    3. Choose 'Certificate' as the authentication method option
    4. Use an easy to remember name eg: Relyance_Prod_User
    5. Toggle on the 'Download certificate when user is added'
    6. Select an expiration period for the certificate. We recommend a minimum of 6 months
    8. Choose a role for the user:
        1. **Role Option 1: Permissive**
            - You can provide read only access to all databases in the cluster by choosing the built in role: Only read any database
        2. **Role Option 2: Restrictive using Specific Privileges**
            - You can provide database and collection specific read access by using the specific privileges section of the user creation screen
        3. **If using Asset explorer**
            - On sidebar panel go to *Database Access > Add New Database User* and create a user with the following permissions:
                - Built-in Role: **Atlas Admin (recommended to surface ownership information)**
                - Specific Privileges: **readAnyDatabase**, **clusterMonitor**
        4. **Role Option 3: Restrictive using Custom Roles**
            - You can create [Custom Roles](https://www.mongodb.com/docs/atlas/security-add-mongodb-roles/#mongodb-roles) and assign a custom role to the new user
                - Choose the listCollections action or role for this custom role and assign it to specific databases of your choice
    9. Once you have assigned the role and created the user, the certificate file should automatically get downloaded onto your system
4. **Find your hostname:** In order to scan your MongoDB instance, you'll also need to provide your cluster hostname. The host should be the full name (i.e. `<<hostname>>`.mongodb.net).
    1. **From Atlas UI:**
        1. Click on **Database** from the left-hand menu under **DEPLOYMENT**.
        2. Under Database Deployments click on **Connect**.
        3. If prompted with initial connection type, choose **Standard connection**.
        4. Select the **Shell** option.
        5. The connection string displayed on the screen contains the hostname for the cluster. it will be in the form of *`<<hostname>>`.mongodb.net*.
    2. **Alternatively - From the Atlas Shell:**
        1. Download and install [Atlas shell](https://www.mongodb.com/docs/atlas/cli/stable/install-atlas-cli/).
        2. From the terminal run the following command:
```bash
atlas cluster connectionstrings describe <<clustername>> --output json
```
Replace `<<clustername>>` with the cluster name you are connecting to.
3. The output json should have the hostname in the following format:
```json
"standardSrv": "mongodb+srv://<<hostname>>.mongodb.net"
```

![Screenshot](https://assets.relyanceuat.xyz/images/docs/24150418891917/25163753718541.png)

![Screenshot](https://assets.relyanceuat.xyz/images/docs/24150418891917/25163753735565.png)
![Screenshot](https://assets.relyanceuat.xyz/images/docs/24150418891917/24163102968461.png)
![Screenshot](https://assets.relyanceuat.xyz/images/docs/24150418891917/24163055282957.png)
![Screenshot](https://assets.relyanceuat.xyz/images/docs/24150418891917/24163055286925.png)

#### In the Relyance AI application:

![mongodb-1.png](https://assets.relyanceuat.xyz/images/docs/24150418891917/24936014998413.png)
1. Login to your Relyance account.
2. Navigate to the **Settings** Menu in the bottom left-hand side.
3. Select **Integrations**.
4. Search for MongoDB.
5. In the MongoDB integration card, and click it to open its connections.
6. Under **Authentication Method**, choose **Certificate Auth**.
8. Paste the host value in the Host field
9. Use the JSON editor and paste the contents of the downloaded certificate into the text area and hit **OK**.
Paste the certificate value into the JSON dialog even though it's not JSON.
10. Click **Authenticate** to complete the integration
11. At this point, you should be successfully connected to MongoDB

![Screenshot](https://assets.relyanceuat.xyz/images/docs/24150418891917/25163753742989.png)

### Using Credentials (Username and Password)

In order to integrate MongoDB with Relyance AI you will need **Credentials (Username/Password)** of a MongoDB user with read access to the databases that will be scanned, the **hostname** of the cluster that you want to connect to, and the **Relyance AI Production NAT IP**.

#### In MongoDB:

1. Login to your MongoDB account with admin privileges.
2. **Allow-list the Relyance Production NAT IP**: The allow-listing of the production IP is needed to ensure secure access to your MongoDB clusters.
    1. Click on **Network Access** in the right side navigation menu under the **Security** section.

    ![mceclip3.png](https://assets.relyanceuat.xyz/images/docs/24150418891917/24162317625613.png)

    2. Add the Relyance AI NAT IP addresses, by clicking the **+ADD IP ADDRESS** button and adding each IP address from the article [Relyance AI IP Addresses for Allow Lists](/docs/integrations/relyance-ai-ip-addresses-for-allow-lists/) to the **Access List Entry** field and provide a meaningful name (e.g. Relyance Production IP 1) in the **Comment** field.
    3. Repeat the above step for all the IP addresses in the above article.
3. **Create a new user for database access**:
    1. Click on **Database Access** from the left-hand navigation under **Security**.
    2. Click on the **+ADD NEW DATABASE USER** button.
    3. In this dialog, you'll create credentials and choose a role for the user (provide an easy to recall username - e.g. Relyance_Prod_User). In this step you have a couple of options:
        1. **Role Option 1: Permissive**
            - You can provide read only access to all databases in the cluster by choosing the built in role: Only read any database
        2. **Role Option 2: Restrictive using Specific Privileges**
            - You can provide database and collection specific read access by using the specific privileges section of the user creation screen
        3. **Role Option 3: Restrictive using Custom Roles**
            - You can create [Custom Roles](https://www.mongodb.com/docs/atlas/security-add-mongodb-roles/#mongodb-roles) and assign a custom role to the new user
4. **Find your hostname:** In order to scan your MongoDB instance, you'll also need to provide your cluster hostname. The host should be the full name (i.e. `<<hostname>>`.mongodb.net).
    1. **From Atlas UI:**
        1. Click on **Database** from the left-hand menu under **DEPLOYMENT**.
        2. Under Database Deployments click on **Connect**.
        3. Select the **Shell** option.
        4. The connection string displayed on the screen contains the hostname for the cluster. it will be in the form of *`<<hostname>>`.mongodb.net*.
    2. **Alternatively - From the Atlas Shell:**
        1. Download and install [Atlas shell](https://www.mongodb.com/docs/atlas/cli/stable/install-atlas-cli/).
        2. From the terminal run the following command:
```bash
atlas cluster connectionstrings describe <<clustername>> --output json
```
Replace `<<clustername>>` with the cluster name you are connecting to.
3. The output json should have the hostname in the following format:
```json
"standardSrv": "mongodb+srv://<<hostname>>.mongodb.net"
```

![Screenshot](https://assets.relyanceuat.xyz/images/docs/24150418891917/24162333786509.png)

![Screenshot](https://assets.relyanceuat.xyz/images/docs/24150418891917/24162317634317.png)

![Screenshot](https://assets.relyanceuat.xyz/images/docs/24150418891917/24162333797389.png)

#### In the Relyance AI application:

1. Login to your Relyance account.
2. Navigate to the **Settings** Menu in the bottom left-hand side.
3. Select **Integrations**.
4. Search for MongoDB.
5. In the MongoDB integration card, and click it to open its connections.
6. Under **Authentication Method**, choose **Custom**.
8. Paste the **username**, **password**, and **host** into their respective fields.
9. Select the **Enable** *Data Inspection* checkbox if you wish Relyance also toinspect the data.

10. Click **Authenticate**.
11. At this point, you should see the following result on the integrations page:
12. Congratulations, you are now connected to **MongoDB**.

![mongodb-2.png](https://assets.relyanceuat.xyz/images/docs/24150418891917/24936000665741.png)

### Verify the connection is really working

The connection needs four things in MongoDB, and they fail at different points:

| Grant | Used for |
| --- | --- |
| `read` on each database in scope | reading collections to classify them |
| `viewUser`, `viewRole` | inventorying database users and roles |
| Atlas **admin** API key | listing clusters and their configuration (Atlas deployments only) |

1. **A timeout rather than an authentication error** is the Atlas IP access list.
   Add every
   [Relyance egress IP](/docs/integrations/relyance-ai-ip-addresses-for-allow-lists/)
   for your tenant's region — a partial list produces scans that sometimes work,
   which is the hardest version of this to diagnose.
2. **Authenticated but no collections.** `read` granted on `admin` only does not
   cover the databases you want scanned. Grant it per database, or use a role that
   spans them.
3. **Collections listed but no users or roles in the inventory.** That is `viewUser`
   and `viewRole`, which are separate from `read` and easy to omit.
4. **Host format matters.** An Atlas cluster wants the `mongodb+srv://` form; a
   self-managed replica set wants the seed list. The wrong form fails DNS lookup
   before authentication is ever attempted, which surfaces as a connection error
   rather than a credentials one.

<!-- terraform-examples:begin (generated from the integration catalog; do not hand-edit) -->

## Manage this integration with Terraform

Connections for this integration can be managed as code with the [Relyance Terraform provider](https://registry.terraform.io/providers/Relyance/relyance/latest). Non-secret fields go in `auth.params`; secret fields go in `auth.secrets_wo`, which is write-only — never stored in Terraform state. Rotate secrets by bumping `auth.secrets_wo_version`.

### Custom

```hcl
resource "relyance_integration_connection" "mongodb_0" {
  vendor = "mongodb"
  name   = "<your connection name>"

  auth = {
    method = "db-connect"
    params = {
      host = "<host>"
      data_storage_location = "us"
    }
    # Secret fields are write-only: sent to Relyance, never stored in state.
    secrets_wo = {
      pw = var.mongodb_pw
    }
    secrets_wo_version = 1
  }

  scans = { "data-inspection" = { enabled = true } }
}
```

### Certificate authentication

```hcl
resource "relyance_integration_connection" "mongodb_1" {
  vendor = "mongodb"
  name   = "<your connection name>"

  auth = {
    method = "certificate"
    params = {
      certificate = jsonencode({})
      host = "<host>"
      data_storage_location = "us"
    }
  }

  scans = { "data-inspection" = { enabled = true } }
}
```

<!-- terraform-examples:end -->