Skip to main content

Set up Microsoft Azure Cosmos DB for NoSQL

Connect docs via MCP
TL;DR

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:

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.

Register app with Microsoft Entra ID​

Who can do this?

You need your Cloud Application Administrator or 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.
  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.

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​

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

To assign the role:

  1. Log in to the Azure portal.
  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—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.

To add Atlan's IP range:

  1. Log in to the Azure portal.
  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 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 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: