Microsoft Entra ID for Data Plane

Microsoft Entra ID for Data Plane Security in Azure Cosmos DB

Introduction: The Shift to Identity-Based Security

In the early days of cloud computing, developers relied heavily on primary keys and connection strings to secure their databases. While these methods are easy to implement, they introduce significant operational risks. If a connection string is leaked in a source code repository or a configuration file, an attacker gains full administrative access to your database. In a modern, production-grade environment, relying solely on static keys is no longer considered acceptable practice.

Microsoft Entra ID (formerly Azure Active Directory) provides a robust alternative: identity-based access control. By using Entra ID for your Cosmos DB data plane, you transition from "secret-based" security to "identity-based" security. Instead of handing out a master key that grants unrestricted access, you assign specific, time-bound permissions to users, applications, or managed identities. This lesson explores how to implement this pattern, why it is the gold standard for security, and how to manage it effectively in your Azure environment.

The Concept of Data Plane vs. Control Plane

To understand why Entra ID is so critical, we must distinguish between the two layers of Azure Cosmos DB security. The "Control Plane" involves managing the database account itself—creating containers, scaling throughput, or changing firewall rules. The "Data Plane," by contrast, involves the actual read, write, and delete operations performed on the documents within your containers.

Historically, Entra ID was used exclusively for the control plane. You would use a Service Principal to deploy a Cosmos DB account via Terraform or Bicep. However, the data plane—the part your application code touches—was restricted to primary and secondary keys. With the integration of Role-Based Access Control (RBAC) for the data plane, you can now enforce granular policies on your data. This means an application can be restricted to "Read-only" access on a specific container, preventing it from accidentally deleting records or modifying sensitive metadata.

Callout: The Principle of Least Privilege The principle of least privilege is the cornerstone of modern security architecture. It dictates that any entity (user or application) should have only the minimum access necessary to perform its job. Using Entra ID for the data plane allows you to move away from "all-or-nothing" master keys and toward a model where an application's identity is granted exactly the permissions it needs, and nothing more.

Why Use Entra ID Over Primary Keys?

When you use primary keys, you are essentially providing a "master password" to your database. If that key is compromised, rotation is a complex, manual process that often requires downtime or careful coordination across multiple application instances. Entra ID eliminates these headaches through several key mechanisms:

• No Shared Secrets: Your application does not need to store a hardcoded key in an environment variable or a configuration file. Instead, it uses its assigned managed identity to request a token from Microsoft.
• Automatic Token Rotation: Entra ID handles the issuance and expiration of access tokens automatically. Your application code does not need to worry about managing the lifecycle of these credentials.
• Centralized Auditing: Every request made to your database using Entra ID is logged with the identity of the requester. This provides a clear audit trail, allowing you to see exactly who accessed what data and when.
• Fine-Grained Permissions: You can assign roles at the account, database, or container level. This allows for complex security architectures where different microservices have strictly isolated access to different parts of your data.

Step-by-Step Implementation: Configuring Data Plane RBAC

Implementing Entra ID for the data plane requires a few specific configuration steps in the Azure portal or via CLI. Before you begin, ensure you have an existing Cosmos DB account and an application (or a Managed Identity) that needs access.

Step 1: Assigning a Role to an Identity

You must grant your application an Azure role that corresponds to the actions it needs to perform. Azure provides several built-in roles for Cosmos DB:

• Cosmos DB Built-in Data Reader: Allows read-only access to documents.
• Cosmos DB Built-in Data Contributor: Allows read, write, and delete operations on documents.
• Cosmos DB Built-in Data Metadata Reader: Allows listing databases and containers, but not reading the data inside them.

To assign a role using the Azure CLI, you would use the following command:

# Get the object ID of the managed identity
IDENTITY_ID=$(az identity show --name "my-app-identity" --resource-group "my-rg" --query "principalId" -o tsv)

# Assign the Data Contributor role to the identity
az cosmosdb sql role assignment create \
    --account-name "my-cosmos-account" \
    --resource-group "my-rg" \
    --role-definition-id "00000000-0000-0000-0000-000000000002" \
    --principal-id $IDENTITY_ID \
    --scope "/subscriptions/sub-id/resourceGroups/my-rg/providers/Microsoft.DocumentDB/databaseAccounts/my-cosmos-account/dbs/my-db/colls/my-container"

Step 2: Enabling RBAC in the SDK

Once the role is assigned, your application code must be updated to use DefaultAzureCredential instead of a connection string. This credential object is part of the Azure Identity library and automatically attempts to authenticate using the environment's current identity (e.g., Managed Identity in Azure, Environment Variables, or your logged-in VS Code/CLI session).

Here is a C# example using the Microsoft.Azure.Cosmos library:

using Azure.Identity;
using Microsoft.Azure.Cosmos;

// The endpoint of your Cosmos DB account
string endpoint = "https://my-account.documents.azure.com:443/";

// Using DefaultAzureCredential to authenticate
CosmosClient client = new CosmosClient(endpoint, new DefaultAzureCredential());

// Now you can perform operations as usual
Container container = client.GetContainer("my-db", "my-container");
ItemResponse<dynamic> response = await container.ReadItemAsync<dynamic>("item-id", new PartitionKey("partition-key"));

Note: When using DefaultAzureCredential, the SDK automatically handles the acquisition and refreshing of Entra ID tokens. You do not need to manually request an access token or pass it into the client constructor.

Best Practices for Managing Data Plane Security

Security is an ongoing process, not a one-time configuration. To maintain a secure environment, you should adhere to the following industry standards and best practices.

1. Use User-Assigned Managed Identities

While system-assigned managed identities are easy to set up, they are tied to the lifecycle of the Azure resource. If you delete the resource, the identity is lost. User-assigned managed identities are standalone resources, making them easier to manage across multiple services or when performing complex deployments.

2. Avoid "Account-Level" Permissions

It is tempting to assign roles at the account level to save time. However, this violates the principle of least privilege. Always assign roles at the lowest possible scope—ideally at the container level. If a service only needs to read from one container, do not grant it access to the entire database or account.

3. Regularly Audit Role Assignments

Over time, permissions tend to accumulate. Developers may add permissions for testing purposes and forget to remove them. Periodically review your role assignments using the Azure Portal or PowerShell to ensure that no identity has more access than it currently requires.

4. Implement Conditional Access Policies

If you are using Entra ID, you can leverage Conditional Access policies. For example, you can require that requests to your Cosmos DB account originate from specific IP ranges (your corporate network) or that the user has performed multi-factor authentication. This adds an extra layer of defense even if an identity's credentials were to be compromised.

Callout: RBAC vs. Key-based Authentication Key-based authentication is a legacy approach that provides a static, long-lived secret. RBAC with Entra ID is a modern approach that uses dynamic, short-lived tokens. The latter is inherently more secure because it removes the risk of "secret sprawl"—the common issue where secrets are accidentally committed to source control or exposed in logs.

Common Pitfalls and Troubleshooting

Even with a well-planned implementation, you may encounter issues. Understanding these common pitfalls will save you significant debugging time.

The "403 Forbidden" Error

The most common issue when switching to Entra ID is receiving a 403 Forbidden error. This almost always means the identity has not been granted the appropriate role, or the role hasn't propagated throughout the Azure system yet. Remember that role assignments can take several minutes to propagate globally across Azure regions.

SDK Version Compatibility

Ensure you are using a recent version of the Azure Cosmos DB SDK. Older versions of the SDKs do not fully support Entra ID authentication for the data plane. If you are using an SDK version from several years ago, you will need to upgrade to a version that supports TokenCredential.

Local Development Friction

When developing locally, DefaultAzureCredential will look for your logged-in identity from the Azure CLI or Visual Studio. If you haven't logged in, or if you are logged in with the wrong account, your code will fail. Always verify your local authentication state using az account show before running your database code.

Advanced Security: Handling Cross-Tenant Access

In some enterprise scenarios, you may have an application in one Entra ID tenant that needs to access a Cosmos DB account in a different tenant. This is a complex configuration that requires specific "Service Principal" setups.

To achieve this, you must register an application in the source tenant and then create a corresponding "Service Principal" or "Guest User" in the target tenant where the Cosmos DB account resides. You then assign the necessary Cosmos DB role to that identity within the target tenant. This approach is highly secure but adds administrative overhead, so it should only be used when necessary for cross-boundary data access.

Automating Security with Infrastructure as Code (IaC)

Manually configuring RBAC via the portal is prone to error and difficult to track. The professional way to manage data plane security is through Infrastructure as Code (IaC) tools like Bicep or Terraform. By defining your role assignments in code, you ensure that security is part of your deployment pipeline.

Here is an example of how to grant access using Bicep:

resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' existing = {
  name: 'my-cosmos-account'
}

resource roleDefinition 'Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions@2023-04-15' existing = {
  name: '00000000-0000-0000-0000-000000000002' // Data Contributor Role
  parent: cosmosAccount
}

resource roleAssignment 'Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2023-04-15' = {
  name: guid(cosmosAccount.id, principalId, roleDefinition.id)
  parent: cosmosAccount
  properties: {
    roleDefinitionId: roleDefinition.id
    principalId: principalId // The ID of your Managed Identity
    scope: cosmosAccount.id
  }
}

By keeping this in your repository, you treat security as version-controlled code. If you need to audit who has access, you simply look at the Bicep file rather than navigating the Azure portal.

Addressing Common Questions (FAQ)

Q: Can I use both Keys and Entra ID simultaneously?

A: Yes, you can. By default, Cosmos DB allows both. However, for maximum security, you should disable key-based authentication entirely once you have migrated your applications to Entra ID. You can disable key access by setting disableKeyBasedMetadataWriteAccess to true in your account configuration.

Q: Does Entra ID authentication impact performance?

A: There is a negligible performance impact. The SDK caches the token locally and refreshes it before it expires. The latency added by fetching a token from Entra ID is minimal compared to the network latency of a database operation, and it only happens periodically (usually every hour).

Q: What if the Entra ID service is down?

A: Entra ID is a highly available global service. In the extremely rare case that it is unavailable, your application would be unable to get a new token. However, since the SDK caches tokens, your application would likely continue to function until the current token expires.

Q: How do I audit who is using which identity?

A: Use Azure Monitor and Log Analytics. By enabling Data Plane logs for your Cosmos DB account, you can stream all requests to a Log Analytics workspace. You can then run Kusto Query Language (KQL) queries to identify the identity used for each request.

Best Practices Checklist for Security Implementation

To ensure your implementation is successful and secure, follow this checklist before moving to production:

1. Disable Primary Keys: Once your application is fully using Entra ID, disable the use of master keys at the account level to eliminate the "backdoor" risk.
2. Use Managed Identities: Never store Service Principal client secrets in code. Use Azure Managed Identities whenever possible.
3. Scoped Roles: Double-check that your role assignments are at the container level, not the account level.
4. Least Privilege: Review the list of permissions assigned to your applications. Are there any roles that can be downgraded (e.g., from Contributor to Reader)?
5. Monitor Logs: Set up alerts in Azure Monitor for unauthorized access attempts or suspicious activity related to your identity-based access.
6. Version Control: Ensure all role assignments are defined in your infrastructure-as-code files so that security state is reproducible and auditable.
7. Rotate Identities: If you are using service principals, implement a rotation policy for the associated secrets, although managed identities are preferred to avoid this requirement.

Key Takeaways

• Identity over Secrets: Transitioning from primary keys to Entra ID is the most effective way to improve the security posture of your Cosmos DB data plane. It removes the risk of exposed connection strings and provides a centralized, manageable identity system.
• Granular Control: Use RBAC to enforce the principle of least privilege. By assigning roles at the container level, you ensure that applications can only perform the specific operations required for their function.
• Operational Simplicity: Leveraging DefaultAzureCredential simplifies your code and removes the need for manual token management, as the SDK handles authentication and expiration for you.
• Auditability: Entra ID provides a clear audit trail. Because every request is tied to a specific identity, you can easily trace data access back to the originating service or user.
• Automation: Always define your role assignments as part of your Infrastructure as Code (IaC) process. This ensures that security configurations are consistent across environments and documented within your source control.
• Defense in Depth: Combine Entra ID with other Azure security features like Conditional Access, VNet service endpoints, and private links to create a multi-layered security strategy that protects your data from multiple vectors.
• Continuous Improvement: Security is not a one-time setup. Regularly audit your role assignments, monitor logs for unusual activity, and keep your SDKs updated to benefit from the latest security improvements and features.

By moving to an identity-based model, you are aligning your database security with modern industry standards. This shift not only protects your data from accidental exposure but also provides the transparency and control required in high-compliance environments. Start by identifying one non-critical service, implement the transition to Entra ID, and gradually roll out this pattern across your entire architecture to achieve a significantly more secure data platform.