Skip to content

Files

Latest commit

AlexandraKemperMSAlexandraKemperMS
updating author and dates for app config docs
Dec 3, 2020
ee516c8 · Dec 3, 2020

History

History
102 lines (76 loc) · 8.7 KB

concept-customer-managed-keys.md

File metadata and controls

102 lines (76 loc) · 8.7 KB
title description author ms.author ms.date ms.topic ms.service
Use customer-managed keys to encrypt your configuration data
Encrypt your configuration data using customer-managed keys
AlexandraKemperMS
alkemper
07/28/2020
conceptual
azure-app-configuration

Use customer-managed keys to encrypt your App Configuration data

Azure App Configuration encrypts sensitive information at rest. The use of customer-managed keys provides enhanced data protection by allowing you to manage your encryption keys. When managed key encryption is used, all sensitive information in App Configuration is encrypted with a user-provided Azure Key Vault key. This provides the ability to rotate the encryption key on demand. It also provides the ability to revoke Azure App Configuration's access to sensitive information by revoking the App Configuration instance's access to the key.

Overview

Azure App Configuration encrypts sensitive information at rest using a 256-bit AES encryption key provided by Microsoft. Every App Configuration instance has its own encryption key managed by the service and used to encrypt sensitive information. Sensitive information includes the values found in key-value pairs. When customer-managed key capability is enabled, App Configuration uses a managed identity assigned to the App Configuration instance to authenticate with Azure Active Directory. The managed identity then calls Azure Key Vault and wraps the App Configuration instance's encryption key. The wrapped encryption key is then stored and the unwrapped encryption key is cached within App Configuration for one hour. App Configuration refreshes the unwrapped version of the App Configuration instance's encryption key hourly. This ensures availability under normal operating conditions.

Important

If the identity assigned to the App Configuration instance is no longer authorized to unwrap the instance's encryption key, or if the managed key is permanently deleted, then it will no longer be possible to decrypt sensitive information stored in the App Configuration instance. Using Azure Key Vault's soft delete function mitigates the chance of accidentally deleting your encryption key.

When users enable the customer managed key capability on their Azure App Configuration instance, they control the service’s ability to access their sensitive information. The managed key serves as a root encryption key. A user can revoke their App Configuration instance’s access to their managed key by changing their key vault access policy. When this access is revoked, App Configuration will lose the ability to decrypt user data within one hour. At this point, the App Configuration instance will forbid all access attempts. This situation is recoverable by granting the service access to the managed key once again. Within one hour, App Configuration will be able to decrypt user data and operate under normal conditions.

Note

All Azure App Configuration data is stored for up to 24 hours in an isolated backup. This includes the unwrapped encryption key. This data is not immediately available to the service or service team. In the event of an emergency restore, Azure App Configuration will re-revoke itself from the managed key data.

Requirements

The following components are required to successfully enable the customer-managed key capability for Azure App Configuration:

  • Standard tier Azure App Configuration instance
  • Azure Key Vault with soft-delete and purge-protection features enabled
  • An RSA or RSA-HSM key within the Key Vault
    • The key must not be expired, it must be enabled, and it must have both wrap and unwrap capabilities enabled

Once these resources are configured, two steps remain to allow Azure App Configuration to use the Key Vault key:

  1. Assign a managed identity to the Azure App Configuration instance
  2. Grant the identity GET, WRAP, and UNWRAP permissions in the target Key Vault's access policy.

Enable customer-managed key encryption for your Azure App Configuration instance

To begin, you will need a properly configured Azure App Configuration instance. If you do not yet have an App Configuration instance available, follow one of these quickstarts to set one up:

Tip

The Azure Cloud Shell is a free interactive shell that you can use to run the command line instructions in this article. It has common Azure tools preinstalled, including the .NET Core SDK. If you are logged in to your Azure subscription, launch your Azure Cloud Shell from shell.azure.com. You can learn more about Azure Cloud Shell by reading our documentation

Create and configure an Azure Key Vault

  1. Create an Azure Key Vault using the Azure CLI. Note that both vault-name and resource-group-name are user-provided and must be unique. We use contoso-vault and contoso-resource-group in these examples.

    az keyvault create --name contoso-vault --resource-group contoso-resource-group

  2. Enable soft-delete and purge-protection for the Key Vault. Substitute the names of the Key Vault (contoso-vault) and Resource Group (contoso-resource-group) created in step 1.

    az keyvault update --name contoso-vault --resource-group contoso-resource-group --enable-purge-protection --enable-soft-delete

  3. Create a Key Vault key. Provide a unique key-name for this key, and substitute the names of the Key Vault (contoso-vault) created in step 1. Specify whether you prefer RSA or RSA-HSM encryption.

    az keyvault key create --name key-name --kty {RSA or RSA-HSM} --vault-name contoso-vault

    The output from this command shows the key ID ("kid") for the generated key. Make a note of the key ID to use later in this exercise. The key ID has the form: https://{my key vault}.vault.azure.net/keys/{key-name}/{Key version}. The key ID has three important components:

    1. Key Vault URI: `https://{my key vault}.vault.azure.net
    2. Key Vault key name: {Key Name}
    3. Key Vault key version: {Key version}

  4. Create a system assigned managed identity using the Azure CLI, substituting the name of your App Configuration instance and resource group used in the previous steps. The managed identity will be used to access the managed key. We use contoso-app-config to illustrate the name of an App Configuration instance:

    az appconfig identity assign --name contoso-app-config --resource-group contoso-resource-group --identities [system]

    The output of this command includes the principal ID ("principalId") and tenant ID ("tenandId") of the system assigned identity. These IDs will be used to grant the identity access to the managed key.

    {
"principalId": {Principal Id},
"tenantId": {Tenant Id},
"type": "SystemAssigned",
"userAssignedIdentities": null
}

  5. The managed identity of the Azure App Configuration instance needs access to the key to perform key validation, encryption, and decryption. The specific set of actions to which it needs access includes: GET, WRAP, and UNWRAP for keys. Granting the access requires the principal ID of the App Configuration instance's managed identity. This value was obtained in the previous step. It is shown below as contoso-principalId. Grant permission to the managed key using the command line:

    az keyvault set-policy -n contoso-vault --object-id contoso-principalId --key-permissions get wrapKey unwrapKey

  6. Once the Azure App Configuration instance can access the managed key, we can enable the customer-managed key capability in the service using the Azure CLI. Recall the following properties recorded during the key creation steps: key name key vault URI.

    az appconfig update -g contoso-resource-group -n contoso-app-config --encryption-key-name key-name --encryption-key-version key-version --encryption-key-vault key-vault-Uri

Your Azure App Configuration instance is now configured to use a customer-managed key stored in Azure Key Vault.

Next Steps

In this article, you configured your Azure App Configuration instance to use a customer-managed key for encryption. Learn how to integrate your service with Azure Managed Identities.