Azure Key Vault managed storage account - PowerShell

Note

Azure storage integration with Azure Active Directory (Azure AD) is now in preview. We recommend using Azure AD for authentication and authorization, which provides OAuth2 token-based access to Azure storage, just like Azure Key Vault. This allows you to:

  • Authenticate your client application using an application or user identity, instead of storage account credentials.
  • Use an Azure AD managed identity when running on Azure. Managed identities remove the need for client authentication all together, and storing credentials in or with your application.
  • Use Role Based Access Control (RBAC) for managing authorization, which is also supported by Key Vault.

Note

This article has been updated to use the new Azure PowerShell Az module. To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. For installation instructions, see Install Azure PowerShell.

An Azure storage account uses a credential that consists of an account name and a key. The key is autogenerated, and serves more as a "password" as opposed to a cryptographic key. Key Vault can manage these storage account keys, by storing them as Key Vault secrets.

Overview

The Key Vault managed storage account feature performs several management functions on your behalf:

  • Lists (syncs) keys with an Azure storage account.
  • Regenerates (rotates) the keys periodically.
  • Manages keys for both storage accounts and Classic storage accounts.
  • Key values are never returned in response to caller.

When you use the managed storage account key feature:

  • Only allow Key Vault to manage your storage account keys. Don't attempt to manage them yourself, as you'll interfere with Key Vault's processes.
  • Don't allow storage account keys to be managed by more than one Key Vault object.
  • Don't manually regenerate your storage account keys. We recommend that you regenerate them via Key Vault.

The following example shows you how to allow Key Vault to manage your storage account keys.

Authorize Key Vault to access to your storage account

Important

An Azure AD tenant provides each registered application with a service principal, which serves as the application's identity. The service principal's Application ID is used when giving it authorization to access other Azure resources, through role-based access control (RBAC). Because Key Vault is a Microsoft application, it's pre-registered in all Azure AD tenants under the same Application ID, within each Azure cloud:

  • Azure AD tenants in Azure government cloud use Application ID 7e7c393b-45d0-48b1-a35e-2905ddf8183c.
  • Azure AD tenants in Azure public cloud and all others use Application ID cfa8b339-82a2-471a-a3c9-0fc0be7a4093.

Before Key Vault can access and manage your storage account keys, you must authorize its access your storage account. The Key Vault application requires permissions to list and regenerate keys for your storage account. These permissions are enabled through the built-in RBAC role Storage Account Key Operator Service Role.

Assign this role to the Key Vault service principal, limiting scope to your storage account, using the following steps. Be sure to update the $resourceGroupName, $storageAccountName, $storageAccountKey, and $keyVaultName variables before you run the script:

# TODO: Update with the resource group where your storage account resides, your storage account name, the name of your active storage account key, and your Key Vault instance name
$resourceGroupName = "rgContoso"
$storageAccountName = "sacontoso"
$storageAccountKey = "key1"
$keyVaultName = "kvContoso"
$keyVaultSpAppId = "cfa8b339-82a2-471a-a3c9-0fc0be7a4093" # See "IMPORTANT" block above for information on Key Vault Application IDs

# Authenticate your PowerShell session with Azure AD, for use with Azure Resource Manager cmdlets
$azureProfile = Connect-AzAccount

# Get a reference to your Azure storage account
$storageAccount = Get-AzStorageAccount -ResourceGroupName $resourceGroupName -StorageAccountName $storageAccountName

# Assign RBAC role "Storage Account Key Operator Service Role" to Key Vault, limiting the access scope to your storage account. For a classic storage account, use "Classic Storage Account Key Operator Service Role." 
New-AzRoleAssignment -ApplicationId $keyVaultSpAppId -RoleDefinitionName 'Storage Account Key Operator Service Role' -Scope $storageAccount.Id

Upon successful role assignment, you should see output similar to the following example:

RoleAssignmentId   : /subscriptions/03f0blll-ce69-483a-a092-d06ea46dfb8z/resourceGroups/rgContoso/providers/Microsoft.Storage/storageAccounts/sacontoso/providers/Microsoft.Authorization/roleAssignments/189cblll-12fb-406e-8699-4eef8b2b9ecz
Scope              : /subscriptions/03f0blll-ce69-483a-a092-d06ea46dfb8z/resourceGroups/rgContoso/providers/Microsoft.Storage/storageAccounts/sacontoso
DisplayName        : Azure Key Vault
SignInName         :
RoleDefinitionName : storage account Key Operator Service Role
RoleDefinitionId   : 81a9662b-bebf-436f-a333-f67b29880f12
ObjectId           : 93c27d83-f79b-4cb2-8dd4-4aa716542e74
ObjectType         : ServicePrincipal
CanDelegate        : False

If Key Vault has already been added to the role on your storage account, you'll receive a "The role assignment already exists." error. You can also verify the role assignment, using the storage account "Access control (IAM)" page in the Azure portal.

Give your user account permission to managed storage accounts

Tip

Just as Azure AD provides a service principal for an application's identity, a user principal is provided for a user's identity. The user principal can then be given authorization to access Key Vault, through Key Vault access policy permissions.

Using the same PowerShell session, update the Key Vault access policy for managed storage accounts. This step applies storage account permissions to your user account, ensuring that you can access the managed storage account features:

# Give your user principal access to all storage account permissions, on your Key Vault instance

Set-AzKeyVaultAccessPolicy -VaultName $keyVaultName -UserPrincipalName $azureProfile.Context.Account.Id -PermissionsToStorage get, list, listsas, delete, set, update, regeneratekey, recover, backup, restore, purge

Note that permissions for storage accounts aren't available on the storage account "Access policies" page in the Azure portal.

Add a managed storage account to your Key Vault instance

Using the same PowerShell session, create a managed storage account in your Key Vault instance. The -DisableAutoRegenerateKey switch specifies NOT to regenerate the storage account keys.

# Add your storage account to your Key Vault's managed storage accounts
Add-AzKeyVaultManagedStorageAccount -VaultName $keyVaultName -AccountName $storageAccountName -AccountResourceId $storageAccount.Id -ActiveKeyName $storageAccountKey -DisableAutoRegenerateKey

Upon successful addition of the storage account with no key regeneration, you should see output similar to the following example:

Id                  : https://kvcontoso.vault.azure.net:443/storage/sacontoso
Vault Name          : kvcontoso
AccountName         : sacontoso
Account Resource Id : /subscriptions/03f0blll-ce69-483a-a092-d06ea46dfb8z/resourceGroups/rgContoso/providers/Microsoft.Storage/storageAccounts/sacontoso
Active Key Name     : key1
Auto Regenerate Key : False
Regeneration Period : 90.00:00:00
Enabled             : True
Created             : 11/19/2018 11:54:47 PM
Updated             : 11/19/2018 11:54:47 PM
Tags                : 

Enable key regeneration

If you want Key Vault to regenerate your storage account keys periodically, you can set a regeneration period. In the following example, we set a regeneration period of three days. After three days, Key Vault will regenerate 'key1' and swap the active key from 'key2' to 'key1'.

$regenPeriod = [System.Timespan]::FromDays(3)
Add-AzKeyVaultManagedStorageAccount -VaultName $keyVaultName -AccountName $storageAccountName -AccountResourceId $storageAccount.Id -ActiveKeyName $storageAccountKey -RegenerationPeriod $regenPeriod

Upon successful addition of the storage account with key regeneration, you should see output similar to the following example:

Id                  : https://kvcontoso.vault.azure.net:443/storage/sacontoso
Vault Name          : kvcontoso
AccountName         : sacontoso
Account Resource Id : /subscriptions/03f0blll-ce69-483a-a092-d06ea46dfb8z/resourceGroups/rgContoso/providers/Microsoft.Storage/storageAccounts/sacontoso
Active Key Name     : key1
Auto Regenerate Key : True
Regeneration Period : 3.00:00:00
Enabled             : True
Created             : 11/19/2018 11:54:47 PM
Updated             : 11/19/2018 11:54:47 PM
Tags                : 

Next steps