## How Atlan connects to Microsoft Azure Cosmos DB for NoSQL

URL: https://docs.atlan.com/apps/connectors/database/microsoft-azure-cosmos-db-for-nosql/concepts/how-atlan-connects-to-microsoft-azure-cosmos-db-for-nosql

> Understand how Atlan securely connects to your Microsoft Azure Cosmos DB for NoSQL accounts to extract metadata.

Atlan connects to your Microsoft Azure Cosmos DB for NoSQL accounts to extract technical metadata while maintaining network security and compliance. Atlan supports two connection methods: direct connectivity from Atlan Cloud, and [Self-Deployed Runtime](https://docs.atlan.com/llms/platform/self-deployed-runtime/llms.txt) running inside your own network.

In both methods, Atlan authenticates with a [Microsoft Entra ID service principal](https://docs.atlan.com/llms/connectors/microsoft-azure-cosmos-db-for-nosql/set-up-microsoft-azure-cosmos-db-for-nosql/llms.txt) and discovers every Cosmos DB for NoSQL account that principal is allowed to see. All traffic to Azure is outbound HTTPS over port 443.

## Connect directly

In direct connectivity, Atlan Cloud reaches your Cosmos DB accounts over the public Azure endpoint.

```mermaid
sequenceDiagram
 participant User as User
 participant Atlan as Atlan SaaS Tenant
 participant Entra as Microsoft Entra ID
 participant Cosmos as Azure Cosmos DB for NoSQL

 User->>Atlan: Configure and schedule crawler workflow
 Atlan->>Entra: Authenticate as service principal 
(tenant ID, client ID, client secret)
 Entra->>Atlan: Return access token
 Atlan->>Cosmos: Discover accounts the service principal can access 
(outbound HTTPS, port 443)
 Atlan->>Cosmos: Run read-only requests for databases, containers, 
 scripts, and sampled items
 Cosmos->>Atlan: Return metadata
 Atlan->>Atlan: Catalog results in Atlan
 User->>Atlan: View assets in Atlan
```

If your accounts restrict public network access to selected networks, you must [allow Atlan's IP range](https://docs.atlan.com/llms/connectors/microsoft-azure-cosmos-db-for-nosql/set-up-microsoft-azure-cosmos-db-for-nosql/llms.txt) before Atlan can connect.

## Connect via self-deployed runtime

If you don't want to open your accounts to Atlan Cloud, a runtime service deployed within your own network acts as a secure bridge. The runtime reaches Azure from inside your network perimeter, and your credentials never leave it.

```mermaid
sequenceDiagram
 participant User as User
 participant Atlan as Atlan SaaS Tenant
 participant Runtime as Self-Deployed Runtime 
 (your network)
 participant SecretStore as Secret Store
 participant Cosmos as Azure Cosmos DB for NoSQL

 User->>Atlan: Configure and schedule crawler workflow 
(non-sensitive connection details)
 Runtime->>Atlan: Poll for job execution request 
(via outbound HTTPS)
 Runtime->>SecretStore: Request service principal credentials
 SecretStore->>Runtime: Return credentials
 Runtime->>Cosmos: Authenticate and run read-only requests 
(outbound HTTPS, port 443)
 Cosmos->>Runtime: Return metadata
 Runtime->>Atlan: Send metadata results 
(via HTTPS)
 Atlan->>Atlan: Catalog results in Atlan
 User->>Atlan: View assets in Atlan
```

- The runtime maintains an outbound HTTPS connection to Atlan Cloud (port 443) and an outbound HTTPS connection to Azure (port 443).
- Because the runtime connects from inside your network, you add the runtime's egress address to your Cosmos DB account network rules rather than Atlan's IP range.

For details on how Self-Deployed Runtime works, see [SDR connectivity](https://docs.atlan.com/llms/catalog/connector-capabilities/sdr-connectivity/llms.txt).

## Security

Atlan extracts structural metadata—accounts, databases, containers, the fields inferred from a sample of items, and the definitions of stored procedures, triggers, and user-defined functions. For example, if you have an `orders` container, Atlan discovers the container and its inferred field schema, but never catalogs the order records themselves.

- **Read-only operations**: Every request Atlan makes is read-only. The connector can't create, modify, or delete accounts, databases, containers, items, or scripts. The Azure role you assign to the service principal controls exactly what the connector can reach.

- **Least-privilege access**: The connector needs only read access to account metadata. See [Set up Microsoft Azure Cosmos DB for NoSQL](https://docs.atlan.com/llms/connectors/microsoft-azure-cosmos-db-for-nosql/set-up-microsoft-azure-cosmos-db-for-nosql/llms.txt) for the role to assign.

- **Credential handling**: In direct connectivity, Atlan stores the service principal credentials encrypted and uses them only to request access tokens from Microsoft Entra ID. In Self-Deployed Runtime, the credentials stay in your own secret store and Atlan Cloud never receives them.

- **Scoped crawls**: Atlan discovers every account the service principal can access. Use the include and exclude filters when you [crawl](https://docs.atlan.com/llms/connectors/microsoft-azure-cosmos-db-for-nosql/crawl-microsoft-azure-cosmos-db-for-nosql/llms.txt) to narrow a crawl to specific accounts and databases, or restrict the service principal's role assignments so it can only see the accounts you intend to catalog.

## See also

* [SDR connectivity](https://docs.atlan.com/llms/catalog/connector-capabilities/sdr-connectivity/llms.txt): How Self-Deployed Runtime connects to data sources.
* [Set up Microsoft Azure Cosmos DB for NoSQL](https://docs.atlan.com/llms/connectors/microsoft-azure-cosmos-db-for-nosql/set-up-microsoft-azure-cosmos-db-for-nosql/llms.txt): Create a service principal and grant it access.
* [Preflight checks for Microsoft Azure Cosmos DB for NoSQL](https://docs.atlan.com/llms/connectors/microsoft-azure-cosmos-db-for-nosql/preflight-checks-for-microsoft-azure-cosmos-db-for-nosql/llms.txt): Validations Atlan runs before a crawl.

---