Manage data plane access to Azure Cosmos DB by using keys

Azure Cosmos DB is a highly scalable and globally distributed NoSQL database service offered by Microsoft. It supports multiple data models, including key-value, documents, graph, and columnar. When using Azure Cosmos DB, it is essential to understand how to manage data plane access to ensure the security and integrity of your data. In this article, we will explore how to manage data plane access to Azure Cosmos DB by using keys.

1. Obtain the Key

To access Azure Cosmos DB using keys, you need to obtain either the Primary Key or the Secondary Key. These keys can be found in the Azure portal or retrieved programmatically using the Azure SDK or REST API.

2. Create an Instance of the CosmosClient Class

In your code, create an instance of the CosmosClient class from the Azure Cosmos DB SDK. The CosmosClient class requires the endpoint URI of your Azure Cosmos DB account and the access key.

Here is an example of creating a CosmosClient instance:

csharp
using Microsoft.Azure.Cosmos;

// …

string endpointUri = “your-endpoint-uri”;
string primaryKey = “your-primary-key”;

CosmosClient cosmosClient = new CosmosClient(endpointUri, primaryKey);

Make sure to replace your-endpoint-uri and your-primary-key with your actual endpoint URI and primary key.

3. Access the Database

Once you have created the CosmosClient instance, you can use it to access your Azure Cosmos DB account. You can create, read, update, and delete documents or perform queries on the database.

Here is an example of reading a document from a container:

csharp
string databaseName = “your-database-name”;
string containerName = “your-container-name”;
string documentId = “your-document-id”;

Database database = await cosmosClient.GetDatabase(databaseName);
Container container = database.GetContainer(containerName);

ItemResponse response = await container.ReadItemAsync(documentId, partitionKey);
MyDocument document = response.Resource;

Make sure to replace your-database-name, your-container-name, and your-document-id with the actual names in your Azure Cosmos DB account.

4. Control Access Using Keys

To control access to your Azure Cosmos DB account, you can generate and manage additional keys. This allows you to grant access with specific permissions to different applications or users. For example, you can create a key with read-only access for reporting purposes or a key with read-write access for application development.

To generate a new key, you can use the Azure portal or the Azure Cosmos DB SDK. The SDK provides methods like RegenerateKeyAsync and CreatePermissionAsync to manage keys and permissions programmatically.

Here is an example of generating a secondary key and creating a permission with read-only access:

csharp
string secondaryKey = await cosmosClient.GetDatabaseAccount().RegenerateKeyAsync(ResourceUriFactory.CreateDatabaseUri(databaseName), “Secondary”);

string permissionId = “permission1”;
PermissionProperties permissionProperties = new PermissionProperties(permissionId, PermissionMode.Read);
await container.CreatePermissionAsync(permissionProperties, new[] { “/myPartitionKey” });

This example regenerates the secondary key for the database account and creates a permission with read-only mode. It also specifies /myPartitionKey as the partition key for the permission.

By following these steps, you can manage data plane access to Azure Cosmos DB using keys. Remember to keep your keys secure and rotate them periodically for better security. Additionally, when assigning permissions, define the most restrictive access level required for each application or user to ensure data integrity.

Note: The code examples provided in this article are in C#, but similar functionality is available in other programming languages supported by Azure Cosmos DB SDKs.