Manage storage account keys with Azure Key Vault and the Azure CLI

Azure Key Vault manages keys for Azure storage accounts and classic storage accounts. You can use the Key Vault managed storage account feature to complete several key management functions for you.

An Azure storage account uses a credential that consists of an account name and a key. The key is autogenerated and serves as a password, rather than an as a cryptographic key. Key Vault manages storage account keys by storing them as Key Vault secrets. Keys are listed (synced) with an Azure storage account and are periodically regenerated or rotated.

When you use the managed storage account key feature, consider the following points:

  • Key values are never returned in response to a caller.
  • Only Key Vault should manage your storage account keys. Don't manage the keys yourself and avoid interfering with Key Vault processes.
  • Only a single Key Vault object should manage storage account keys. Don't allow key management from multiple objects.
  • You can request Key Vault to manage your storage account with a user principal, but not with a service principal.
  • Regenerate keys by using Key Vault only. Don't manually regenerate your storage account keys.

Note

Azure Storage integration with Azure Active Directory (Azure AD) is Microsoft's cloud-based identity and access management service. Azure AD integration is available for Azure blobs and queues. Use Azure AD for authentication and authorization. Azure AD provides OAuth2 token-based access to Azure Storage just like Azure Key Vault.

Azure AD allows you to authenticate your client application by using an application or user identity, instead of storage account credentials. You can use an Azure AD managed identity when you run on Azure. Managed identities remove the need for client authentication and storing credentials in or with your application. Azure AD uses role-based access control (RBAC) to manage authorization, which is also supported by Key Vault.

Service principal application ID

An Azure AD tenant provides each registered application with a service principal. The service principal serves as the application identity (ID). The Application ID is used during authorization setup for access to other Azure resources via RBAC.

Key Vault is a Microsoft application that's pre-registered in all Azure AD tenants. The Key Vault is registered under the same Application ID and within each Azure cloud.

Tenants Cloud Application ID
Azure AD Azure Government 7e7c393b-45d0-48b1-a35e-2905ddf8183c
Azure AD Azure public cfa8b339-82a2-471a-a3c9-0fc0be7a4093
Other Any cfa8b339-82a2-471a-a3c9-0fc0be7a4093

Prerequisites

Before you use Key Vault to manage your storage account key, review the prerequisites:

  • Install the Azure CLI.
  • Create an Azure storage account. Follow these steps.
  • The storage account name must use only lowercase letters and numbers. The length of the name must be between 3 and 24 characters.

Manage storage account keys

There are four basic steps to use Key Vault to manage storage account keys:

  1. Get an existing storage account.
  2. Fetch an existing key vault.
  3. Add a Key Vault managed storage account to the vault. Set key1 as the active key with a regeneration period of 180 days.
  4. Use key1 to set a storage context for the specified storage account.

Note

Key Vault as a service is assigned operator permissions on your storage account.

After you set up Azure Key Vault managed storage account keys, only change the keys by using Key Vault. For managed storage account keys, Key Vault manages the rotation of the storage account key.

  1. After you create a storage account, run the following command to get the resource ID of the storage account to manage:

    az storage account show -n storageaccountname
    

    Copy the resource ID value from the command output:

    /subscriptions/<subscription ID>/resourceGroups/ResourceGroup/providers/Microsoft.Storage/storageAccounts/StorageAccountName
    

    Example output:

    "objectId": "93c27d83-f79b-4cb2-8dd4-4aa716542e74"
    
  2. Assign the "Storage Account Key Operator Service Role" RBAC role to Key Vault. This role limits the access scope to your storage account. For a classic storage account, use the "Classic Storage Account Key Operator Service Role" role.

    az role assignment create --role "Storage Account Key Operator Service Role" --assignee-object-id 93c27d83-f79b-4cb2-8dd4-4aa716542e74 --scope "/subscriptions/<subscriptionID>/resourceGroups/<StorageAccountResourceGroupName>/providers/Microsoft.Storage/storageAccounts/<StorageAccountName>"
    

    93c27d83-f79b-4cb2-8dd4-4aa716542e74 is the Object ID for Key Vault in the Azure public cloud. To get the Object ID for Key Vault in the Azure Government cloud, see Service principal application ID.

  3. Create a Key Vault Managed storage account:

    Set a regeneration period of 90 days. After 90 days, Key Vault regenerates key1 and swaps the active key from key2 to key1. key1 is then marked as the active key.

    az keyvault storage add --vault-name <YourVaultName> -n <StorageAccountName> --active-key-name key1 --auto-regenerate-key --regeneration-period P90D --resource-id <Id-of-storage-account>
    

Create and generate tokens

You can also ask Key Vault to generate shared access signature tokens. A shared access signature provides delegated access to resources in your storage account. You can grant clients access to resources in your storage account without sharing your account keys. A shared access signature provides you with a secure way to share your storage resources without compromising your account keys.

The commands in this section complete the following actions:

  • Set an account shared access signature definition <YourSASDefinitionName>. The definition is set on a Key Vault managed storage account <YourStorageAccountName> in your key vault <VaultName>.
  • Create an account shared access signature token for Blob, File, Table, and Queue services. The token is created for resource types Service, Container, and Object. The token is created with all permissions, over https, and with the specified start and end dates.
  • Set a Key Vault managed storage shared access signature definition in the vault. The definition has the template URI of the shared access signature token that was created. The definition has the shared access signature type account and is valid for N days.
  • Retrieve the actual access token from the Key Vault secret that corresponds to the shared access signature definition.

After you complete the steps in the previous section, run the following commands to ask Key Vault to generate shared access signature tokens.

  1. Create a shared access signature definition. After the shared access signature definition is created, ask Key Vault to generate more shared access signature tokens. This operation requires the storage and setsas permissions.

    $sastoken = az storage account generate-sas --expiry 2020-01-01 --permissions rw --resource-types sco --services bfqt --https-only --account-name storageacct --account-key 00000000
    

    For help about the operation, see the az storage account generate-sas reference documentation.

    After the operation runs successfully, copy the output.

       "se=2020-01-01&sp=***"
    
  2. Use the $sasToken generated by the previous command and create a shared access signature definition. For more information about the command parameters, see the az keyvault storage sas-definition create reference documentation.

    az keyvault storage sas-definition create --vault-name <YourVaultName> --account-name <YourStorageAccountName> -n <NameOfSasDefinitionYouWantToGive> --validity-period P2D --sas-type account --template-uri $sastoken
    

    When the user doesn't have permissions to the storage account, first get the Object ID of the user:

    az ad user show --upn-or-object-id "developer@contoso.com"
    
    az keyvault set-policy --name <YourVaultName> --object-id <ObjectId> --storage-permissions backup delete list regeneratekey recover     purge restore set setsas update
    

Fetch tokens in code

Execute operations on your storage account by fetching shared access signature tokens from Key Vault.

There are three ways to authenticate to Key Vault:

  • Use a managed service identity. This approach is highly recommended.
  • Use a service principal and certificate.
  • Use a service principal and password. This approach isn't recommended.

For more information, see Azure Key Vault: Basic concepts.

The following example demonstrates how to fetch shared access signature tokens. You fetch the tokens after you create a shared access signature definition.

// After you get a security token, create KeyVaultClient with vault credentials.
var kv = new KeyVaultClient(new KeyVaultClient.AuthenticationCallback(securityToken));

// Get a shared access signature token for your storage from Key Vault.
// The format for SecretUri is https://<VaultName>.vault.azure.net/secrets/<ExamplePassword>
var sasToken = await kv.GetSecretAsync("SecretUri");

// Create new storage credentials by using the shared access signature token.
var accountSasCredential = new StorageCredentials(sasToken.Value);

// Use the storage credentials and the Blob storage endpoint to create a new Blob service client.
var accountWithSas = new CloudStorageAccount(accountSasCredential, new Uri ("https://myaccount.blob.core.windows.net/"), null, null, null);

var blobClientWithSas = accountWithSas.CreateCloudBlobClient();

If your shared access signature token is about to expire, fetch the shared access signature token again from Key Vault and update the code.

// If your shared access signature token is about to expire,
// get the shared access signature token again from Key Vault and update it.
sasToken = await kv.GetSecretAsync("SecretUri");
accountSasCredential.UpdateSASToken(sasToken);

Azure CLI commands

For information about the Azure CLI commands that are relevant to managed storage accounts, see the az keyvault storage reference documentation.

Next steps