Configure customer-managed keys for the FHIR service
By using customer-managed keys (CMK), you can protect and control access to your organization's data with keys that you create and manage. You use Azure Key Vault to create and manage CMK and then use the keys to encrypt the data stored by the FHIR® service.
Customer-managed keys enable you to:
Create your own encryption keys and store them in a key vault, or use the Azure Key Vault API to generate keys.
Maintain full control and responsibility for the key lifecycle, including key rotation.
Prerequisites
Make sure you're familiar with best practices for customer-managed keys.
Verify you're assigned the Azure Contributor RBAC role, which lets you create and modify Azure resources.
Add a key for the FHIR service in Azure Key Vault. For steps, see Add a key in Azure Key Vault. Customer-managed keys must meet these requirements:
The key is versioned.
The key type is RSA.
The key is 2048-bit or 3072-bit.
The key vault is located in the same region as a created resource, but can be in different Azure subscriptions or tenants.
The combined length for the key vault name and key name can't exceed 94 characters.
When using a key vault with a firewall to disable public access, the option to Allow trusted Microsoft services to bypass this firewall must be enabled.
To prevent losing the encryption key for the FHIR service, the key vault or managed HSM must have soft delete and purge protection enabled. These features allow you to recover deleted keys for a certain time (default 90 days) and block permanent deletion until that time is over.
Note
The FHIR service supports attaching one identity type (either a system-assigned or user-assigned identity). Changing the identity type might impact background jobs such as export and import if the identity type is already mapped.
Update the FHIR service with the encryption key
After you add the key, you need to update the FHIR service with the key URL.
In the key vault, select Keys.
Select the key for the FHIR service.
Select the key version.
Copy the Key Identifier. You need the key URL when you update the key by using an ARM template.
You update the key for the FHIR service by using the Azure portal or an ARM template. During the update, you choose whether to use a system-assigned or user-assigned managed identity. For a system-assigned managed identity, make sure to assign the Key Vault Crypto Service Encryption User role. For more information, see Assign Azure roles using the Azure portal.
Update the key by using the Azure portal
In the Azure portal, go to the FHIR service and then select Encryption from the left pane.
Select Customer-managed key for the Encryption type.
Select a key vault and key or enter the Key URI for the key that was created previously.
Select an identity type, either System-assigned or User-assigned, that matches the type of managed identity configured previously.
Select Save to update the FHIR service to use the customer-managed key.
Update the key by using an ARM template
Use the Azure portal to Deploy a custom template and use one of the ARM templates to update the key. For more information, see Create and deploy ARM templates by using the Azure portal.
ARM template for a system-assigned managed identity
{
"$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"workspaceName": {
"type": "String"
},
"fhirServiceName": {
"type": "String"
},
"keyEncryptionKeyUrl": {
"type": "String"
},
"region": {
"defaultValue": "West US 3",
"type": "String"
}
},
"resources": [
{
"type": "Microsoft.HealthcareApis/workspaces/fhirservices",
"apiVersion": "2023-06-01-preview",
"name": "[concat(parameters('workspaceName'), '/', parameters('fhirServiceName'))]",
"location": "[parameters('region')]",
"identity": {
"type": "SystemAssigned"
},
"properties": {
"encryption": {
"customerManagedKeyEncryption": {
"keyEncryptionKeyUrl": "[parameters('keyEncryptionKeyUrl')]"
}
}
}
}
]
}
ARM template for a user-assigned managed identity
{
"$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"workspaceName": {
"type": "String"
},
"fhirServiceName": {
"type": "String"
},
"keyVaultName": {
"type": "String"
},
"keyName": {
"type": "String"
},
"userAssignedIdentityName": {
"type": "String"
},
"roleAssignmentName": {
"type": "String"
},
"region": {
"defaultValue": "West US 3",
"type": "String"
},
"tenantId": {
"type": "String"
}
},
"resources": [
{
"type": "Microsoft.KeyVault/vaults",
"apiVersion": "2022-07-01",
"name": "[parameters('keyVaultName')]",
"location": "[parameters('region')]",
"properties": {
"accessPolicies": [],
"enablePurgeProtection": true,
"enableRbacAuthorization": true,
"enableSoftDelete": true,
"sku": {
"family": "A",
"name": "standard"
},
"tenantId": "[parameters('tenantId')]"
}
},
{
"type": "Microsoft.ManagedIdentity/userAssignedIdentities",
"apiVersion": "2023-01-31",
"name": "[parameters('userAssignedIdentityName')]",
"location": "[parameters('region')]"
},
{
"type": "Microsoft.KeyVault/vaults/keys",
"apiVersion": "2022-07-01",
"name": "[concat(parameters('keyVaultName'), '/', parameters('keyName'))]",
"properties": {
"attributes": {
"enabled": true
},
"curveName": "P-256",
"keyOps": [ "unwrapKey","wrapKey" ],
"keySize": 2048,
"kty": "RSA"
},
"dependsOn": [
"[resourceId('Microsoft.KeyVault/vaults/', parameters('keyVaultName'))]"
]
},
{
"type": "Microsoft.Authorization/roleAssignments",
"apiVersion": "2021-04-01-preview",
"name": "[guid(parameters('roleAssignmentName'))]",
"properties": {
"roleDefinitionId": "[resourceId('Microsoft.Authorization/roleDefinitions', '14b46e9e-c2b7-41b4-b07b-48a6ebf60603')]",
"principalId": "[reference(resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName'))).principalId]"
},
"dependsOn": [
"[resourceId('Microsoft.KeyVault/vaults/keys', parameters('keyVaultName'), parameters('keyName'))]",
"[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName'))]"
]
},
{
"type": "Microsoft.HealthcareApis/workspaces",
"name": "[parameters('workspaceName')]",
"apiVersion": "2022-05-15",
"location": "[parameters('region')]"
},
{
"type": "Microsoft.HealthcareApis/workspaces/fhirservices",
"apiVersion": "2023-06-01-preview",
"name": "[concat(parameters('workspaceName'), '/', parameters('fhirServiceName'))]",
"location": "[parameters('region')]",
"dependsOn": [
"[resourceId('Microsoft.HealthcareApis/workspaces', parameters('workspaceName'))]",
"[resourceId('Microsoft.Authorization/roleAssignments', guid(parameters('roleAssignmentName')))]"
],
"identity": {
"type": "userAssigned",
"userAssignedIdentities": {
"[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities/', parameters('userAssignedIdentityName'))]": {}
}
},
"properties": {
"encryption": {
"customerManagedKeyEncryption": {
"keyEncryptionKeyUrl": "[reference(resourceId('Microsoft.KeyVault/vaults/keys', parameters('keyVaultName'), parameters('keyName'))).keyUriWithVersion]"
}
}
}
}
]
}
When prompted, select the values for the resource group, region, workspace, and FHIR service name.
- If you're using a system-assigned managed identity, enter the Key Identifier you copied from the key vault in the Key Encryption Key Url field.
- If you're using a user-assigned managed identity, enter the values for the key vault name, key name, user assigned identity name, and tenant ID.
Select Review + create to deploy the updates to the key.
Configure a key when you create the FHIR service
If you use a user-assigned managed identity with the FHIR service, you can configure customer-managed keys at the same time you create the FHIR service.
On the Create FHIR service page, enter the FHIR service name.
Choose Next: Security.
On the Security tab, in the Encryption section select Customer-managed key.
Choose Select from key vault or Enter key URI and then enter the key.
Choose Select an identity to use the user-assigned managed identity. On the Select user assigned managed identity page, filter for and then select the managed identity. Choose Add.
On the Security tab, choose Review + create.
- On the Review + create tab, review the summary of the configuration options and the validation success message. Choose Create to deploy the FHIR service with customer-managed keys.
Recover from lost key access
For the FHIR service to operate properly, it must always have access to the key in the key vault. However, there are scenarios where the service could lose access to the key, including:
The key is disabled or deleted from the key vault.
The FHIR service system-assigned managed identity is disabled.
The FHIR service system-assigned managed identity loses access to the key vault.
In any scenario where the FHIR service can't access the key, API requests return with 500 errors and the data is inaccessible until access to the key is restored.
If key access is lost, ensure you updated the key and required resources so they're accessible by the FHIR service.
Resolve common errors
Common errors that cause databases to become inaccessible are usually due to configuration issues. For more information, see Common errors with customer-managed keys.
Note
FHIR® is a registered trademark of HL7 and is used with the permission of HL7.
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for