Create and manage encryption scopes

To create an encryption scope in the Azure portal, follow these steps:

1. Navigate to your storage account in the Azure portal.

2. Under Security + networking select Encryption.

3. Select the Encryption Scopes tab.

4. Click the Add button to add a new encryption scope.

5. In the Create Encryption Scope pane, enter a name for the new scope.

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

7. 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 an 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:

$rgName = "<resource-group>"
$accountName = "<storage-account>"
$scopeName = "<encryption-scope>"

New-AzStorageEncryptionScope -ResourceGroupName $rgName `
    -StorageAccountName $accountName `
    -EncryptionScopeName $scopeName1 `
    -StorageEncryption

Create an encryption scope protected by customer-managed keys in the same tenant

To create an encryption scope that is protected by customer-managed keys stored in a key vault or managed HSM that is in the same tenant as the storage account, first configure customer-managed keys for the storage account. You must assign a managed identity to the storage account that has permissions to access the key vault. The managed identity can be either a user-assigned managed identity or a system-assigned managed identity. To learn more about configuring customer-managed keys, see Configure customer-managed keys in the same tenant for an existing storage account.

To grant the managed identity permissions to access the key vault, assign the Key Vault Crypto Service Encryption User role the managed identity.

To configure customer-managed keys for use with an encryption scope, purge protection must be enabled on the key vault or managed HSM.

The following example shows how to configure an encryption scope with a system-assigned managed identity. Remember to replace the placeholder values in the example with your own values:

$rgName = "<resource-group>"
$accountName = "<storage-account>"
$keyVaultName = "<key-vault>"
$scopeName = "<encryption-scope>"

# Assign a system-assigned managed identity to the storage account.
$storageAccount = Set-AzStorageAccount -ResourceGroupName $rgName `
    -Name $accountName `
    -AssignIdentity

# Assign the necessary permissions to the managed identity 
# so that it can access the key vault.
$principalId = $storageAccount.Identity.PrincipalId
$keyVault = Get-AzKeyVault $keyVaultName

New-AzRoleAssignment -ObjectId $storageAccount.Identity.PrincipalId `
    -RoleDefinitionName "Key Vault Crypto Service Encryption User" `
    -Scope $keyVault.ResourceId

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.

The format of the key URI is similar to the following examples, and can be constructed from the key vault's VaultUri property and the key name:

# Without the key version
https://<key-vault>.vault.azure.net/keys/<key>

# With the key version
https://<key-vault>.vault.azure.net/keys/<key>/<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:

$keyUri = $keyVault.VaultUri + "keys/" + $keyName

New-AzStorageEncryptionScope -ResourceGroupName $rgName `
    -StorageAccountName $accountName `
    -EncryptionScopeName $scopeName `
    -KeyUri $keyUri `
    -KeyvaultEncryption

Create an encryption scope protected by customer-managed keys in a different tenant

To create an encryption scope that is protected by customer-managed keys stored in a key vault or managed HSM that is in a different tenant than the storage account, first configure customer-managed keys for the storage account. You must configure a user-assigned managed identity for the storage account that has permissions to access the key vault in the other tenant. To learn more about configuring cross-tenant customer-managed keys, see Configure cross-tenant customer-managed keys for an existing storage account.

To configure customer-managed keys for use with an encryption scope, purge protection must be enabled on the key vault or managed HSM.

After you have configured cross-tenant customer-managed keys for the storage account, you can create an encryption scope on the storage account in one tenant that is scoped to a key in a key vault in the other tenant. You will need the key URI to create the cross-tenant encryption scope.

Remember to replace the placeholder values in the example with your own values:

$rgName = "<resource-group>"
$accountName = "<storage-account>"
$scopeName = "<encryption-scope>"

# Construct the key URI from the key vault URI and key name.
$keyUri = $kvUri + "keys/" + $keyName

New-AzStorageEncryptionScope -ResourceGroupName $rgName `
    -StorageAccountName $accountName `
    -EncryptionScopeName $scopeName `
    -KeyUri $keyUri `
    -KeyvaultEncryption

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 an 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:

az storage account encryption-scope create \
    --resource-group <resource-group> \
    --account-name <storage-account> \
    --name <encryption-scope> \
    --key-source Microsoft.Storage

Create an encryption scope protected by customer-managed keys in the same tenant

To create an encryption scope that is protected by customer-managed keys stored in a key vault or managed HSM that is in the same tenant as the storage account, first configure customer-managed keys for the storage account. You must assign a managed identity to the storage account that has permissions to access the key vault. The managed identity can be either a user-assigned managed identity or a system-assigned managed identity. To learn more about configuring customer-managed keys, see Configure customer-managed keys in the same tenant for an existing storage account.

To grant the managed identity permissions to access the key vault, assign the Key Vault Crypto Service Encryption User role the managed identity.

To configure customer-managed keys for use with an encryption scope, purge protection must be enabled on the key vault or managed HSM.

The following example shows how to configure an encryption scope with a system-assigned managed identity. Remember to replace the placeholder values in the example with your own values:

az storage account update \
    --name <storage-account> \
    --resource-group <resource_group> \
    --assign-identity

principalId=$(az storage account show --name <storage-account> \
    --resource-group <resource_group> \
    --query identity.principalId \
    --output tsv)

$kvResourceId=$(az keyvault show \
    --resource-group <resource-group> \
    --name <key-vault> \
    --query id \
    --output tsv)

az role assignment create --assignee-object-id $principalId \
    --role "Key Vault Crypto Service Encryption User" \
    --scope $kvResourceId

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.

The format of the key URI is similar to the following examples, and can be constructed from the key vault's vaultUri property and the key name:

# Without the key version
https://<key-vault>.vault.azure.net/keys/<key>

# With the key version
https://<key-vault>.vault.azure.net/keys/<key>/<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:

az storage account encryption-scope create \
    --resource-group <resource-group> \
    --account-name <storage-account> \
    --name <encryption-scope> \
    --key-source Microsoft.KeyVault \
    --key-uri <key-uri>

Create an encryption scope protected by customer-managed keys in a different tenant

To create an encryption scope that is protected by customer-managed keys stored in a key vault or managed HSM that is in a different tenant than the storage account, first configure customer-managed keys for the storage account. You must configure a user-assigned managed identity for the storage account that has permissions to access the key vault in the other tenant. To learn more about configuring cross-tenant customer-managed keys, see Configure cross-tenant customer-managed keys for an existing storage account.

To configure customer-managed keys for use with an encryption scope, purge protection must be enabled on the key vault or managed HSM.

After you have configured cross-tenant customer-managed keys for the storage account, you can create an encryption scope on the storage account in one tenant that is scoped to a key in a key vault in the other tenant. You will need the key URI to create the cross-tenant encryption scope.

Remember to replace the placeholder values in the example with your own values:

az storage account encryption-scope create \
    --resource-group <resource-group> \
    --account-name <storage-account> \
    --name <encryption-scope> \
    --key-source Microsoft.KeyVault \
    --key-uri <key-uri>

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:

Get-AzStorageEncryptionScope -ResourceGroupName $rgName `
    -StorageAccountName $accountName

To list all encryption scopes in a resource group by storage account, use the pipeline syntax:

Get-AzStorageAccount -ResourceGroupName $rgName | Get-AzStorageEncryptionScope

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>

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:

1. Navigate to the list of containers in your storage account, and select the Add button to create a container.

2. Expand the Advanced settings in the New Container pane.

3. In the Encryption scope drop-down, select the default encryption scope for the container.

4. 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 Microsoft Entra 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.

az storage container create \
    --account-name <storage-account> \
    --resource-group <resource-group> \
    --name <container> \
    --default-encryption-scope <encryption-scope> \
    --prevent-encryption-scope-override true \
    --auth-mode login

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:

1. Navigate to the container to which you want to upload the blob.

2. Select the Upload button, and locate the blob to upload.

3. Expand the Advanced settings in the Upload blob pane.

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

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

az storage blob upload \
    --account-name <storage-account> \
    --container-name <container> \
    --file <file> \
    --name <file> \
    --encryption-scope <encryption-scope>

To change the key that protects a scope in the Azure portal, follow these steps:

1. Navigate to the Encryption Scopes tab to view the list of encryption scopes for the storage account.
2. Select the More button next to the scope you wish to modify.
3. In the Edit encryption scope pane, you can change the encryption type from Microsoft-managed key to customer-managed key or vice versa.
4. 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:

Update-AzStorageEncryptionScope -ResourceGroupName $rgName `
    -StorageAccountName $accountName `
    -EncryptionScopeName $scopeName2 `
    -StorageEncryption

Next, call the Update-AzStorageEncryptionScope command and pass in the -KeyUri and -KeyvaultEncryption parameters:

Update-AzStorageEncryptionScope -ResourceGroupName $rgName `
    -StorageAccountName $accountName `
    -EncryptionScopeName $scopeName1 `
    -KeyUri $keyUri `
    -KeyvaultEncryption

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:

az storage account encryption-scope update \
    --account-name <storage-account> \
    --resource-group <resource-group>
    --name <encryption-scope> \
    --key-source 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:

az storage account encryption-scope update \
    --resource-group <resource-group> \
    --account-name <storage-account> \
    --name <encryption-scope> \
    --key-source Microsoft.KeyVault \
    --key-uri <key-uri>

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:

Update-AzStorageEncryptionScope -ResourceGroupName $rgName `
    -StorageAccountName $accountName `
    -EncryptionScopeName $scopeName1 `
    -State disabled

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:

az storage account encryption-scope update \
    --account-name <storage-account> \
    --resource-group <resource-group> \
    --name <encryption-scope> \
    --state Disabled