---
title: "Azure Cosmos DB"
slug: "azure-cosmos-db"
updated: 2025-10-27T14:04:40Z
published: 2025-10-27T14:04:40Z
canonical: "docs.plainid.io/azure-cosmos-db"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plainid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure Cosmos DB

Azure Cosmos DB is a data service delivered as part of the Azure suite. Among other capabilities this service allows exposing REST capability data fetching data using REST requests. As such the PlainID PIP-REST adapter can be leveraged to connect and integrate with Azure Cosmos and can use it as a Data Source. 

To enable this integration PlainID has extended its OAuth capability and created a specific Authentication flow based on the Azure Cosmos specifics. This allows a secure, token-based access that comply with Azure specifications and enables the integration with Azure Cosmos DB as a PIP Data Source.

**The `cosmos-aad` wrapper detailed below handles a compatible flow required by Azure Cosmos including token acquisition and and specific Cosmos request headers.**
For more information refer to the official Microsoft documentation (under OAuth Token support) [Access control in the Azure Cosmos DB SQL API](https://learn.microsoft.com/en-us/rest/api/cosmos-db/access-control-on-cosmosdb-resources).

## Azure RBAC Prerequisites
Before connecting to Cosmos DB, ensure the appropriate Role-Based Access Control (RBAC) permissions are configured in your Azure environment:

1. Assign one of the following roles to **both the application and the target user** at the Cosmos DB **account level**:
    
    - **Cosmos DB Built-in Data Contributor**
    - **Cosmos DB Built-in Data Reader**

For details, refer to the official Microsoft documentation on 
[Azure Cosmos DB RBAC](https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/how-to-grant-data-plane-access?tabs=built-in-definition,csharp&pivots=azure-interface-cli)

## REST Data Source Configuration
Integration with Azure Cosmos DB as a Data Source is done using the PIP REST adapter and should be configured as any REST data source. Refer to [REST Services Source](/docs/rest-services-source) for details on setting up a REST data source, defining endpoints, DDLs, etc.

The Azure Cosmos DB Authentication is based on an OAuth flow, which requires OAuth Authentication setup. Refer to [OAuth2 Authentication Support](/docs/oauth2-authentication-support) for more information. 

### OAuth2 Example Configuration for Cosmos AAD Access Tokens

Set up AAD-based OAuth2 credentials in your `auth-config.xml`:

```xml
<application-policy name="oauth2-azure-pid">
  <authentication>
    <login-module code="com.plainid.pip.auth.oauth.clientcredential.OAuth20ClientCredentialLoginModule" flag="required">
      <module-option name="access-token-uri">
        https://login.microsoftonline.com/<AZURE_TENANT_ID>/oauth2/v2.0/token
      </module-option>
      <module-option name="client-id"><AZURE_APP_CLIENT_ID></module-option>
      <module-option name="client-secret"><AZURE_APP_CLIENT_SECRET></module-option>
      <module-option name="scope">https://cosmos.azure.com/.default</module-option>
    </login-module>
  </authentication>
</application-policy>
```

### Translator Properties for Cosmos Integration
To begin, define the OAuth setup using the regular REST translator properties used for referencing the OAuth setup: 
```properties
authConf = /app/conf/auth-config.xml
securityDomain = oauth2-azure-pid
```

In addition use the following Cosmos-specific property that ensures AAD Token use for Cosmos: 
```properties
restWrapper = cosmos-aad
```
This property handles the specific Cosmos Token flow as detailed in [Microsoft's documentation](https://learn.microsoft.com/en-us/rest/api/cosmos-db/access-control-on-cosmosdb-resources) in addition to injecting required Cosmos headers.

Lastly, based on your Cosmos integration, use the `Headers` property to inject this Cosmos-specific header as part of the request customization as required to enable cross-partition querying if your Cosmos DB queries requires it: 
```properties
headers = {"x-ms-documentdb-query-enablecrosspartition": ["true"]}
```



Along with the PIP REST capability and proper Azure RBAC roles, correctly configured authentication and translator properties, PlainID’s PIP service can securely access Cosmos DB using AAD tokens. The `cosmos-aad` wrapper simplifies token management and ensures the correct headers are applied for Microsoft’s Cosmos DB API.