Configure customer-managed keys at rest

When you create a new Azure API for FHIR® account, your data is encrypted using Microsoft-managed keys by default. Now you can add a second layer of encryption for the data using a key that you choose and manage yourself.

In Azure, this is typically accomplished using an encryption key in the customer's Azure Key Vault. Azure SQL, Azure Storage, and Azure Cosmos DB are some examples that provide this capability. Azure API for FHIR leverages this support from Azure Cosmos DB. When you create an account, you have the option to specify an Azure Key Vault key URI. This key is passed on to Azure Cosmos DB when the DB account is provisioned. When a Fast Healthcare Interoperability Resources (FHIR) request is made, Azure Cosmos DB fetches your key and uses it to encrypt/decrypt the data.

To get started, refer to the following links:

• Register the Azure Cosmos DB resource provider for your Azure subscription
• Configure your Azure Key Vault instance
• Add an access policy to your Azure Key Vault instance
• Generate a key in Azure Key Vault

Using Azure portal

When creating your Azure API for FHIR account on Azure portal, you'll notice a Data Encryption configuration option under the Database Settings on the Additional Settings tab. By default, the service-managed key option is selected.

You can choose your key from the KeyPicker:

You can also specify your Azure Key Vault key here by selecting Customer-managed key option.

You can also enter the key URI as shown in the following.

For existing FHIR accounts, you can view the key encryption choice (Service-managed key or Customer-managed key) in the Database blade as follows. The configuration option can't be modified once it's selected. However, you can modify and update your key.

In addition, you can create a new version of the specified key, after which your data gets encrypted with the new version without any service interruption. You can also remove access to the key to remove access to the data. When the key is disabled, queries will result in an error. If the key is re-enabled, queries will succeed again.

Using Azure PowerShell

With your Azure Key Vault key URI, you can configure CMK using PowerShell by running the following PowerShell command.

New-AzHealthcareApisService
    -Name "myService"
    -Kind "fhir-R4"
    -ResourceGroupName "myResourceGroup"
    -Location "westus2"
    -CosmosKeyVaultKeyUri "https://<my-vault>.vault.azure.net/keys/<my-key>"

Using Azure CLI

As with PowerShell method, you can configure CMK by passing your Azure Key Vault key URI under the key-vault-key-uri parameter and running the following CLI command.

az healthcareapis service create
    --resource-group "myResourceGroup"
    --resource-name "myResourceName"
    --kind "fhir-R4"
    --location "westus2"
    --cosmos-db-configuration key-vault-key-uri="https://<my-vault>.vault.azure.net/keys/<my-key>"

Using Azure Resource Manager Template

With your Azure Key Vault key URI, you can configure CMK by passing it under the keyVaultKeyUri property in the properties object.

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "services_myService_name": {
            "defaultValue": "myService",
            "type": "String"
        }
    },
    "variables": {},
    "resources": [
        {
            "type": "Microsoft.HealthcareApis/services",
            "apiVersion": "2020-03-30",
            "name": "[parameters('services_myService_name')]",
            "location": "westus2",
            "kind": "fhir-R4",
            "properties": {
                "accessPolicies": [],
                "cosmosDbConfiguration": {
                    "offerThroughput": 400,
                    "keyVaultKeyUri": "https://<my-vault>.vault.azure.net/keys/<my-key>"
                },
                "authenticationConfiguration": {
                    "authority": "https://login.microsoftonline.com/72f988bf-86f1-41af-91ab-2d7cd011db47",
                    "audience": "[concat('https://', parameters('services_myService_name'), '.azurehealthcareapis.com')]",
                    "smartProxyEnabled": false
                },
                "corsConfiguration": {
                    "origins": [],
                    "headers": [],
                    "methods": [],
                    "maxAge": 0,
                    "allowCredentials": false
                }
            }
        }
    ]
}

And you can deploy the template with the following PowerShell script.

$resourceGroupName = "myResourceGroup"
$accountName = "mycosmosaccount"
$accountLocation = "West US 2"
$keyVaultKeyUri = "https://<my-vault>.vault.azure.net/keys/<my-key>"

New-AzResourceGroupDeployment `
    -ResourceGroupName $resourceGroupName `
    -TemplateFile "deploy.json" `
    -accountName $accountName `
    -location $accountLocation `
    -keyVaultKeyUri $keyVaultKeyUri

Frequently asked questions

Is the 'cosmosdb_key_vault_key_versionless_id' used in the FHIR API designed to connect to FHIR service managed Cosmos DB?

Yes, when you are enabling customer-managed keys on FHIR APIs, selecting 'cosmosdb_key_vault_key_versionless_id' connects to FHIR service managed Cosmos DB.

Next steps

In this article, you learned how to configure customer-managed keys at rest using the Azure portal, PowerShell, CLI, and Resource Manager Template. You can refer to the Azure Cosmos DB FAQ section for more information.