Edit

Share via

AzureKeyVault@2 - Azure Key Vault v2 task

  • Article

Use this task to download secrets, such as authentication keys, storage account keys, data encryption keys, .PFX files, and passwords from an Azure Key Vault instance. The task can be used to fetch the latest values of all or a subset of secrets from the vault and set them as variables that can be used in subsequent tasks of a pipeline. The task is Node-based and works with agents on Linux, macOS, and Windows.

Syntax

# Azure Key Vault v2
# Download Azure Key Vault secrets.
- task: AzureKeyVault@2
  inputs:
    azureSubscription: # string. Alias: ConnectedServiceName. Required. Azure subscription. 
    KeyVaultName: # string. Required. Key vault. 
    SecretsFilter: '*' # string. Required. Secrets filter. Default: *.
    #RunAsPreJob: false # boolean. Make secrets available to whole job. Default: false.

Inputs

azureSubscription - Azure subscription
Input alias: ConnectedServiceName. string. Required.

Select the service connection for the Azure subscription containing the Azure Key Vault instance, or create a new connection. Learn more.


KeyVaultName - Key vault
string. Required.

The name of the Azure Key Vault that contains the secrets to download.


SecretsFilter - Secrets filter
string. Required. Default value: *.

Downloads secret names according to the entered value. The value can be the default value to download all secrets from the selected key vault, or a comma-separated list of secret names.


RunAsPreJob - Make secrets available to whole job
boolean. Default value: false.

Runs the task before the job execution begins. Exposes secrets to all tasks in the job, not just tasks that follow this one.


Task control options

All tasks have control options in addition to their task inputs. For more information, see Control options and common task properties.

Output variables

None.

Remarks

What's new in Version 2.0: Added support for %3B, %5D in secrets.

Use this task to download secrets, such as authentication keys, storage account keys, data encryption keys, .PFX files, and passwords from an Azure Key Vault instance. The task can be used to fetch the latest values of all or a subset of secrets from the vault and set them as variables that can be used in subsequent tasks of a pipeline. The task is Node-based and works with agents on Linux, macOS, and Windows.

I get a forbidden error on pipelines at the point of getting credentials from Azure Key Vault

This occurs if the required permissions are missing in the Azure key vault. To resolve the issue, add an access policy with the correct permissions.

Prerequisites

The task has the following Prerequisites:

You can create a key vault:

Add secrets to a key vault:

  • By using the PowerShell cmdlet Set-AzKeyVaultSecret. If the secret does not exist, this cmdlet creates it. If the secret already exists, this cmdlet creates a new version of that secret.

  • By using the Azure CLI. To add a secret to a key vault, for example a secret named SQLPassword with the value PlaceholderPassword, type:

    az keyvault secret set --vault-name 'ContosoKeyVault' --name 'SQLPassword' --value 'PlaceholderPassword'

When you want to access secrets:

  • Ensure the Azure service connection has at least Get and List permissions on the vault. You can set these permissions in the Azure portal:

    • Open the Settings blade for the vault, choose Access policies, then Add new.
    • In the Add access policy blade, choose Select principal and select the service principal for your client account.
    • In the Add access policy blade, choose Secret permissions and ensure that Get and List are checked (ticked).
    • Choose OK to save the changes.

Note

If you're using a Microsoft-hosted agent, you must add the IP range of the Microsoft-hosted agent to your firewall. Get the weekly list of IP ranges from the weekly JSON file, which is published every Wednesday. The new IP ranges become effective the following Monday. For more information, see Microsoft-hosted agents. To find the IP ranges that are required for your Azure DevOps organization, learn how to identify the possible IP ranges for Microsoft-hosted agents.

Note

Values are retrieved as strings. For example, if there is a secret named connectionString, a task variable connectionString is created with the latest value of the respective secret fetched from Azure key vault. This variable is then available in subsequent tasks.

If the value fetched from the vault is a certificate (for example, a PFX file), the task variable will contain the contents of the PFX in string format. You can use the following PowerShell code to retrieve the PFX file from the task variable:

$kvSecretBytes = [System.Convert]::FromBase64String("$(PfxSecret)")
$certCollection = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2Collection
$certCollection.Import($kvSecretBytes,$null,[System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]::Exportable)

If the certificate file will be stored locally on the machine, it is good practice to encrypt it with a password:

 #Get the file created
$password = 'your password'
$protectedCertificateBytes = $certCollection.Export([System.Security.Cryptography.X509Certificates.X509ContentType]::Pkcs12, $password)
$pfxPath = [Environment]::GetFolderPath("Desktop") + "\MyCert.pfx"
[System.IO.File]::WriteAllBytes($pfxPath, $protectedCertificateBytes)

For more information, see Get started with Azure Key Vault certificates.

Examples

Requirements

Requirement Description
Pipeline types YAML, Classic build, Classic release
Runs on Agent, DeploymentGroup
Demands None
Capabilities This task does not satisfy any demands for subsequent tasks in the job.
Command restrictions Any
Settable variables Any
Agent version 2.182.1 or greater
Task category Deploy