How to set up Microsoft Azure Cosmos DB

💪 Did you know? Atlan currently only supports crawling Microsoft Azure Cosmos DB for MongoDB with the Microsoft Azure Cosmos DB package.

Atlan supports the following authentication methods for fetching metadata from Microsoft Azure Cosmos DB:

  • SCRAM-SHA authentication — this method uses a primary connection string to fetch metadata. This authentication method is supported for both request unit (RU) and vCore cluster-based Microsoft Azure Cosmos DB for MongoDB deployments.
  • Service principal authentication — this method requires a client ID, client secret, tenant ID, resource group, subscription ID, and Cosmos DB account name to fetch metadata. This authentication method is only supported for RU-based Microsoft Azure Cosmos DB for MongoDB deployments.

SCRAM-SHA authentication

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

This authentication method is supported for both request unit (RU) and vCore cluster-based Microsoft Azure Cosmos DB for MongoDB deployments. You will need the primary connection string of your Microsoft Azure Cosmos DB deployment to use SCRAM-SHA authentication for integrating with Atlan

RU-based deployment

To retrieve the primary connection string for RU-based deployments:

  1. Log in to the Azure portal 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 (RU) account.
  4. In the left menu of your account page, under Settings, click the Connection strings tab.
  5. On the Connection strings page, change to the Read-only Keys tab.
  6. Copy the value of the Primary Connection String and store it in a secure location.

vCore-based deployment

To retrieve the primary connection string for vCore cluster-based deployments:

  1. Log in to the Azure portal 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. On the Connection strings page, change to the Read-only Keys tab.
  7. 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.

Service principal authentication

This authentication method is only supported for request Unit (RU)-based Microsoft Azure Cosmos DB for MongoDB deployments. Microsoft Azure Cosmos DB for MongoDB deployment does not support service principal authentication for vCore cluster-based deployments.

Register app with Microsoft Entra ID

🤓 Who can do this? You will need your Microsoft Entra ID administrator to complete these steps — you may not have access yourself.

You will need to register your service principal 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.
  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

🤓 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. 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.
  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 Overview screen of your Azure Cosmos DB for MongoDB (RU) account page, copy the values of the following fields and store them in a secure location:
    • Cosmos DB account name, located at the top of the screen
    • Resource Group
    • Subscription ID
  5. From the left menu of your Azure Cosmos DB for MongoDB (RU) account page, click Access control (IAM).
  6. From the tabs along the top of the Access control (IAM) page, click Add and then click Add role assignment.
  7. 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 — 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 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.

To whitelist the Atlan 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 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 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.

Related articles

Was this article helpful?
0 out of 0 found this helpful