Encryption scopes enable you to manage encryption at the level of an individual blob or container. You can use encryption scopes to create secure boundaries between data that resides in the same storage account but belongs to different customers. For more information about encryption scopes, see Encryption scopes for Blob storage.
This article shows how to create an encryption scope. It also shows how to specify an encryption scope when you create a blob or container.
Create an encryption scope
You can create an encryption scope that is protected with a Microsoft-managed key or with a customer-managed key that is stored in an Azure Key Vault or in an Azure Key Vault Managed Hardware Security Model (HSM). To create an encryption scope with a customer-managed key, you must first create a key vault or managed HSM and add the key you intend to use for the scope. The key vault or managed HSM must have purge protection enabled. The storage account and key vault can be in different regions.
An encryption scope is automatically enabled when you create it. After you create the encryption scope, you can specify it when you create a blob. You can also specify a default encryption scope when you create a container, which automatically applies to all blobs in the container.
When you configure an encryption scope, you are billed for a minimum of one month (30 days). After the first month, charges for an encryption scope are prorated on an hourly basis. For more information, see Billing for encryption scopes.
To create an encryption scope in the Azure portal, follow these steps:
Navigate to your storage account in the Azure portal.
Under Security + networking select Encryption.
Select the Encryption Scopes tab.
Click the Add button to add a new encryption scope.
In the Create Encryption Scope pane, enter a name for the new scope.
Select the desired type of encryption key support, either Microsoft-managed keys or Customer-managed keys.
If you selected Microsoft-managed keys, click Create to create the encryption scope.
If you selected Customer-managed keys, then select a subscription and specify a key vault and a key to use for this encryption scope. If the desired key vault is in a different region, select Enter key URI and specify the key URI.
If infrastructure encryption is enabled for the storage account, then it will automatically be enabled for the new encryption scope. Otherwise, you can choose whether to enable infrastructure encryption for the encryption scope.
To create an encryption scope with PowerShell, install the Az.Storage PowerShell module, version 3.4.0 or later.
Create an encryption scope protected by Microsoft-managed keys
To create a new encryption scope that is protected by Microsoft-managed keys, call the New-AzStorageEncryptionScope command with the -StorageEncryption parameter.
If infrastructure encryption is enabled for the storage account, then it will automatically be enabled for the new encryption scope. Otherwise, you can choose whether to enable infrastructure encryption for the encryption scope. To create the new scope with infrastructure encryption enabled, include the -RequireInfrastructureEncryption parameter.
Remember to replace the placeholder values in the example with your own values:
Create an encryption scope protected by customer-managed keys
To create a new encryption scope that is protected by customer-managed keys stored in a key vault or managed HSM, first configure customer-managed keys for the storage account. You must assign a managed identity to the storage account and then use the managed identity to configure the access policy for the key vault or managed HSM so that the storage account has permissions to access it.
To configure customer-managed keys for use with an encryption scope, purge protection must be enabled on the key vault or managed HSM. The key vault or managed HSM can be in a different region from the storage account.
Remember to replace the placeholder values in the example with your own values:
$rgName = "<resource-group>"
$accountName = "<storage-account>"
$keyVaultName = "<key-vault>"
$keyUri = "<key-uri>"
$scopeName2 = "customer2scope"
# Assign a system managed identity to the storage account.
$storageAccount = Set-AzStorageAccount -ResourceGroupName $rgName `
-Name $accountName `
-AssignIdentity
# Configure the access policy for the key vault.
Set-AzKeyVaultAccessPolicy `
-VaultName $keyVaultName `
-ObjectId $storageAccount.Identity.PrincipalId `
-PermissionsToKeys wrapkey,unwrapkey,get
Next, call the New-AzStorageEncryptionScope command with the -KeyvaultEncryption parameter, and specify the key URI. Including the key version on the key URI is optional. If you omit the key version, then the encryption scope will automatically use the most recent key version. If you include the key version, then you must update the key version manually to use a different version.
If infrastructure encryption is enabled for the storage account, then it will automatically be enabled for the new encryption scope. Otherwise, you can choose whether to enable infrastructure encryption for the encryption scope. To create the new scope with infrastructure encryption enabled, include the -RequireInfrastructureEncryption parameter.
Remember to replace the placeholder values in the example with your own values:
To create an encryption scope with Azure CLI, first install Azure CLI version 2.20.0 or later.
Create an encryption scope protected by Microsoft-managed keys
To create a new encryption scope that is protected by Microsoft-managed keys, call the az storage account encryption-scope create command, specifying the --key-source parameter as Microsoft.Storage.
If infrastructure encryption is enabled for the storage account, then it will automatically be enabled for the new encryption scope. Otherwise, you can choose whether to enable infrastructure encryption for the encryption scope. To create the new scope with infrastructure encryption enabled, include the --require-infrastructure-encryption parameter and set its value to true.
Remember to replace the placeholder values with your own values:
Create an encryption scope protected by customer-managed keys
To create a new encryption scope that is protected by customer-managed keys in a key vault or managed HSM, first configure customer-managed keys for the storage account. You must assign a managed identity to the storage account and then use the managed identity to configure the access policy for the key vault so that the storage account has permissions to access it. For more information, see Customer-managed keys for Azure Storage encryption.
To configure customer-managed keys for use with an encryption scope, purge protection must be enabled on the key vault or managed HSM. The key vault or managed HSM can be in a different region from the storage account.
Remember to replace the placeholder values in the example with your own values:
az login
az account set --subscription <subscription-id>
az storage account update \
--name <storage-account> \
--resource-group <resource_group> \
--assign-identity
storage_account_principal=$(az storage account show \
--name <storage-account> \
--resource-group <resource-group> \
--query identity.principalId \
--output tsv)
az keyvault set-policy \
--name <key-vault> \
--resource-group <resource_group> \
--object-id $storage_account_principal \
--key-permissions get unwrapKey wrapKey
Next, call the az storage account encryption-scope command with the --key-uri parameter, and specify the key URI. Including the key version on the key URI is optional. If you omit the key version, then the encryption scope will automatically use the most recent key version. If you include the key version, then you must update the key version manually to use a different version.
If infrastructure encryption is enabled for the storage account, then it will automatically be enabled for the new encryption scope. Otherwise, you can choose whether to enable infrastructure encryption for the encryption scope. To create the new scope with infrastructure encryption enabled, include the --require-infrastructure-encryption parameter and set its value to true.
Remember to replace the placeholder values in the example with your own values:
To view the encryption scopes for a storage account in the Azure portal, navigate to the Encryption Scopes setting for the storage account. From this pane, you can enable or disable an encryption scope or change the key for an encryption scope.
To view details for a customer-managed key, including the key URI and version and whether the key version is automatically updated, follow the link in the Key column.
To list the encryption scopes available for a storage account with PowerShell, call the Get-AzStorageEncryptionScope command. Remember to replace the placeholder values in the example with your own values:
To list the encryption scopes available for a storage account with Azure CLI, call the az storage account encryption-scope list command. Remember to replace the placeholder values in the example with your own values:
az storage account encryption-scope list \
--account-name <storage-account> \
--resource-group <resource-group>
Create a container with a default encryption scope
When you create a container, you can specify a default encryption scope. Blobs in that container will use that scope by default.
An individual blob can be created with its own encryption scope, unless the container is configured to require that all blobs use the default scope. For more information, see Encryption scopes for containers and blobs.
To create a container with a default encryption scope in the Azure portal, first create the encryption scope as described in Create an encryption scope. Next, follow these steps to create the container:
Navigate to the list of containers in your storage account, and select the Add button to create a new container.
Expand the Advanced settings in the New Container pane.
In the Encryption scope drop-down, select the default encryption scope for the container.
To require that all blobs in the container use the default encryption scope, select the checkbox to Use this encryption scope for all blobs in the container. If this checkbox is selected, then an individual blob in the container cannot override the default encryption scope.
To create a container with a default encryption scope with PowerShell, call the New-AzStorageContainer command, specifying the scope for the -DefaultEncryptionScope parameter. To force all blobs in a container to use the container's default scope, set the -PreventEncryptionScopeOverride parameter to true.
$containerName1 = "container1"
$ctx = New-AzStorageContext -StorageAccountName $accountName -UseConnectedAccount
# Create a container with a default encryption scope that cannot be overridden.
New-AzStorageContainer -Name $containerName1 `
-Context $ctx `
-DefaultEncryptionScope $scopeName1 `
-PreventEncryptionScopeOverride $true
To create a container with a default encryption scope with Azure CLI, call the az storage container create command, specifying the scope for the --default-encryption-scope parameter. To force all blobs in a container to use the container's default scope, set the --prevent-encryption-scope-override parameter to true.
The following example uses your Azure AD account to authorize the operation to create the container. You can also use the account access key. For more information, see Authorize access to blob or queue data with Azure CLI.
If a client attempts to specify a scope when uploading a blob to a container that has a default encryption scope and the container is configured to prevent blobs from overriding the default scope, then the operation fails with a message indicating that the request is forbidden by the container encryption policy.
Upload a blob with an encryption scope
When you upload a blob, you can specify an encryption scope for that blob, or use the default encryption scope for the container, if one has been specified.
Note
When you upload a new blob with an encryption scope, you cannot change the default access tier for that blob. You also cannot change the access tier for an existing blob that uses an encryption scope. For more information about access tiers, see Hot, Cool, and Archive access tiers for blob data.
To upload a blob with an encryption scope via the Azure portal, first create the encryption scope as described in Create an encryption scope. Next, follow these steps to create the blob:
Navigate to the container to which you want to upload the blob.
Select the Upload button, and locate the blob to upload.
Expand the Advanced settings in the Upload blob pane.
Locate the Encryption scope drop-down section. By default, the blob is created with the default encryption scope for the container, if one has been specified. If the container requires that blobs use the default encryption scope, this section is disabled.
To specify a different scope for the blob that you are uploading, select Choose an existing scope, then select the desired scope from the drop-down.
To upload a blob with an encryption scope via PowerShell, call the Set-AzStorageBlobContent command and provide the encryption scope for the blob.
$containerName2 = "container2"
$localSrcFile = "C:\temp\helloworld.txt"
$ctx = New-AzStorageContext -StorageAccountName $accountName -UseConnectedAccount
# Create a new container with no default scope defined.
New-AzStorageContainer -Name $containerName2 -Context $ctx
# Upload a block upload with an encryption scope specified.
Set-AzStorageBlobContent -Context $ctx `
-Container $containerName2 `
-File $localSrcFile `
-Blob "helloworld.txt" `
-BlobType Block `
-EncryptionScope $scopeName2
To upload a blob with an encryption scope via Azure CLI, call the az storage blob upload command and provide the encryption scope for the blob.
If you are using Azure Cloud Shell, follow the steps described in Upload a blob to create a file in the root directory. You can then upload this file to a blob using the following sample.
To change the key that protects a scope in the Azure portal, follow these steps:
Navigate to the Encryption Scopes tab to view the list of encryption scopes for the storage account.
Select the More button next to the scope you wish to modify.
In the Edit encryption scope pane, you can change the encryption type from Microsoft-managed key to customer-managed key or vice versa.
To select a new customer-managed key, select Use a new key and specify the key vault, key, and key version.
To change the key that protects an encryption scope from a customer-managed key to a Microsoft-managed key with PowerShell, call the Update-AzStorageEncryptionScope command and pass in the -StorageEncryption parameter:
To change the key that protects an encryption scope from a customer-managed key to a Microsoft-managed key with Azure CLI, call the az storage account encryption-scope update command and pass in the --key-source parameter with the value Microsoft.Storage:
Next, call the az storage account encryption-scope update command, pass in the --key-uri parameter, and pass in the --key-source parameter with the value Microsoft.KeyVault:
To disable an encryption scope in the Azure portal, navigate to the Encryption Scopes setting for the storage account, select the desired encryption scope, and select Disable.
To disable an encryption scope with PowerShell, call the Update-AzStorageEncryptionScope command and include the -State parameter with a value of disabled, as shown in the following example. To re-enable an encryption scope, call the same command with the -State parameter set to enabled. Remember to replace the placeholder values in the example with your own values:
To disable an encryption scope with Azure CLI, call the az storage account encryption-scope update command and include the --state parameter with a value of Disabled, as shown in the following example. To re-enable an encryption scope, call the same command with the --state parameter set to Enabled. Remember to replace the placeholder values in the example with your own values:
