## Set up Microsoft Azure Cosmos DB for NoSQL

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

> Set up a Microsoft Entra ID service principal and grant it read-only access to the Cosmos DB for NoSQL accounts you want to catalog.

Configure authentication for the Microsoft Azure Cosmos DB for NoSQL connector by registering a Microsoft Entra ID service principal and granting it read-only access to the accounts you want to catalog. Atlan authenticates with a service principal using a tenant ID, client ID, and client secret—account keys, connection strings, and resource tokens aren't supported.

## Prerequisites

Before you begin, make sure you have:

- Access to the [Azure portal](https://portal.azure.com/) with a [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) role in Microsoft Entra ID, or access to someone who does
- Microsoft Azure Cosmos DB administrator access on the accounts you want to catalog, or access to someone who does

Grant the service principal access only to the accounts you want Atlan to catalog—Atlan discovers every account the principal can reach. You can narrow a crawl further with include and exclude filters when you [crawl your assets](https://docs.atlan.com/llms/connectors/microsoft-azure-cosmos-db-for-nosql/crawl-microsoft-azure-cosmos-db-for-nosql/llms.txt).

## Register app with Microsoft Entra ID

:::warning Who can do this?
You 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 is required if creating registered applications isn't enabled for the entire organization.
:::

To register your service principal application 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 expires.
 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.

You now have the tenant ID, client ID, and client secret that Atlan needs.

:::note Client secrets expire
Note the expiry date you selected. When the secret expires, crawls fail to authenticate until you create a new secret and update the credentials in Atlan.
:::

## Grant read-only access

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

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), which grants read-only access to your Azure Cosmos DB account data.

To assign the 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 NoSQL account.
4. From the left menu of your 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 grants [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**.
 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 you registered. Click **Next** to proceed to the next step.
 3. In the _Review + assign_ tab, click **Review + assign** to add the role assignment.

Repeat these steps for every Cosmos DB for NoSQL account you want to crawl in Atlan.

## Allow Atlan's IP range

If your accounts restrict public network access, add Atlan's IP range to your account's network rules so Atlan can [crawl your assets](https://docs.atlan.com/llms/connectors/microsoft-azure-cosmos-db-for-nosql/crawl-microsoft-azure-cosmos-db-for-nosql/llms.txt).

To add Atlan's 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 NoSQL account.
4. From the left menu of your account page, click **Networking**.
5. On the _Networking_ page, under _Public network access_, check the following:
 - If **All networks** is enabled, no further action is 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 you receive it, for _IP (Single IPv4 or CIDR range)_, enter Atlan's IP range and click **Save**.

If you plan to crawl through [Self-Deployed Runtime](https://docs.atlan.com/llms/platform/self-deployed-runtime/llms.txt) instead, add the runtime's egress address rather than Atlan's IP range.

## Next steps

Now that you've registered a service principal and granted it access, you're ready to:

- [Crawl Microsoft Azure Cosmos DB for NoSQL](https://docs.atlan.com/llms/connectors/microsoft-azure-cosmos-db-for-nosql/crawl-microsoft-azure-cosmos-db-for-nosql/llms.txt): Configure and run metadata extraction from your accounts.

---