We’re excited to announce new features for the Azure Cosmos DB integrated cache! The integrated cache is built into the dedicated gateway, and now there’s new ways to authenticate your requests. Security is top of mind for many organizations, and you can now use Role-Based Access Control (RBAC) with Microsoft Entra ID to authenticate to the dedicated gateway, eliminating the security risks and complications that come with key-based authentication. Additionally, there’s a new request option that gives you fine grained control over which requests populate the integrated cache.

RBAC authentication with Microsoft Entra ID

One of the most exciting updates is support for RBAC authentication using Microsoft Entra ID. You no longer have to rely on your Azure Cosmos DB account’s primary key for authenticating to the dedicated gateway and integrated cache. Now, you can connect with Entra ID, which improves security and streamlines managing access permissions. Entra ID’s integration allows for more granular control over who can access your data, making it easier to adhere to your organization’s security policies.

The dedicated gateway uses the same permissions, role definitions and role assignments as Azure Cosmos DB. If you already have RBAC configured for data plane operations in your Azure Cosmos DB account, you can also use it for authenticating to the dedicated gateway. The permission model is based on actions that map to database operations (create item, read item etc.), and there are no actions or roles specific to operations that use the dedicated gateway or integrated cache.

How to configure RBAC roles and assignments

Learn how to configure RBAC roles and assignments for the dedicated gateway. If you already have RBAC configured for data plane operations in your Azure Cosmos DB account, you can skip this section and move on to updating your application to use RBAC with the dedicated gateway.

Role definitions contain a list of permissions for allowed user actions. For some cases, the built-in role definitions are sufficient, or you can create your own custom role definitions. The two built-in role definitions are Cosmos DB Built-in Data Reader and Cosmos DB Built-in Data Contributor.

Once you have a role definition, assign it to a user. To assign role permissions, you’ll need the ID of the role definition and the ID of the user account or service principal that will connect to the dedicated gateway. For this example, we’ll use the Cosmos DB Built-in Data Contributor role and a user account.

1. Sign in to the Azure CLI and find or change your current subscription.

az login
az account set --subscription "<subscription ID or name>"

2. Retrieve the details of your account using the az ad user show command. Copy the value of the id property and save it for use in the next step.

az ad user show -–id “<Your email address>”

3. Assign the built-in Cosmos DB Built-in Data Contributor role to your user account using the az cosmosdb sql role assignment create Each built-in role has its own ID, and you can find them in the built-in role definitions chart.

az cosmosdb sql role assignment create \
    --account-name <Your Azure Cosmos DB account name> \
    --resource-group <Your resource group name> \
    --scope "/" \
    --principal-id <Your user id from step 2>  \
    --role-definition-id “00000000-0000-0000-0000-000000000002”

Update your application to use RBAC with the dedicated gateway

Once you’ve created your roles and role assignments, you can use DefaultAzureCredential() from the Azure.Identity package to authenticate your CosmosClient. There are no other application changes required to use RBAC authentication with the dedicated gateway. This example uses the Azure Cosmos DB .NET SDK, however RBAC authentication is supported in all SDKs.

1. Install the Azure.Identity package

dotnet add package Azure.Identity

2. Add the following code at the top of your file where the CosmosClient is created

using Azure.Identity;

3. Modify the code to create your CosmosClient. All dedicated gateway endpoints follow the same pattern <Your Azure Cosmos DB account name>.sqlx.cosmos.azure.com

CosmosClient client = new(
    accountEndpoint: “https://<Your Azure Cosmos DB account name>.sqlx.cosmos.azure.com:443/”, 
    tokenCredential: new DefaultAzureCredential()
);

Fine-grained options for caching requests

Azure Cosmos DB’s dedicated gateway now includes an option to bypass the integrated cache per request. By selectively bypassing the cache, you can ensure that only the most critical and frequently accessed data occupies the limited cache space. This reduces the likelihood of important data being evicted, optimizing the performance for high-priority queries and items. Requests that bypass the cache are still routed through the dedicated gateway and are served from the backend, costing RUs.

Strategic cache management

The ability to bypass the integrated cache empowers you to make strategic decisions about cache usage. All read and write requests from clients configured with the dedicated gateway endpoint populate the cache by default. By directing one-off requests not to use the cache, you free up space for data and queries that are more likely to be repeated. This helps maintain a high cache hit rate and increase RU savings potential. For example, if a query is frequently repeated, but users rarely request the second or third page of data, you can bypass the cache on these trips while keeping the first page in the cache.

How to bypass the integrated cache

The bypass integrated cache request option is available in the Azure Cosmos DB .NET, Java and JavaScript SDKs. The following example shows how to bypass the integrated cache for a query using the .NET SDK.

FeedIterator<MyClass> myQuery = container.GetItemQueryIterator<MyClass>(new QueryDefinition("SELECT * FROM c"), requestOptions: new QueryRequestOptions
        {
            DedicatedGatewayRequestOptions = new DedicatedGatewayRequestOptions 
            { 
                BypassIntegratedCache = true
            }
        }
);

Conclusion

Azure Cosmos DB’s latest updates to the dedicated gateway and integrated cache offer enhanced flexibility and control, making it easier to manage authentication and optimize cache usage. Whether you are seeking to improve security with RBAC authentication via Microsoft Entra ID or aiming to fine-tune your cache strategy with selective bypass options, these features provide powerful tools to help you achieve your goals.

Learn more

• Azure Cosmos DB integrated cache | Microsoft Learn
• Azure Cosmos DB dedicated gateway | Microsoft Learn
• How to configure the Azure Cosmos DB integrated cache | Microsoft Learn
• Use data plane role-based access control – Azure Cosmos DB for NoSQL | Microsoft Learn

Leave a review

Tell us about your Azure Cosmos DB experience! Leave a review on PeerSpot and we’ll gift you $50. Get started here.

About Azure Cosmos DB

Azure Cosmos DB is a fully managed and serverless NoSQL and vector database for modern app development, including AI applications. With its SLA-backed speed and availability as well as instant dynamic scalability, it is ideal for real-time NoSQL and MongoDB applications that require high performance and distributed computing over massive volumes of NoSQL and vector data.

Try Azure Cosmos DB for free here. To stay in the loop on Azure Cosmos DB updates, follow us on X, YouTube, and LinkedIn.