Azure Cosmos DB

Updated
  • Updated on Jun 30, 2025
  • Published on Jun 30, 2025
  • 2 minute(s) read
Prev Next

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.

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

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 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 for more information.

OAuth2 Example Configuration for Cosmos AAD Access Tokens

Set up AAD-based OAuth2 credentials in your auth-config.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:

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:

restWrapper = cosmos-aad

This property handles the specific Cosmos Token flow as detailed in Microsoft's documentation 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:

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.