Use Azure Key Vault secrets in Azure Pipelines

Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019

Azure Key Vault enables developers to securely store and manage secrets such as API keys, credentials or certificates. Azure Key Vault service supports two types of containers: vaults and managed HSM (hardware security module) pools. Vaults support storing software and HSM-backed keys, secrets, and certificates, while managed HSM pools only support HSM-backed keys.

In this tutorial, you will learn how to:

  • Create an Azure Key Vault using Azure CLI
  • Add a secret and configure access to Azure key vault
  • Use secrets in your pipeline

Prerequisites

Create an Azure Key Vault

Sign in to the Azure Portal, and then select the Cloud Shell button in the upper-right corner.

  1. If you have more than one Azure subscription associated with your account, use the command below to specify a default subscription. You can use az account list to generate a list of your subscriptions.

    az account set --subscription <your_subscription_name_or_ID>
    
  2. Set your default Azure region. You can use az account list-locations to generate a list of available regions.

    az config set defaults.location=<your_region>
    

    For example, this command will select the westus2 region:

    az config set defaults.location=westus2
    
  3. Create a new resource group. A resource group is a container that holds related resources for an Azure solution.

    az group create --name <your-resource-group>
    
  4. Create a new key vault.

    az keyvault create \
      --name <your-key-vault> \
      --resource-group <your-resource-group>
    
  5. Create a new secret in your Azure key vault.

    az keyvault secret set \
      --name "Password" \
      --value "mysecretpassword" \
      --vault-name <your-key-vault-name>
    

Create a project

  1. Sign in to your Azure DevOps organization.

  2. If you don't have any projects in your organization yet, select Create a project to get started. Otherwise, select New project in the upper-right corner.

Create a repo

We will use YAML to create our pipeline but first we need to create a new repo.

  1. Sign in to your Azure DevOps organization and navigate to your project.

  2. Select Repos, and then select Initialize to initialize a new repo with a README.

    A screenshot showing how to initialize a repository.

Create a new pipeline

  1. Select Pipelines, and then select New Pipeline.

  2. Select Azure Repos Git (YAML).

    A screenshot showing how to select Azure Repos source control.

  3. Select the repository you created in the previous step.

  4. Select the Starter pipeline template.

  5. The default pipeline will include a few scripts that run echo commands. Those are not needed so we can delete them. Your new YAML file should look like this:

    trigger:
    - main
    
    pool:
        vmImage: 'ubuntu-latest'
    
    steps:
    
  6. Select Show assistant to expand the assistant panel. This panel provides convenient and searchable list of pipeline tasks.

    A screenshot showing how to access the task assistant panel.

  7. Search for vault and select the Azure Key Vault task.

    A screenshot showing how to search for the Azure Key Vault task.

  8. Select your Azure subscription and then select Authorize. Select your Key vault from the dropdown menu, and then select Add to add the task to your YAML pipeline.

    A screenshot showing how to configure the Azure Key Vault task.

    Note

    The Make secrets available to whole job feature is not supported in Azure DevOps Server 2019 and 2020.

  9. Your YAML file should look like the following:

    trigger:
    - main
    
    pool:
      vmImage: ubuntu-latest
    
    steps:
    - task: AzureKeyVault@2
      inputs:
        azureSubscription: 'Your-Azure-Subscription'
        KeyVaultName: 'Your-Key-Vault-Name'
        SecretsFilter: '*'
        RunAsPreJob: false
    
    - task: CmdLine@2
      inputs:
        script: 'echo $(Your-Secret-Name) > secret.txt'
    
    - task: CopyFiles@2
      inputs:
        Contents: secret.txt
        targetFolder: '$(Build.ArtifactStagingDirectory)'
    
    - task: PublishBuildArtifacts@1
      inputs:
        PathtoPublish: '$(Build.ArtifactStagingDirectory)'
        ArtifactName: 'drop'
        publishLocation: 'Container'
    

Don't save or queue your pipeline just yet. We must first give our pipeline the right permissions to access Azure Key Vault. Keep your browser tab open, we will resume the remaining steps once we set up the key vault permissions.

Set up Azure Key Vault access policies

In order to access our Azure Key Vault, we must first set up a service principal to give access to Azure Pipelines. Follow this guide to create your service principal and then proceed with the next steps in this section.

  1. Navigate to Azure portal.

  2. Use the search bar to search for the key vault you created earlier.

    A screenshot showing how to search for your Azure Key Vault.

  3. Under Settings Select Access policies.

  4. Select Add Access Policy to add a new policy.

  5. For Secret permissions, select Get and List.

  6. Select the option to select a service principal and search for the one you created in the beginning of this section. A security principal is an object that represents a user, group, service, or application that's requesting access to Azure resources.

  7. Select Add to create the access policy, then select Save when you are done.

Run and review the pipeline

  1. Return to the previous tab where we left off.

  2. Select Save, and then select Save again to commit your changes and trigger the pipeline. You may be asked to allow the pipeline access to Azure resources, if prompted select Allow. You will only have to approve your pipeline once.

  3. Select the CmdLine task to view the logs.

    A screenshot showing the command-line task logs.

  4. Return to pipeline summary and select the published artifact.

    A screenshot showing the pipeline summary and the published artifact.

  5. Select the secret.txt artifact to open it.

    A screenshot showing how to open the published artifact.

  6. The text file should contain our secret: mysecretpassword.

Warning

This tutorial is for educational purposes only. For security best practices and how to safely work with secrets, see Manage secrets in your server apps with Azure Key Vault.

Clean up resources

Follow the steps below to delete the resources you created:

  1. If you created a new organization to host your project, see how to delete your organization, otherwise delete your project.

  2. All Azure resources created during this tutorial are hosted under a single resource group PipelinesKeyVaultResourceGroup. Run the following command to delete the resource group and all of its resources.

    az group delete --name PipelinesKeyVaultResourceGroup
    

FAQ

Q: I'm getting the following error: "the user or group does not have secrets list permission" what should I do?

A: If you encounter an error indicating that the user or group does not have secrets list permission on key vault, run the following commands to authorize your application to access the key or secret in the Azure Key Vault:

$ErrorActionPreference="Stop";
$Credential = Get-Credential;
Connect-AzAccount -SubscriptionId <YOUR_SUBSCRIPTION_ID> -Credential $Credential;
$spn=(Get-AzureRmADServicePrincipal -SPN <YOUR_SERVICE_PRINCIPAL_ID>);
$spnObjectId=$spn.Id;
Set-AzureRmKeyVaultAccessPolicy -VaultName key-vault-tutorial -ObjectId $spnObjectId -PermissionsToSecrets get,list;

Next steps