Using Azure Key Vault with Octopus

I recently wrote about extending the functionality of Octopus to integrate with HashiCorp Vault using step templates. Afterwards, several people asked if I plan to create step templates to integrate with other secret managers.

In this post, I walk through a new step template, Azure Key Vault - Retrieve Secrets, which is designed to retrieve secrets from an Azure Key Vault for use in your deployments or runbooks.

Introduction

This post assumes some familiarity with custom step templates and the Octopus Community Library.

In addition, this post doesn't go into great detail about Azure Key Vault concepts or how to set it up. You can learn more by reading the Azure Key Vault basic concepts guide from Microsoft.

The step template in this post retrieves secrets from an Azure Key Vault using the Az.KeyVault PowerShell module. The module must be downloaded and installed on the deployment target or worker before the step can retrieve secrets successfully. The step template has been tested on both Windows and Linux (with PowerShell Core installed).

Authentication

Before you can retrieve secrets from Azure Key Vault, you must authenticate with Azure. In their authentication concepts documentation, Microsoft note:

Authentication with Key Vault works in conjunction with Azure Active Directory (Azure AD), which is responsible for authenticating the identity of any given security principal.

In Octopus, authentication with Azure Key Vault can be achieved with an Azure Account, using a service principal.

In addition to accessing resources in Azure, your service principal may need further permissions configured to access and retrieve secrets stored in Azure Key Vault. To learn more, read the Azure Key Vault RBAC guide on how to provide access to keys, certificates, and secrets with an Azure role-based access control.

Retrieving secrets

The Azure Key Vault - Retrieve Secrets step template retrieves one or more secrets from an Azure Key Vault and creates sensitive output variables for each one retrieved.

For each secret, you can optionally choose to retrieve a specific version, and provide a custom output variable name.

Retrieving a single secret requires:

• An Azure account with permission to access the secret.
• The name of the Azure Key Vault to retrieve the secret from.
• The name of the secret to retrieve.

An advanced feature of the step template offers support for retrieving multiple secrets at once. This requires entering each secret on a new line.

For each secret retrieved, a sensitive output variable is created for use in subsequent steps. By default, only a count of the number of variables created will be shown in the task log. To see the names of the variables in the task log, change the Print output variable names parameter to True.

Step template parameters

The step template uses the following parameters:

• Azure Account: An Azure account with permissions to retrieve secrets from the Azure Key Vault.
• Vault Name: The name of the Azure Key Vault to retrieve secrets from.

• Vault Secrets to retrieve: Specify the names of the Secrets to be returned from Azure Key Vault, in the format: SecretName SecretVersion | OutputVariableName where:

  • SecretName is the name of the Secret to retrieve.
  • SecretVersion is the optional version of the Secret to retrieve. If this value isn't specified, the latest version will be retrieved.
  • OutputVariableName is the optional Octopus output variable name to store the secret's value in. If this value isn't specified, an output name will be generated dynamically.

  Note: Multiple fields can be retrieved by entering each one on a new line.

• Print output variable names: Write out the Octopus output variable names to the task log. Default: False.

• Az PowerShell Module version (optional): If you wish to use a specific version of the Az PowerShell module (rather than the default), enter the version number here. e.g. 5.9.0.

Note: The version specified must exist on the machine.

• Az PowerShell Install Location (optional): If you wish to provide a custom path to the Az PowerShell module (rather than the default), enter the value here.

Note: The Module must exist at the specified location on the machine. This step template will not download the Module.

Using the step

The Azure Key Vault - Retrieve Secrets step is added to deployment and runbook processes in the same way as other steps.

After you've added the step to your process, fill out the parameters in the step:

After you've filled in the parameters, you can execute the step in a runbook or deployment process. On successful execution, any matching secrets will be stored as sensitive output variables. If you've configured your step to print the variable names, they'll appear in the task log:

In subsequent steps, output variables created from matching secrets can be used in your deployment or runbook.

Tip: Remember to replace Azure Key Vault - Retrieve Secrets with the name of your step for any output variable names.

Conclusion

The step template covered in this post demonstrates that it's easy to integrate with Azure Key Vault, and make use of secrets stored there with your Octopus deployments or runbooks.

Happy deployments!

This post was originally published at octopus.com.