Merge pull request #89023 from msmbaldwin/akv-storage-keys

Akv storage keys

Author: American-Dipper

articles/key-vault/key-vault-overview-storage-keys-powershell.md

@@ -1,47 +1,64 @@
 ---
 title: Azure Key Vault managed storage account - PowerShell version
-description: The managed storage account feature provides a seemless integration, between Azure Key Vault and an Azure storage account.
+description: The managed storage account feature provides a seamless integration, between Azure Key Vault and an Azure storage account.
 ms.topic: conceptual
 ms.service: key-vault
 author: msmbaldwin
 ms.author: mbaldwin
 manager: rkarlin
-ms.date: 03/01/2019
+ms.date: 09/10/2019
+
 # Customer intent: As a developer I want storage credentials and SAS tokens to be managed securely by Azure Key Vault.
 ---
-# Azure Key Vault managed storage account - PowerShell
+# Manage storage account keys with Key Vault and Azure PowerShell
+
+An Azure storage account uses credentials comprising 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](/azure/key-vault/about-keys-secrets-and-certificates#key-vault-secrets). 
+
+You can use the Key Vault managed storage account key feature to list (sync) keys with an Azure storage account, and regenerate (rotate) the keys periodically. You can manage keys for both storage accounts and Classic storage accounts.
+
+When you use the managed storage account key feature, consider the following points:
 
-> [!NOTE]
-> [Azure storage integration with Azure Active Directory (Azure AD) is now in preview](../storage/common/storage-auth-aad.md). 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](/azure/active-directory/managed-identities-azure-resources/) 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.
-> - AAD access to Storage Account does not work for accessing tables as of yet.
+- 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.
+
+We recommend using Azure Storage integration with Azure Active Directory (Azure AD), Microsoft's cloud-based identity and access management service. Azure AD integration is available for [Azure blobs and queues](../storage/common/storage-auth-aad.md), and 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](/azure/active-directory/managed-identities-azure-resources/) 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.
 
 [!INCLUDE [updated-for-az](../../includes/updated-for-az.md)]
 
-An [Azure storage account](/azure/storage/storage-create-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](/azure/key-vault/about-keys-secrets-and-certificates#key-vault-secrets). 
+## Service principal application ID
+
+An Azure AD tenant provides each registered application with a [service principal](/azure/active-directory/develop/developer-glossary#service-principal-object). The service principal serves as the application ID, which is used during authorization setup for access to other Azure resources via RBAC.
 
-## Overview
+Key Vault is a Microsoft application that's pre-registered in all Azure AD tenants. Key Vault is registered under the same Application ID in each Azure cloud.
 
-The Key Vault managed storage account feature performs several management functions on your behalf:
+| 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` |
 
-- 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.
+## Prerequisites
 
-When you use the managed storage account key feature:
+To complete this guide, you must first do the following:
 
-- **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.
+- [Install the Azure PowerShell module](/powershell/azure/install-az-ps?view=azps-2.6.0).
+- [Create a key vault](quick-create-powershell.md)
+- [Create an Azure storage account](../storage/common/storage-quickstart-create-account.md?tabs=azure-powershell). The storage account name must use only lowercase letters and numbers. The length of the name must be between 3 and 24 characters.
+      
 
-The following example shows you how to allow Key Vault to manage your storage account keys.
+## Manage storage account keys
 
-## Connect to your Azure account
+### Connect to your Azure account
 
 Authenticate your PowerShell session using the [Connect-AzAccount](/powershell/module/az.accounts/connect-azaccount?view=azps-2.5.0) cmdlet. 
+
 ```azurepowershell-interactive
 Connect-AzAccount
 ```
@@ -51,31 +68,33 @@ If you have multiple Azure subscriptions, you can list them using the [Get-AzSub
 Set-AzContext -SubscriptionId <subscriptionId>
 ```
 
-## Authorize Key Vault to access to your storage account
-
-> [!IMPORTANT]
-> An Azure AD tenant provides each registered application with a **[service principal](/azure/active-directory/develop/developer-glossary#service-principal-object)**, 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`.
+### Set variables
 
-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](/azure/role-based-access-control/built-in-roles#storage-account-key-operator-service-role). 
+First, set the variables to be used by the PowerShell cmdlets in the following steps. Be sure to update the <YourResourceGroupName>, <YourStorageAccountName>, and <YourKeyVaultName> placeholders, and set $keyVaultSpAppId to `cfa8b339-82a2-471a-a3c9-0fc0be7a4093` (as specified in [Service principal application ID](#service-principal-application-id), above).
 
-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:
+We will also use the Azure PowerShell [Get-AzContext](/powershell/module/az.accounts/get-azcontext?view=azps-2.6.0) and [Get-AzStorageAccount](/powershell/module/az.storage/get-azstorageaccount?view=azps-2.6.0) cmdlets to get your user ID and the context of your Azure storage account.
 
 ```azurepowershell-interactive
-# 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"
+$resourceGroupName = <YourResourceGroupName>
+$storageAccountName = <YourStorageAccountName>
+$keyVaultName = <YourKeyVaultName>
+$keyVaultSpAppId = "cfa8b339-82a2-471a-a3c9-0fc0be7a4093"
 $storageAccountKey = "key1"
-$keyVaultName = "kvContoso"
-$keyVaultSpAppId = "cfa8b339-82a2-471a-a3c9-0fc0be7a4093" # See "IMPORTANT" block above for information on Key Vault Application IDs
 
-# Get your User Id for later commands
+# Get your User Id
 $userId = (Get-AzContext).Account.Id
 
 # Get a reference to your Azure storage account
 $storageAccount = Get-AzStorageAccount -ResourceGroupName $resourceGroupName -StorageAccountName $storageAccountName
+```
+
+### Give Key Vault access to your storage account
+
+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](/azure/role-based-access-control/built-in-roles#storage-account-key-operator-service-role). 
 
+Assign this role to the Key Vault service principal, limiting scope to your storage account, using the Azure PowerShell [New-AzRoleAssignment](/powershell/module/az.resources/new-azroleassignment?view=azps-2.6.0) cmdlet.
+
+```azurepowershell-interactive
 # 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
 ```
@@ -96,12 +115,9 @@ 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
+### 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: 
+Use the Azure PowerShell [Set-AzKeyVaultAccessPolicy](/powershell/module/az.keyvault/set-azkeyvaultaccesspolicy?view=azps-2.6.0) cmdlet to update the Key Vault access policy and grant storage account permissions to your user account.
 
 ```azurepowershell-interactive
 # Give your user principal access to all storage account permissions, on your Key Vault instance
@@ -111,12 +127,13 @@ Set-AzKeyVaultAccessPolicy -VaultName $keyVaultName -UserPrincipalName $userId -
 
 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
+### 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.
+Use the Azure PowerShell [Add-AzKeyVaultManagedStorageAccount](/powershell/module/az.keyvault/add-azkeyvaultmanagedstorageaccount?view=azps-2.6.0) cmdlet to create a managed storage account in your Key Vault instance. The  `-DisableAutoRegenerateKey` switch specifies NOT to regenerate the storage account keys.
 
 ```azurepowershell-interactive
 # Add your storage account to your Key Vault's managed storage accounts
+
 Add-AzKeyVaultManagedStorageAccount -VaultName $keyVaultName -AccountName $storageAccountName -AccountResourceId $storageAccount.Id -ActiveKeyName $storageAccountKey -DisableAutoRegenerateKey
 ```
 
@@ -138,10 +155,11 @@ 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 'key2' and swap the active key from 'key2' to 'key1'.
+If you want Key Vault to regenerate your storage account keys periodically, you can use the Azure PowerShell [Add-AzKeyVaultManagedStorageAccount](/powershell/module/az.keyvault/add-azkeyvaultmanagedstorageaccount?view=azps-2.6.0) cmdlet to set a regeneration period. In this example, we set a regeneration period of three days. After three days, Key Vault will regenerate 'key2' and swap the active key from 'key2' to 'key1'.
 
 ```azurepowershell-interactive
 $regenPeriod = [System.Timespan]::FromDays(3)
+
 Add-AzKeyVaultManagedStorageAccount -VaultName $keyVaultName -AccountName $storageAccountName -AccountResourceId $storageAccount.Id -ActiveKeyName $storageAccountKey -RegenerationPeriod $regenPeriod
 ```
 
@@ -161,6 +179,85 @@ Updated             : 11/19/2018 11:54:47 PM
 Tags                : 
 ```
 
+## Shared access signature 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. 
+- 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.
+- Verify that the shared access signature was saved in your key vault as a secret.
+- 
+### Set variables
+
+First, set the variables to be used by the PowerShell cmdlets in the following steps. Be sure to update the <YourStorageAccountName> and <YourKeyVaultName> placeholders.
+
+We will also use the Azure PowerShell [New-AzStorageContext](/powershell/module/az.storage/new-azstoragecontext?view=azps-2.6.0) cmdlets to get the context of your Azure storage account.
+
+```azurepowershell-interactive
+$storageAccountName = <YourStorageAccountName>
+$keyVaultName = <YourKeyVaultName>
+
+$storageContext = New-AzStorageContext -StorageAccountName $storageAccountName -Protocol Https -StorageAccountKey Key1
+```
+
+### Create a shared access signature token
+
+Create a shared access signature definition using the Azure PowerShell [New-AzStorageAccountSASToken](/powershell/module/az.storage/new-azstorageaccountsastoken?view=azps-2.6.0) cmdlets.
+ 
+```azurepowershell-interactive
+$start = [System.DateTime]::Now.AddDays(-1)
+$end = [System.DateTime]::Now.AddMonths(1)
+
+$sasToken = New-AzStorageAccountSasToken -Service blob,file,Table,Queue -ResourceType Service,Container,Object -Permission "racwdlup" -Protocol HttpsOnly -StartTime $start -ExpiryTime $end -Context $storageContext
+```
+The value of $sasToken will look similar to this.
+
+```console
+?sv=2018-11-09&sig=5GWqHFkEOtM7W9alOgoXSCOJO%2B55qJr4J7tHQjCId9S%3D&spr=https&st=2019-09-18T18%3A25%3A00Z&se=2019-10-19T18%3A25%3A00Z&srt=sco&ss=bfqt&sp=racupwdl
+```
+
+### Generate a shared access signature definition
+
+Use the the Azure PowerShell [Set-AzKeyVaultManagedStorageSasDefinition](/powershell/module/az.keyvault/set-azkeyvaultmanagedstoragesasdefinition?view=azps-2.6.0) cmdlet to create a shared access signature definition.  You can provide the name of your choice to the `-Name` parameter.
+
+```azurepowershell-interactive
+Set-AzKeyVaultManagedStorageSasDefinition -AccountName $storageAccountName -VaultName $keyVaultName -Name <YourSASDefinitionName> -TemplateUri $sasToken -SasType 'account' -ValidityPeriod ([System.Timespan]::FromDays(30))
+```
+
+### Verify the shared access signature definition
+
+You can verify that the shared access signature definition has been stored in your key vault using the Azure PowerShell [Get-AzKeyVaultSecret](/powershell/module/az.keyvault/get-azkeyvaultsecret?view=azps-2.6.0) cmdlet.
+
+First, find the shared access signature definition in your key vault.
+
+```azurepowershell-interactive
+Get-AzKeyVaultSecret -vault-name <YourKeyVaultName>
+```
+
+The secret corresponding to your SAS definition will have these properties:
+
+```console
+Vault Name   : <YourKeyVaultName>
+Name         : <SecretName>
+...
+Content Type : application/vnd.ms-sastoken-storage
+Tags         :
+```
+
+You can now use the [Get-AzKeyVaultSecret](/cli/azure/keyvault/secret?view=azure-cli-latest#az-keyvault-secret-show) cmdlet and the secret `Name` property to view the content of that secret.
+
+```azurepowershell-interactive
+$secret = Get-AzKeyVaultSecret -VaultName <YourKeyVaultName> -Name <SecretName>
+
+Write-Host $secret.SecretValueText
+```
+
+The output of this command will show your SAS definition string.
+
+
 ## Next steps
 
 - [Managed storage account key samples](https://github.com/Azure-Samples?utf8=%E2%9C%93&q=key+vault+storage&type=&language=)