Manage Key Vault in Azure Stack by using PowerShell

This article helps you get started to create and manage Key Vault in Azure Stack by using PowerShell. The Key Vault PowerShell cmdlets described in this article are available as a part of the Azure PowerShell SDK. The following sections describe the PowerShell cmdlets that are required to:

  • Create a vault.
  • Store and manage cryptographic keys and secrets.
  • Authorize users or applications to invoke operations in the vault.

Prerequisites

Enable your tenant subscription for Key Vault operations

Before you can issue any operations against a key vault, you need to ensure that your tenant subscription is enabled for vault operations. To verify that vault operations are enabled, run the following command:

Get-AzureRmResourceProvider -ProviderNamespace Microsoft.KeyVault | ft -Autosize

Output

If your subscription is enabled for vault operations, the output shows “RegistrationState” equals “Registered” for all resource types of a key vault.

Registration state

If vault operations are not enabled, invoke the following command to register the Key Vault service in your subscription:

Register-AzureRmResourceProvider -ProviderNamespace Microsoft.KeyVault

Output

If the registration is successful, the following output is returned:

Register When you invoke the key vault commands, you might get an error, such as "The subscription is not registered to use namespace 'Microsoft.KeyVault'." If you get an error, confirm that you have enabled the Key Vault resource provider by following the instructions that were mentioned previously.

Create a key vault

Before you create a key vault, create a resource group so that all of the resources related to the key vault exist in a resource group. Use the following command to create a new resource group:

New-AzureRmResourceGroup -Name “VaultRG” -Location local -verbose -Force

Output

New resource group

Now, use the New-AzureRMKeyVault command to create a key vault in the resource group that you created earlier. This command reads three mandatory parameters: resource group name, key vault name, and geographic location.

Run the following command to create a key vault:

New-AzureRmKeyVault -VaultName “Vault01” -ResourceGroupName “VaultRG” -Location local -verbose

Output

New key vault

The output of this command shows the properties of the key vault that you created. When an application accesses this vault, it uses the Vault URI property shown in the output. For example, the vault Uniform Resource Identifier (URI) in this case is "https://vault01.vault.local.azurestack.external". Applications that interact with this key vault through REST API must use this URI.

In Active Directory Federation Services (AD FS)-based deployments, when you create a key vault by using PowerShell, you might receive a warning that says "Access policy is not set. No user or application has access permission to use this vault." To resolve this issue, set an access policy for the vault by using the Set-AzureRmKeyVaultAccessPolicy command:

# Obtain the security identifier(SID) of the active directory user
$adUser = Get-ADUser -Filter "Name -eq '{Active directory user name}'"
$objectSID = $adUser.SID.Value 

#Set the key vault access policy
Set-AzureRmKeyVaultAccessPolicy -VaultName "{key vault name}" -ResourceGroupName "{resource group name}" -ObjectId "{object SID}" -PermissionsToKeys {permissionsToKeys} -PermissionsToSecrets {permissionsToSecrets} -BypassObjectIdValidation 

Manage keys and secrets

After you create a vault, use the following steps to create and manage keys and secrets within the vault.

Create a key

Use the Add-AzureKeyVaultKey command to create or import a software-protected key in a key vault.

Add-AzureKeyVaultKey -VaultName “Vault01” -Name “Key01” -verbose -Destination Software

The Destination parameter is used to specify that the key is software protected. When the key is successfully created, the command outputs the details of the created key.

Output

New key

You can now reference the created key by using its URI. If you create or import a key that has same name as an existing key, the original key is updated with the values specified in the new key. You can access the previous version by using the version-specific URI of the key. For example:

Get a key

Use the Get-AzureKeyVaultKey command to read a key and its details.

Get-AzureKeyVaultKey -VaultName “Vault01” -Name “Key01”

Create a secret

Use the Set-AzureKeyVaultSecret command to create or update a secret in a vault. A secret is created if one doesn’t already exist. A new version of the secret is created if it already exists.

$secretvalue = ConvertTo-SecureString “User@123” -AsPlainText -Force
Set-AzureKeyVaultSecret -VaultName “Vault01” -Name “Secret01” -SecretValue $secretvalue

Output

Create a secret

Get a secret

Use the Get-AzureKeyVaultSecret command to read a secret in a key vault. This command can return all or specific versions of a secret.

Get-AzureKeyVaultSecret -VaultName “Vault01” -Name “Secret01”

After you create the keys and secrets, you can authorize external applications to use them.

Authorize an application to use a key or secret

Use the Set-AzureRmKeyVaultAccessPolicy command to authorize an application to access a key or secret in the key vault. In the following example, the vault name is ContosoKeyVault and the application you want to authorize has a client ID of 8f8c4bbd-485b-45fd-98f7-ec6300b7b4ed. To authorize the application, run the following command. Optionally, you can specify the PermissionsToKeys parameter to set permissions for a user, application, or a security group.

Set-AzureRmKeyVaultAccessPolicy -VaultName 'ContosoKeyVault' -ServicePrincipalName 8f8c4bbd-485b-45fd-98f7-ec6300b7b4ed -PermissionsToKeys decrypt,sign

If you want to authorize that same application to read secrets in your vault, run the following cmdlet:

Set-AzureRmKeyVaultAccessPolicy -VaultName 'ContosoKeyVault' -ServicePrincipalName 8f8c4bbd-485b-45fd-98f7-ec6300 -PermissionsToKeys Get

Next steps