access-key-vault-managed-identity.md

title	description	author	ms.author	ms.service	ms.devlang	ms.topic	ms.date	ms.reviewer
Use a managed identity to access Azure Key Vault from Azure Cosmos DB	Use managed identity in Azure Cosmos DB to access Azure Key Vault.	seesharprun	sidandrews	cosmos-db	csharp	how-to	06/01/2022	thweiss

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

[!INCLUDEappliesto-all-apis]

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 an account for free.
• An existing Azure Cosmos DB SQL API account. Create an Azure Cosmos DB SQL API 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

1. 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 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.

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

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

2. 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.

1. 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 account, see configure customer-managed keys
• To use Azure Key Vault to manage secrets, see secure credentials.