## Set up Microsoft Azure Cosmos DB

URL: https://docs.atlan.com/apps/connectors/database/microsoft-azure-cosmos-db/how-tos/set-up-microsoft-azure-cosmos-db

> If your Microsoft Azure Cosmos DB deployment includes a mix of vCore- and RU-based accounts, you must configure both to fetch metadata. You can then use the _vCore and RU_ deployment option to [crawl your Microsoft Azure Cosmos DB assets](/apps/connectors/database/microsoft-azure-cosmos-db/how-tos/crawl-microsoft-azure-cosmos-db).

:::info **Did you know?** 
 This connector crawls [Microsoft Azure Cosmos DB for MongoDB](https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/introduction) accounts. To catalog accounts that use the NoSQL API, use the [Microsoft Azure Cosmos DB for NoSQL connector](https://docs.atlan.com/llms/connectors/microsoft-azure-cosmos-db-for-nosql/llms.txt) instead.

:::

Atlan supports the following deployment types for fetching metadata from Microsoft Azure Cosmos DB:

- vCore-based deployment - you can use SCRAM-SHA authentication for vCore-based accounts. You will need to authenticate the connection in Atlan with a primary connection string to fetch metadata from vCore-based accounts. Atlan provides multi-account support for fetching metadata.
- RU-based deployment - you can use service principal authentication for request unit (RU)-based accounts. You will need to authenticate the connection in Atlan with a client ID, client secret, and tenant ID to fetch metadata from RU-based accounts. Atlan provides multi-account support for fetching metadata.

If your Microsoft Azure Cosmos DB deployment includes a mix of vCore- and RU-based accounts, you must configure both to fetch metadata. You can then use the _vCore and RU_ deployment option to [crawl your Microsoft Azure Cosmos DB assets](https://docs.atlan.com/llms/connectors/microsoft-azure-cosmos-db/crawl-microsoft-azure-cosmos-db/llms.txt).

## vCore deployment

:::warning Who can do this?
 You will need your Microsoft Azure Cosmos DB administrator to complete these steps - you may not have access yourself.

:::

For vCore-based accounts, you will need the primary connection string of your Microsoft Azure Cosmos DB deployment to use SCRAM-SHA authentication for [integrating with Atlan](https://docs.atlan.com/llms/connectors/microsoft-azure-cosmos-db/crawl-microsoft-azure-cosmos-db/llms.txt).

To retrieve the primary connection string for vCore-based accounts:

1. Log in to the [Azure portal](https://portal.azure.com/) as an admin.
2. In the portal, search for and select **Azure Cosmos DB**.
3. On the _Azure Cosmos DB_ page, select your Azure Cosmos DB for MongoDB (vCore) account.
4. From the _Overview_ page, copy the value of the _Admin username_. For password, you will need the password that was set up during your Microsoft Azure Cosmos DB deployment.
5. In the left menu of the account page, under _Settings_, click **Connection strings**.
6. Copy the value of the _Primary Connection String_ and store it in a secure location. You will need to add the values of the admin username and password to the placeholder values in the primary connection string you copied. Repeat steps 1 to 6 for all the vCore-based accounts you want to crawl in Atlan.

## RU-based deployment

For request Unit (RU)-based accounts, you will need a client ID, client secret, and tenant ID for service principal authentication. Microsoft Azure Cosmos DB for MongoDB deployment currently does not support service principal authentication for vCore-based accounts.

### Register app with Microsoft Entra ID

:::warning Who can do this?
 You will need your _[Cloud Application Administrator](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#cloud-application-administrator)_ or _[Application Administrator](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#application-administrator)_ to complete these steps  - you may not have access yourself. This will be required if the creation of registered applications is not enabled for the entire organization.

:::

You will need to [register your service principal application](https://learn.microsoft.com/en-us/azure/healthcare-apis/register-application) with Microsoft Entra ID and note down the values of the tenant ID, client ID, and client secret.

To register your app with Microsoft Entra ID:

1. Log in to the [Azure portal](https://portal.azure.com/).
2. In the search bar, search for **Microsoft Entra ID**, and select it from the dropdown list.
3. From the left menu of the _Microsoft Entra ID_ page, click **App registrations**.
4. From the toolbar on the _App registrations_ page, click **\+ New registration**.
5. On the _Register an application_ page, for _Name_, enter a name for your service principal application and then click **Register**.
6. On the homepage of your newly created application, from the _Overview_ screen, copy the values for the following fields and store them in a secure location:
 - **Application (client) ID**
 - **Directory (tenant) ID**
7. From the left menu of your newly created application page, click **Certificates & secrets**.
8. On the _Certificates & secrets_ page, under _Client secrets_, click **\+ New client secret**.
9. In the _Add a client secret_ screen, enter the following details:
 1. For _Description_, enter a description for your client secret.
 2. For _Expiry_, select when the client secret will expire.
 3. Click **Add**.
10. On the _Certificates & secrets_ page, under _Client secrets_, for the newly created client secret, click the clipboard icon to copy the _Value_ and store it in a secure location.

### Set permissions

:::warning Who can do this?
 You will need your Microsoft Azure Cosmos DB administrator to complete these steps - you may not have access yourself.

:::

You will need to add the service principal to the [Cosmos DB Account Reader Role](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#cosmos-db-account-reader-role). This will allow the service principal read-only access to your Azure Cosmos DB account data.

To add the service principal to the _Cosmos DB Account Reader Role_:

1. Log in to the [Azure portal](https://portal.azure.com).
2. Open the menu and search for or select **Azure Cosmos DB**.
3. On the _Azure Cosmos DB_ page, select your Azure Cosmos DB for MongoDB (RU) account.
4. From the left menu of your Azure Cosmos DB for MongoDB (RU) account page, click **Access control (IAM)**.
5. From the tabs along the top of the _Access control (IAM)_ page, click **Add** and then click **Add role assignment**.
6. On the _Add role assignment_ page, configure the following:
 1. In the _Roles_ tab, from the list of roles under _Job function roles_, select **Cosmos DB Account Reader Role**  - this allows [read-only access to Azure Cosmos DB account data](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#cosmos-db-account-reader-role) - and then click **Next**. You will need to assign this role to all the RU-based accounts you want to crawl in Atlan.
 2. In the _Members_ tab, enter the following details:
 1. For _Assign access to_, click **User, group, or service principal**.
 2. For _Members_, click **\+ Select members** and then select the [service principal](https://docs.atlan.com/llms/connectors/microsoft-azure-cosmos-db/set-up-microsoft-azure-cosmos-db/llms.txt) you created. Click **Next** to proceed to the next step.
 3. In the _Review + assign_ tab, click **Review + assign** to add role assignment.

## (Optional) Whitelist Atlan IP range

You may need to whitelist Atlan's IP range to allow Atlan to [crawl Microsoft Azure Cosmos DB](https://docs.atlan.com/llms/connectors/microsoft-azure-cosmos-db/crawl-microsoft-azure-cosmos-db/llms.txt).

To whitelist the Atlan IP range:

1. Log in to the [Azure portal](https://portal.azure.com).
2. Open the menu and search for or select **Azure Cosmos DB**.
3. On the _Azure Cosmos DB_ page, select your Azure Cosmos DB for MongoDB account.
4. From the left menu of your Azure Cosmos DB for MongoDB account page, click **Networking**.
5. On the _Networking_ page, under _Public network access_, check the following:
 - If **All networks** is enabled, no further action required.
 - If **Select networks** is enabled, [raise an Atlan support request](https://docs.atlan.com/support/submit-request) to obtain Atlan's IP range. Once received from Atlan support, for _IP (Single IPv4 or CIDR range)_, enter Atlan's IP range and click the **Save** button.

---