Working With Azure Key Vault Using Azure PowerShell

Introduction

This article demonstrates what Azure Key Vault is, how to create Azure Key Vault, Key Vault Keys and Secrets, Remove Key, and Secret Key Vault. We will also discuss how to grant permissions to Azure Key Vault. All of these, with help of Azure PowerShell.

What is Azure Key Vault?

Azure Key Vault is an Azure resource used to safeguard cryptographic keys and secrets (such as - authentication keys, storage account keys, data encryption keys, .PFX files, and passwords) used by cloud apps and services. Storing such values in Key Vault gives more security and control over keys and passwords. Key Vault streamlines the key management process and enables you to maintain control of the keys which access and encrypt your data. Developers can create keys for development and testing in minutes, and then seamlessly migrate them to production keys. Security administrators can grant (and revoke) permission to keys, as needed. With Azure Key Vault, you can encrypt keys and small secrets like passwords using keys stored in hardware security modules (HSMs). For added assurance, you can import or generate keys in HSMs. If you choose to do this, Microsoft will process your keys in FIPS 140-2 Level 2 validated HSMs (hardware and firmware). Key Vault is designed so that Microsoft does not see or extract your keys. You can monitor and audit the key used with Azure logging.

Prerequisite

Before starting to work with Azure web app with PowerShell, we need to make sure that we have necessary prerequisites. You need to install Azure PowerShell on your machine. I have detailed explained in my other article Creating Azure Resource Group With PowerShell. This article also explains about Resource Group which is a logical group of Azure resources and how it helps to group the resources. Before going to next step in this article, perform the following steps mentioned in the above article.

Login to Azure Account
Select appropriate subscription
Create a resource group if not already exists.

Create Azure Key Vault

Once you have a target resource group, select a resource group, as below, in a variable.

$resourceGroup = Get-AzureRmResourceGroup -Name <ResourceGroupName>

You can validate the value of $resourceGroup variable by entering variable name on the PowerShell Prompt.

ResourceGroupName: {
ResourceGroupName
}
Location: eastus
ProvisioningState: Succeeded
Tags: ResourceId: /subscriptions/ {
guid
}
/resourceGroups/ {
ResourceGroupName
}

To create new Key Vault in the selected resource group, use New-AzureRmKeyVault cmdlet. This cmdlet takes ResourceGroupName, VaultName, and Location as required parameters.

New-AzureRmKeyVault -ResourceGroupName $resourceGroup.ResourceGroupName -Name "KeyVaultTestResource" -Location "eastus"

In the above command, we passed resource group name which we captured in $resourceGroup variable. If Key Vault with specified name (in our case, it is KeyVaultTestResource) is available, Key Vault is created in target Azure Resource group and displays newly created Key Vault details.

Vault Name: KeyVaultTestResource
Resource Group Name: {
ResourceGroupName
}
Location: eastus
Resource ID: /subscriptions/ {
SubscriptionId
}
/resourceGroups/ {
ResourceGroupName
}
/providers/Microsoft.KeyVault / vaults / KeyVaultTestResource
Vault URI: https: //KeyVaultTestResource.vault.azure.net
Tenant ID: {
TenantId
}
SKU: Standard
Enabled For Deployment ? : False
Enabled For Template Deployment ? : False
Enabled For Disk Encryption ? : False
Access Policies: Tenant ID: {
TenantId
}
Object ID: {
User Object ID
}
Application ID: Display Name: {
CurrentUser Display Name with Azure Account
}
Permissions to Keys: get, create, delete, list, update,
import, backup, restore
Permissions to Secrets: all
Permissions to Certificates: all
Tags:

Note that if parameter value for VaultName isn’t available in Azure, the above cmdlet will fail with exception -New-AzureRmKeyVault : The name '{VaultName}' is already in use. The reason is that the vault name you used to create new vault has already been used by someone else and you can’t use the same name.

Vault URI property of the above result is identifier of the new Key Vault. You can use this Vault URI if you need to access Key Vault programmatically using Azure Key Vault Client. I will be explaining this in another article about how to access Azure Key Vault programmatically using Key Vault Client. SKU property indicates the current Key Vault SKU. Key Vault resource only supports Standard and Premium SKUs. Access Policy property indicates that currently who has access to Key Vault. By default, current user is granted permission for both, Key and Secret Management. The {Object ID} property indicates the current user Azure AD object ID. Also, it displays details permission levels for Keys, Secrets, and Certificates.

Get Target Key Vault

To get existing web app from Azure, use Get-AzureRmKeyVault cmdlet. It again takes ResourceGroupName and VaultName as required parameters.

Get-AzureRmKeyVault -ResourceGroupName $resourceGroup.ResourceGroupName -VaultName "KeyVaultTestResource"

To get all key vaults within a resource group, you just pass ResourceGroupName parameter to above cmdlet.

Get-AzureRmKeyVault -ResourceGroupName $resourceGroup.ResourceGroupName

To get all key vaults within your subscription, don’t pass any parameter to above cmdlet.

Get-AzureRmKeyVault

Delete Key Vault

To delete the Azure Key Vault, use Remove-AzureRmKeyVault. It takes VaultName as required parameter. Though you should use ResourceGroupName parameter for better performance.

Remove-AzureRmKeyVault -VaultName "KeyVaultTestResource" –ResourceGroupName $resourceGroup.ResourceGroupName

Working with Keys

Create or Import Key in Key Vault

You can create or import key(s) in Key Vault with help of PowerShell. Keys can be added to Key Vault with any of the following methods.

Create a key in a hardware security module (HSM) in Key Vault service.
Create a key in software in the Key Vault service.
Import a key from your own hardware security module (HCM) to HCMs in Key Vault service
Import a key from a .pfx file from your computer
Import a key from a .pfx file on your competer to hardware security module (HCM) in Key Vault service.

For any of these attributes, you can provide key attributes or use default settings.

If you create or import a key that has the same name as an existing key in your key vault, the original key is updated with the values that you specify for the new key. You can access the previous values by using the version-specific URI for that version of the key.

Note- To import a key from your own hardware security module, you must first generate a BYOK package (a file with a .byok file name extension) by using the Azure Key Vault BYOK toolset.

As a best practice, back up your key after it is created or updated, by using the Backup-AzureKeyVaultKey cmdlet. There is no undelete functionality, so if you accidentally or intentionally delete your key but change your mind, the key is not recoverable unless you have a backup of it that you can restore.

To create new key in Key Vault, use Add-AzureKeyVaultKey cmdlet with VaultName and Name parameter along with Destination as optional parameter in certain cases.

The below command creates a software protected key named ‘CertSoftwareKey’ in the Key Vault named ‘KeyVaultTestResource’.

Add-AzureKeyVaultKey –VaultName ‘KeyVaultTestResource’ –Name ‘CertSoftwareKey’ –Destination ‘Software’

It generates the following output. Every new or update to existing key operation generates new version for the key. Id attribute constitutes of Version which uniquely identifies the key.

The below command creates a HSM protected key named ‘CertHSMKey’ in the Key Vault named ‘KeyVaultTestResource’.

Add-AzureKeyVaultKey –VaultName ‘KeyVaultTestResource’ –Name ‘CertHSMKey’ –Destination ‘HSM’

Note

Hardware key operations can only be performed in ‘Premium’ SKU.

Below command imports the software protected key.

$password = ConvertTo-SecureString -string '{Password}' -AsPlainText –Force
Add-AzureKeyVaultKey –VaultName ‘KeyVaultTestResource’ –Name ‘CertPfxKey’ –KeyFilePath ‘{Path of .pfx file}’ –KeyFilePassword $password

The first command converts a string into a secure string by using the ConvertTo-SecureString cmdlet, and then stores that string in the $password variable.

The second command creates a software password in the KeyVaultTestResource key vault. The command specifies the location for the key and the password stored in $password.

Delete Key in Key Vault

To delete the key from Azure Key Vault, use Remove-AzureKeyVaultKey cmdlet. It takes VaultName and Name as required parameters.

Remove-AzureKeyVaultKey -VaultName ‘KeyVaultTestResource’ -Name ‘CertHSMKey’

Working with Secrets

Create Secret in Key Vault

To create or update Secret in Azure Key Vault, use Set-AzureKeyVaultSecret cmdlet. The Set-AzureKeyVaultSecret cmdlet creates or updates a secret in a key vault in Azure Key Vault. If the secret does not exist, this cmdlet creates it. If the secret already exists, this cmdlet creates a new version of that secret.

$password = ConvertTo-SecureString -string '{Password}' -AsPlainText –Force
Set-AzureKeyVaultSecret –VaultName ‘KeyVaultTestResource’ –Name ‘SQLPassword’ -SecretValue $password

The first command converts a string into a secure string by using the ConvertTo-SecureString cmdlet, and then stores that string in the $password variable.

The second command modifies value of the secret named SQLPassword in the key vault named KeyVaultTestResource. The secret value becomes the value stored in $password.

Delete Secret in Key Vault

To remove the secret from key vault, use Remove-AzureKeyVaultSecret cmdlet. This cmdlet takes VaultName and Name parameters.

Remove-AzureKeyVaultSecret –VaultName ‘KeyVaultTestResource’ –Name ‘SQLPassword’

Permission to Key Vault

Azure Key Vault is used to secure sensitive information. It can further be controlled by providing appropriate/required permissions to user, group or application in Azure. The permissions to Key Vault can be fine grained to perform specific operation in the Key Vault.

By default, user who creates Azure Key Vault is granted full permissions on keys and secrets with target Key Vault. To grant or modify existing permission, use Set-AzureRmKeyVaultAccessPolicy cmdlet. This cmdlet grants or modifies existing permissions for a user, application, or security group to perform the specified operations with a key vault. It does not modify the permissions that other users, applications, or security groups have on the key vault. If you are setting permissions for a security group, this operation affects only users in that security group.

Set-AzureRmKeyVaultAccessPolicy -VaultName 'KeyVaultTestResource' -UserPrincipalName '[email protected]' -PermissionsToKeys create,import,delete,list -PermissionsToSecrets 'Set,Delete'

Above command grants permissions for a user in your Azure Active Directory, [email protected], to perform operations on keys and secrets with a key vault named KeyVaultTestResource.

$AADApplicationName =”TestADApp”
$AADApp = Get-AzureRmADApplication -DisplayNameStartWith $AADApplicationName
$servicePrincipal = Get-AzureRmADServicePrincipal -SearchString $AADApp.DisplayName
Set-AzureRmKeyVaultAccessPolicy -VaultName 'KeyVaultTestResource' -ServicePrincipalName $servicePrincipal.ServicePrincipalNames[0] -PermissionsToSecrets 'Get'

In the above example, the first command sets Azure AD application name to variable $AADApplicationName. The second command gets Azure AD application with help of its Display Name. The third command retrieves the Azure AD Application Service Principal based on application name. The forth command then sets the permissions using Azure AD Application Service Principal name to Azure Key Vault Secrets to the ‘Get’ operation.

Summary

In this article, I discussed what Azure Key Vault is, along with the benefits of using Key Vault. We also looked into how to work with Keys and Secrets in Key Vault. Further, we discussed how to grant permissions to Key Vault to user and Azure AD application. All of these operations, using Azure PowerShell cmdlets.