> For the complete documentation index, see [llms.txt](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/integrations/integrations/aws/aws-documentdb.md).

# AWS DocumentDB

{% hint style="success" %}
When [connecting an AWS account to Veza](/4yItIzMvkpAvMVFAamTf/integrations/integrations/aws.md#1-create-a-veza-aws-connector-policy), the recommended IAM policy includes permissions to discover DocumentDB clusters. To gather database-level metadata (users, roles, and permissions), Veza will need to be able to execute database commands as a local user, as described in this document.
{% endhint %}

## Overview

Amazon DocumentDB is a fully managed document database service designed for MongoDB compatibility. Veza provides three-tier discovery: a top-level DataService entity represents the integration itself, cluster infrastructure metadata is discovered through AWS APIs, and database-level permissions are extracted using the MongoDB wire protocol.

When you enable DocumentDB in your AWS integration, Veza automatically discovers all DocumentDB clusters (both regular and elastic) in your account. If you provide database credentials, Veza connects to each cluster, lists available databases, and creates separate datasources for each one to extract users, roles, and granular permissions.

### Authorization Entities

The DataService and Cluster tiers are always discovered when DocumentDB is enabled. Database-level entities require credentials:

| Discovery Tier        | Entity Types                                                     | Requirements                                      |
| --------------------- | ---------------------------------------------------------------- | ------------------------------------------------- |
| **DataService-level** | DocumentDB DataService                                           | AWS IAM permissions only                          |
| **Cluster-level**     | DocumentDB Cluster                                               | AWS IAM permissions only                          |
| **Database-level**    | <p>DocumentDB Database<br>DocumentDB User<br>DocumentDB Role</p> | AWS IAM permissions + DocumentDB user credentials |

## Prerequisites

Cluster discovery requires an existing [AWS integration](/4yItIzMvkpAvMVFAamTf/integrations/integrations/aws.md) in Veza with at least one successful extraction and appropriate IAM permissions (detailed in [IAM Configuration](#iam-configuration)). This discovers cluster metadata for both regular and elastic DocumentDB clusters.

To enable database-level discovery, you will need network connectivity from Veza to your DocumentDB endpoints.

An [Insight Point](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point.md) configured to allow outbound connections to your DocumentDB clusters through [security group inbound rules](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point.md#ports-and-connectivity) is recommended for production environments.

You will also need admin access to create a DocumentDB user with read-only access as described in [Database User Configuration](#database-user-configuration).

## IAM Configuration

### Recommended: Least-Privilege Custom Policy

Veza recommends creating a custom IAM policy with only the required permissions for DocumentDB cluster discovery:

* `rds:DescribeDBClusters` - DocumentDB regular clusters are built on RDS technology and use RDS APIs
* `docdb-elastic:ListClusters` - Lists all elastic DocumentDB clusters in your account
* `docdb-elastic:GetCluster` - Retrieves detailed metadata for each elastic cluster

These are included in the recommended Veza connector policy, enabling cluster-level discovery as part of the default AWS integration:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DocumentDBClusterDiscovery",
      "Effect": "Allow",
      "Action": [
        "rds:DescribeDBClusters",
        "docdb-elastic:ListClusters",
        "docdb-elastic:GetCluster"
      ],
      "Resource": "*"
    }
  ]
}
```

{% hint style="info" %}
`rds:DescribeDBClusters` is an RDS service API used internally by DocumentDB for standard cluster management. If you use the **Limit Services** option to enable DocumentDB without also enabling RDS, the AWS integration policy must include this permission to discover standard DocumentDB clusters. Elastic clusters are unaffected.
{% endhint %}

AWS provides managed policies that include the necessary permissions, though they grant additional permissions beyond what Veza requires:

* **AmazonDocDBReadOnlyAccess** - Includes `rds:DescribeDBClusters` plus 35+ other RDS permissions
* **AmazonDocDBElasticReadOnlyAccess** - Includes both elastic DocumentDB permissions plus `ec2:CreateTags` and `ec2:DescribeSubnets`

## Database User Configuration

To enable database-level discovery, Veza requires a DocumentDB user with read-only access to database metadata. This requires `listDatabases` and `listCollections` permissions to enumerate databases and collections, `viewUser` to read user definitions, and `viewRole` to inspect role definitions.

The role inherits `readAnyDatabase` for collection-level data access and `clusterMonitor` for cluster metadata.

Connect to your DocumentDB cluster and run the following commands to create a role with these privileges and assign it to a new user:

```javascript
use admin

db.createRole({
  role: "veza-extractor-role",
  privileges: [
    {
      resource: { db: "", collection: "" },
      actions: [
        "listDatabases",
        "listCollections",
        "viewUser",
        "viewRole"
      ]
    }
  ],
  roles: [
    { role: "readAnyDatabase", db: "admin" },
    { role: "clusterMonitor", db: "admin" }
  ]
})

db.createUser({
  user: "veza-extractor-user",
  pwd: passwordPrompt(),  // or cleartext password
  roles: [
    { role: "veza-extractor-role", db: "admin" }
  ]
})
```

{% hint style="info" %}
**Note**: The user and role names (`veza-extractor-user` and `veza-extractor-role`) are examples. You can use any names that comply with your organization's naming conventions.
{% endhint %}

## Veza Configuration

### Enable DocumentDB in Your AWS Integration

1. In Veza, go to the **Integrations** overview
2. Find your existing AWS integration and click to edit it
3. In the integration configuration, enable the **DocumentDB** service
4. **(Optional)** To enable database-level discovery, configure the following fields:
   * **DocumentDB DB User**: The username created in [Database User Configuration](#database-user-configuration) (e.g., `veza-extractor-user`)
   * **DocumentDB DB Password**: The password for the database user
5. Save the integration configuration

The next time Veza connects, DocumentDB clusters are discovered automatically through AWS APIs. If database credentials are configured, Veza connects to each cluster and discovers databases. Each discovered database is displayed as a separate datasource under **Integrations** > *All Data Sources*.

## Notes and Supported Entities

When DocumentDB is enabled in your AWS integration, Veza automatically discovers cluster infrastructure for both regular and elastic clusters in `available` or `ACTIVE` status. If database credentials are configured, Veza connects to each cluster to extract database-level authorization metadata. Each discovered database appears as a separate datasource in Veza.

### DocumentDB Cluster

Represents a DocumentDB cluster infrastructure resource discovered via AWS APIs. Clusters serve as the parent container for databases and provide network connectivity configuration.

| Attribute          | Description                                                             |
| ------------------ | ----------------------------------------------------------------------- |
| `name`             | Cluster name as shown in AWS Console                                    |
| `aws_account_id`   | AWS account ID containing the cluster                                   |
| `aws_account_name` | AWS account name                                                        |
| `region`           | AWS region where cluster is deployed                                    |
| `endpoint`         | Network endpoint for database connections                               |
| `port`             | Connection port (defaults to 27017 for MongoDB compatibility)           |
| `engine`           | DocumentDB engine version (e.g., `docdb-3.6`, `docdb-4.0`, `docdb-5.0`) |
| `is_elastic`       | Boolean indicating whether this is an elastic cluster                   |
| `created_at`       | Cluster creation timestamp                                              |

### DocumentDB Database

Represents an individual database within a DocumentDB cluster. Discovered through MongoDB wire protocol when database credentials are configured. Each database becomes a separate datasource in Veza.

| Attribute    | Description        |
| ------------ | ------------------ |
| `name`       | Database name      |
| `cluster_id` | Parent cluster ARN |

### DocumentDB User

Represents a database user identity with authentication and authorization privileges. Users are scoped to a specific database (the authentication database) but may have permissions across multiple databases through role assignments.

| Attribute                   | Description                                                                                                                                                                                   |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `username`                  | User's login name                                                                                                                                                                             |
| `user_id`                   | Unique identifier (`username@database` composite key)                                                                                                                                         |
| `database_name`             | Authentication database where user is defined                                                                                                                                                 |
| `cluster_id`                | Parent cluster ARN                                                                                                                                                                            |
| `external`                  | Boolean indicating external authentication (e.g., LDAP)                                                                                                                                       |
| `is_active`                 | Always `true` (DocumentDB doesn't track disabled state)                                                                                                                                       |
| `identity_type`             | Set to `human` by default                                                                                                                                                                     |
| `aws_account_id`            | AWS account ID (for external authentication scenarios)                                                                                                                                        |
| `authentication_mechanisms` | The authentication mechanism used by this user. Always `SCRAM-SHA-1(TLS)` (DocumentDB does not expose credential mechanisms via its API, so the value reflects the only supported mechanism.) |

### DocumentDB Role

Represents a role that grants specific privileges on database resources. Roles can be assigned to users and can inherit from other roles. Veza discovers both built-in roles (like `read`, `readWrite`, `dbAdmin`) and custom roles.

| Attribute       | Description                                           |
| --------------- | ----------------------------------------------------- |
| `role_id`       | Role name (e.g., `read`, `dbAdmin`, custom role name) |
| `database_name` | Database where role is defined                        |
| `cluster_id`    | Parent cluster ARN                                    |

### Permissions

DocumentDB uses the MongoDB privilege system with three resource scopes. Veza translates these MongoDB-specific actions into abstract permissions (DataRead, DataWrite, MetadataRead, etc.) for cross-platform analysis:

* **Cluster-level privileges** (56 actions): Administrative operations affecting the entire cluster, such as `listDatabases`, `serverStatus`, `addShard`, `replSetConfigure`
* **Database-level privileges** (25 actions): Database management operations like `createUser`, `dropUser`, `grantRole`, `viewRole`, `createCollection`
* **Collection-level privileges** (21 actions): Data operations like `find` (read), `insert` (create), `update` (modify), `remove` (delete)

For the complete list of supported actions and their abstract privilege mappings, see [MongoDB documentation](https://docs.mongodb.com/manual/reference/privilege-actions/).

### Credential Configuration

Database credentials are optional; the integration will still discover cluster metadata. After configuring credentials, the same username and password apply to all clusters in your AWS account.

The integration currently supports MongoDB native authentication (username and password); AWS IAM database authentication is not supported.

To store DocumentDB credentials in AWS Secrets Manager instead of configuring them directly on the integration, see [Using AWS Secrets Manager for Database Extraction](/4yItIzMvkpAvMVFAamTf/integrations/integrations/aws/secrets-manager-for-databases.md). Use the DocumentDB cluster ARN as the `resource_id`.

### MongoDB Compatibility

DocumentDB implements the MongoDB 3.6, 4.0, or 5.0 wire protocol. Veza connects using a standard MongoDB-compatible client, making database-level discovery functionally identical to standalone MongoDB integration.

### Network Requirements

Database-level discovery requires network connectivity from your Veza Insight Point to DocumentDB cluster endpoints. For production environments, you can deploy an [Insight Point](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point.md) in the same AWS region as your clusters and configure security group inbound rules to allow connections from the Insight Point's IP address. For multi-region deployments, ensure your Insight Point can reach all cluster endpoints or deploy region-specific Insight Points.

### Testing and Security

Before enabling production discovery, test with a non-production cluster to verify connectivity and permissions. Use the least-privilege IAM policy for cluster discovery and create a dedicated read-only DocumentDB user with only the required privileges (`listDatabases`, `find` on `system.users`, `viewRole`).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/integrations/integrations/aws/aws-documentdb.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.