Cosmos DB Authentication

This document provides a comprehensive guide to authenticating with Azure Cosmos DB, ensuring secure access to your data.

Note: Authentication is a critical aspect of securing your Cosmos DB data. Always follow best practices to protect your keys and credentials.

Authentication Methods

Azure Cosmos DB supports several authentication methods to control access to your data. The primary methods include:

1. Key-based Authentication

This is the most common and straightforward method for authenticating with Cosmos DB. You use the account keys (primary or secondary) to authorize requests.

Account Keys

When you create an Azure Cosmos DB account, it is provisioned with a primary and a secondary account key. These keys are like passwords for your database account and grant full access.

Primary Key: Used for read and write operations.
Secondary Key: A backup key that can also be used for read and write operations. It's good practice to rotate these keys periodically for enhanced security.

Using Account Keys

You can retrieve your account keys from the Azure portal under your Cosmos DB account's "Keys" section. These keys are typically included in the connection string used by your application's SDK.

AccountEndpoint=https://mycosmosdbaccount.documents.azure.com:443/;AccountKey=YOUR_PRIMARY_OR_SECONDARY_KEY;

When using Cosmos DB SDKs, you typically provide the endpoint and the account key to initialize the client:

// C# Example
using Microsoft.Azure.Cosmos;

string cosmosDbEndpoint = "https://your-account-name.documents.azure.com:443/";
string cosmosDbKey = "YOUR_COSMOS_DB_ACCOUNT_KEY";

CosmosClient client = new CosmosClient(cosmosDbEndpoint, cosmosDbKey);

Important: Treat your account keys with the same security as your passwords. Do not embed them directly in client-side code or version control. Use secure methods like Azure Key Vault or environment variables.

2. Resource Tokens

Resource tokens provide fine-grained access control to specific resources (like documents) within your Cosmos DB account. They are often used for scenarios where you need to grant temporary, limited access to users without exposing account keys.

Resource tokens are generated by a user with appropriate permissions.
They have a limited lifetime and expire.
They are typically used in conjunction with Azure Cosmos DB's authentication mechanisms.

Resource tokens are generated using the REST API or server-side SDKs. They are useful for scenarios like sharing specific data with web or mobile clients that shouldn't have direct access to the master keys.

3. Azure Active Directory (Azure AD) Authentication

For enhanced security and centralized identity management, Azure Cosmos DB supports Azure AD authentication. This allows you to use Azure AD identities (users, groups, service principals) to access your Cosmos DB resources.

Benefits of Azure AD Authentication:

Centralized Identity Management: Manage access from a single place.
Role-Based Access Control (RBAC): Assign granular permissions using Azure AD roles.
Reduced Key Management: Eliminate the need to manage and rotate account keys for many scenarios.
Improved Security Posture: Leverages Azure AD's robust security features.

Configuring Azure AD Authentication:

To enable Azure AD authentication:

You must have an Azure Cosmos DB account with a resource located in a region that supports Azure AD authentication for data plane operations.
Configure Azure AD authentication for your Cosmos DB account. This involves registering your Cosmos DB resource provider in Azure AD.
Assign appropriate Azure RBAC roles to Azure AD identities (users, groups, service principals) that grant them permissions to access data in your Cosmos DB account. The roles include:
- Cosmos DB Built-in Data Reader
- Cosmos DB Built-in Data Contributor
- Cosmos DB Built-in Owner
Applications can then authenticate using Azure AD credentials (e.g., OAuth 2.0 tokens) to access Cosmos DB data.

// C# Example with Azure AD (using Azure.Identity)
using Azure.Identity;
using Microsoft.Azure.Cosmos;

string cosmosDbEndpoint = "https://your-account-name.documents.azure.com:443/";

// Authenticate using DefaultAzureCredential (or other credential types like ManagedIdentityCredential)
TokenCredential credential = new DefaultAzureCredential();

CosmosClient client = new CosmosClient(cosmosDbEndpoint, credential);

Best Practices for Authentication

Securely Store Keys: Never hardcode account keys in application code. Use Azure Key Vault, environment variables, or secure configuration management.
Rotate Keys Regularly: Implement a key rotation strategy to minimize the impact of a compromised key.
Use Least Privilege: Grant only the necessary permissions to users and applications. Use Azure AD RBAC for fine-grained control.
Prefer Azure AD: For new applications or when possible, leverage Azure AD authentication for enhanced security and manageability.
Understand Resource Token Usage: Use resource tokens for scenarios requiring temporary, limited access to specific data.