Before diving into code, I want to clear up a potential misunderstanding about Azure Vault.

What Azure Vault Is Not

While AzVault can store any key string value, it's not really a credential manager, and is not designed to replace existing solutions to that effect. In an automation scenario, you still have to programatically authenticate to your AzVault to retrieve objects in the first place, which presents a chicken-and-egg scenario. Instead, AzVault presents a way to store a string with several unique attributes that we'll discuss.

Get Started

To get started, we need to install the needed module, and connect to our Azure account in Powershell. We'll use the newer, cross-platform Az module. Be aware, you can't have both the older AzureRM and Az installed side-by-side in Windows Powershell. Refer to this Microsoft article on how to remedy that.

Install-Module Az -Scope CurrentUser -AllowClobber

Connect-AzAccount -Subscription "Visual Studio Enterprise"
Install and Configure the connection to Azure.
NOTE: The -Subscription parameter is only needed if you have more than one subscription, otherwise it can be omitted.

For this example, we're going to store an API token as a secret and use it in a call to our demo API endpoint. The first thing we need to do is create a resource group for our vault to live in. Generally speaking, Microsoft recommends all resources for a particular solution to be in the same resource group and be part of the same resource lifecycle, so take that into account for your project.

New-AzResourceGroup -Name 'Rg-Vault-Demo' -Location 'EastUS' -Force
Create a new resource group

Once it finishes provisioning, let's create a new AzVault.

$VaultParams = @{
    'VaultName' = 'myTestVault'
    'ResourceGroupName' = 'RG-Vault-Demo'
    'Location' = 'EastUS'
}

New-AzKeyVault @VaultParams
Create a new AzVault in our resource group

With our vault created, we're ready to begin adding secrets to it.

Adding a New Secret To a Vault

Let's create our first secret in our newly minted (pun intended) vault.

$SetParams = @{
    VaultName = 'myTestVault'
    Name = 'mySuperSecret'
    SecretValue = (ConvertTo-SecureString -String 'ILikeTurtles' -AsPlainText -Force)
}
Set-AzKeyVaultSecret @SetParams
Create a new secret for our vault

Once that completes, our secret is ready to be used.

Retrieving a Secret From a Vault

Now, let's retrieve the value of our secret for use in our script.

$ApiToken = Get-AzKeyVaultSecret -VaultName 'myTestVault' -Name 'mySuperSecret' |
    Select-Object -ExpandProperty SecretValueText


$IrmParams = @{
    Uri = "https://my.example.com/api/v1/example?t=$ApiToken"
    Method = 'GET'
    UseBasicParsing = $True
}
Invoke-RestMethod @IrmParams
Retrieve a secret from a vault and use it in an API request

That's it, at least at a basic level. If all you want to do is store a secret and retrieve a secret, you're done. However, we've not yet discussed what makes AzVault such a powerful resource.

Diving Deeper: Activation and Expiration Attributes

One super cool thing about AzVault secrets is the concept of activation and expiration dates. Want to go ahead and stage production keys ahead of a go-live date? Set an activation date for when the secret becomes available.

Need to grant temporary access to an external party with a unique access key? Set an expiration date.

I want a representative from Contoso Inc. to be able to make API calls to my endpoint for the next 8 hours only. My API is stateless, so I'm passing a passhash in the query parameters. I've also added some optional tags to help keep my secrets organized.

$SetParams = @{
    VaultName = 'myTestVault'
    Name = "contoso-api-key"
    SecretValue = (ConvertTo-SecureString -String 'myContosoApiToken' -AsPlainText -Force)
    Expires = ((Get-Date).AddHours(8))
    Tags = @{ 'Vendor' = 'Contoso'; 'Access' = 'ReadOnly'}
}
Set-AzKeyVaultSecret @SetParams
Access to this secret will expire in 8 hours

Now that you understand the basics and a few niceties around the AzVault resource, it's time to explore. Happy shelling!