Azure Key Vault task
Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019
Overview
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.
Prerequisites
The task has the following Prerequisites:
- An Azure subscription linked to Azure Pipelines or Team Foundation Server using the Azure Resource Manager service connection.
- An Azure Key Vault containing the secrets.
You can create a key vault:
- In the Azure portal
- By using Azure PowerShell
- By using the Azure CLI
Add secrets to a key vault:
By using the PowerShell cmdlet Set-AzureKeyVaultSecret. 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 Pa$$w0rd, type:
az keyvault secret set --vault-name 'ContosoKeyVault' --name 'SQLPassword' --value 'Pa$$w0rd'
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.
YAML snippet
# Azure Key Vault
# Download Azure Key Vault secrets
- task: AzureKeyVault@2
inputs:
connectedServiceName: # Azure subscription
keyVaultName: # Name of existing key vault
secretsFilter: '*' # Downloads all secrets for the key vault
runAsPreJob: true # Runs before the job starts
Arguments
Parameter | Description |
---|---|
connectedServiceName Azure Subscription |
(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 |
(Required) Select the name of the Azure Key Vault from which the secrets will be downloaded. |
secretsFilter Secrets filter |
(Required) A comma-separated list of secret names to be downloaded or * to download all secrets from the selected key vault. Default value: * |
runAsPreJob Make secrets available to whole job |
(Required) Run the task before job execution begins. Exposes secrets to all tasks in the job, not just tasks that follow this one. Default value: false |
Parameter | Description |
---|---|
connectedServiceName Azure Subscription |
(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 |
(Required) Select the name of the Azure Key Vault from which the secrets will be downloaded. |
secretsFilter Secrets filter |
(Required) A comma-separated list of secret names to be downloaded or * to download all secrets from the selected key vault. Default value: * |
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.
Open source
This task is open source on GitHub. Feedback and contributions are welcome.
FAQ
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.
Do I need an agent?
You need at least one agent to run your build or release.
I'm having problems. How can I troubleshoot them?
See Troubleshoot Build and Release.
I can't select a default agent pool and I can't queue my build or release. How do I fix this?
See Agent pools.
My NuGet push task is failing with the following error: "Error: unable to get local issuer certificate". How can I fix this?
This can be fixed by adding a trusted root certificate. You can either add the NODE_EXTRA_CA_CERTS=file
environment variable to your build agent, or you can add the NODE.EXTRA.CA.CERTS=file
task variable in your pipeline. See Node.js documentation for more details about this variable. See Set variables in a pipeline for instructions on setting a variable in your pipeline.
I can't connect with Key Vault from Azure DevOps
This happens when the Key Vault firewall isn't properly configured. Make sure that the agent pool and the Azure DevOps Service itself can access the key vault. To do this, ensure that Azure DevOps IP Ranges for your Org's region are allowed, as well as agent IP ranges for Microsoft-hosted agents are allowed if using MS Hosted agents.
Feedback
Submit and view feedback for