Mobile Monitoring Solutions

Close this search box.

Introduction to Azure Cosmos DB Security

MMS Founder

Article originally posted on Database Journal – Daily Database Management & Administration News and Tutorials. Visit Database Journal – Daily Database Management & Administration News and Tutorials

Deployment of cloud-based technologies introduces a wide range of challenges; however, few of them are scrutinized to the same extent as security. When analyzing security-related challenges, it is important to note that they encompass several distinct but interrelated technologies, including authentication and authorization, network isolation, as well as data integrity and confidentiality. In addition, when dealing with data services, it is also necessary to distinguish between the data plane, facilitating access to the underlying content and the management plane, which allows for delegation of administrative tasks. In this article, we will explore how these concepts apply to the Azure Cosmos DB offering.

The first line of defense when controlling data plane access to Cosmos DB is implemented by leveraging the IP address-based network filtering at the account level. By default, this filtering is disabled, effectively allowing network connectivity from any location. Once you enable it, all inbound traffic is blocked unless you explicitly permit it. When using the Azure portal, there are four configuration options that represent different connection types:

  • Add my current IP – this option provides a convenient method to allow connectivity from the public IP address representing your computer. This can be a computer residing in any location with Internet connectivity, including on-premises datacenters and Azure virtual networks.
  • IP (SINGLE IPV4 OR CIDR RANGE) – this option allows you to specify any Internet-based IP address or an IP address range in the Classless Inter-Domain Routing notation.
  • Exceptions (Allow access to Azure Services) – this is a checkbox (enabled by default) that controls connectivity from Azure PaaS services, such as Azure Stream Analytics, Azure Functions, and Azure App Service that are capable of interacting directly with Cosmos DB.
  • Exceptions (Allow access to Azure portal) – this is a checkbox (enabled by default) that controls connectivity to Cosmos DB directly from the Azure portal via such portal-based data management interfaces as Data Explorer.

If you decide to manage a firewall programmatically (for example, by using Azure PowerShell, Azure CLI, or REST API), then you can accomplish this by modifying the ipRangeFilter property of the object representing a target Cosmos DB account. In such case, you will need to provide specific IP addresses or IP address ranges:

  • Exceptions (Allow access to Azure Services) is represented by the IP address
  • Exceptions (Allow access to Azure portal) – is represented by the IP addresses,,,, for Azure public (the portals for US Gov, as well as Germany and China national clouds are represented by their respective, unique IP addresses).

Following establishing a successful network connection, incoming requests are subject to authentication and authorization. To implement them, Cosmos DB relies on several complementing security mechanisms. The first of them involves the use of account-specific, autogenerated master keys. Each account includes two master keys, which provide full control of its entire content. In addition, each account also includes a pair of read-only keys, which grant the ability to carry out read-only operations (with the exception of reading permissions of account resources). Having two master (and two read-only) keys allows you to regenerate each key independently of the other one in the same pair, facilitating key rotation while at the same time, providing uninterrupted access to users and applications.

The use of master keys should be limited to scenarios that require full privileges to the content of an account. For more granular access, you should use resource tokens. Resource tokens provide user-based permissions to individual account resources, including collections, documents, attachments, stored procedures, triggers, and user-defined functions. They are auto-generated when a database user is granted permissions to a resource and re-generated in response to a request referencing that permission. By default, they are valid for one hour, with the maximum timespan of five hours.

Resource tokens are typically employed in scenarios that implement the valet key pattern (for details, refer to its architectural overview on Microsoft Docs). This pattern involves a middle-tier service that serves as the authentication and authorization broker between a client and a back-end service (which in our case, corresponds to the target Cosmos DB account). The mid-tier service has full access to the account based on the knowledge of one of the two master keys. The mid-tier service is also responsible for authenticating the client (for example, by using Azure Active Directory). Once the client successfully authenticates, the mid-tier service requests a resource token associated with the authenticated user from the Cosmos DB account and relays the token back to the client. At that point, the client can use the token to access Cosmos DB resources directly. This continues until the token expires, resulting in the 401 exception. In response, the client contacts the middle-tier service again, which in turn initiates the request for a new resource token.

The control plane security protection of Cosmos DB leverages Role Based Access Control (RBAC), which is part of the Azure core platform functionality. RBAC involves the use of pre-defined and custom roles that determine the list of actions that a role holder is allowed to carry out. Implementing it requires designating an Azure Active Directory user, group, or service principal that will become the role holder and specifying the scope (a subscription, resource group, or an individual resource, such as a Cosmos DB account) in which the role assignment will take effect. Cosmos DB-specific built-in RBAC roles include only DocumentDB Account Contributor and Cosmos DB Account Reader, but you have the option of creating custom roles if needed (for details regarding this process, refer to Microsoft Docs).

This concludes our introduction to Cosmos DB security. In upcoming articles published on this forum, we will explore user and permission management in more detail.

See all articles by Marcin Policht

Subscribe for MMS Newsletter

By signing up, you will receive updates about our latest information.

  • This field is for validation purposes and should be left unchanged.