Access Azure Key Vault from Azure Cosmos DB using a managed identity

Article
09/14/2024

APPLIES TO: NoSQL MongoDB Cassandra Gremlin Table

Azure Cosmos DB may need to read secret/key data from Azure Key Vault. For example, your Azure Cosmos DB may require a customer-managed key stored in Azure Key Vault. To do this, Azure Cosmos DB should be configured with a managed identity, and then an Azure Key Vault access policy should grant the managed identity access.

Prerequisites

An Azure account with an active subscription. Create a trial subscription.
An existing Azure Cosmos DB API for NoSQL account. Create an Azure Cosmos DB API for NoSQL account
An existing Azure Key Vault resource. Create a key vault using the Azure CLI
To perform the steps in this article, install the Azure CLI and sign in to Azure.

Prerequisite check

In a terminal or command window, store the names of your Azure Key Vault resource, Azure Cosmos DB account and resource group as shell variables named keyVaultName, cosmosName, and resourceGroupName.
```
# Variable for function app name
keyVaultName="msdocs-keyvault"

# Variable for Azure Cosmos DB account name
cosmosName="msdocs-cosmos-app"

# Variable for resource group name
resourceGroupName="msdocs-cosmos-keyvault-identity"
```
Note

These variables will be re-used in later steps. This example assumes your Azure Cosmos DB account name is msdocs-cosmos-app, your key vault name is msdocs-keyvault and your resource group name is msdocs-cosmos-keyvault-identity.

Create a system-assigned managed identity in Azure Cosmos DB

First, create a system-assigned managed identity for the existing Azure Cosmos DB account.

Important

This how-to guide assumes that you are using a system-assigned managed identity. Many of the steps are similar when using a user-assigned managed identity.

Run az cosmosdb identity assign to create a new system-assigned managed identity.

az cosmosdb identity assign \
    --resource-group $resourceGroupName \
    --name $cosmosName

Retrieve the metadata of the system-assigned managed identity using az cosmosdb identity show, filter to just return the principalId property using the query parameter, and store the result in a shell variable named principal.
```
principal=$(
    az cosmosdb identity show \
        --resource-group $resourceGroupName \
        --name $cosmosName \
        --query principalId \
        --output tsv
)

echo $principal
```
Note

This variable will be re-used in a later step.

Create an Azure Key Vault access policy

In this step, create an access policy in Azure Key Vault using the previously managed identity.

Use the az keyvault set-policy command to create an access policy in Azure Key Vault that gives the Azure Cosmos DB managed identity permission to access Key Vault. Specifically, the policy will use the key-permissions parameters to grant permissions to get, list, and import keys.
```
az keyvault set-policy \
    --name $keyVaultName \
    --object-id $principal \
    --key-permissions get list import
```

Next steps

To use customer-managed keys in Azure Key Vault with your Azure Cosmos DB account, see configure customer-managed keys
To use Azure Key Vault to manage secrets, see secure credentials.