Skip to content

Latest commit

 

History

History
246 lines (156 loc) · 10.3 KB

azure-key-vault.md

File metadata and controls

246 lines (156 loc) · 10.3 KB
title description ms.topic ms.date ms.custom monikerRange recommendations
Use Azure Key Vault secrets in Azure Pipelines
How to create Azure Key vaults, store secrets, and use those secrets in your Azure Pipelines
tutorial
02/16/2021
contperf-fy21q3, devx-track-azurecli
>= azure-devops-2019
true

Use Azure Key Vault secrets in Azure Pipelines

Azure Pipelines | Azure DevOps Server 2020 | Azure DevOps Server 2019

Note

This article will guide you through working with Azure key vault in your pipeline. if you want to set secret variables or reference variable groups, see Define variables for more details.

Azure Key Vault allows users to securely store, manage, and access sensitive information. Secrets can be API keys, credentials, certificates, etc.

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:

[!div class="checklist"]

  • 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

Azure key vaults can be created and managed through the Azure portal or Azure CLI. We will use Azure CLI in this tutorial to create our Azure Key vault.

[!INCLUDE include]

  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. Run the following command to 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. Run the following command to 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. Run the following command to create a new key vault.

    az keyvault create \
  --name <your-key-vault> \
  --resource-group <your-resource-group>

  5. Run the following command to create a new secret in your key vault. Secrets are stored as a key value pair. In the example below, Password is the key and mysecretpassword is the value.

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

Create a project

Sign in to Azure Pipelines. Your browser will then navigate to https://dev.azure.com/your-organization-name and displays your Azure DevOps dashboard.

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

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. Go to Repos, and then select Initialize to initialize a new repo with a README.

    :::image type="content" border="false" source="media/azure-key-vault/initialize-repo.png" alt-text="Creating the repo":::

Create a new pipeline

  1. Go to Pipelines, and then select New Pipeline.

  2. Select Azure Repos Git.

    :::image type="content" border="false" source="media/azure-key-vault/create-pipeline.png" alt-text="Creating the pipeline":::

  3. Select the repo you created earlier. It should have the same name as your Azure DevOps project.

  4. Select Starter pipeline.

  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 will now 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.

    :::image type="content" border="false" source="media/azure-key-vault/show-assistant.png" alt-text="Showing the pipeline assistant":::

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

    :::image type="content" border="false" source="media/azure-key-vault/azure-key-vault-task.png" alt-text="Selecting the Azure Key Vault task":::

  8. Select and authorize your Azure subscription then select the Azure key vault task and select Add to add it to your pipeline. This task allows the pipeline to connect to your Azure Key Vault and retrieve secrets to use as pipeline variables.

    [!NOTE] The Make secrets available to whole job feature is not currently supported in Azure DevOps Server 2019 and 2020.

    :::image type="content" border="false" source="media/azure-key-vault/configure-azure-key-vault-task.png" alt-text="Configuring the Azure Key Vault task":::

  9. Your YAML file should look something 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'

  10. Do not save or run 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. Go to Azure portal.

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

    :::image type="content" border="false" source="media/azure-key-vault/search-azure-key-vault.png" alt-text="Searching for 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 Save.

Run and review the pipeline

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

  2. Select Save then Save again to commit your changes and trigger the pipeline.

    [!NOTE] 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 job to view the logs.

    :::image type="content" border="false" source="media/azure-key-vault/command-line-task.png" alt-text="Reviewing the command-line task":::

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

    :::image type="content" border="false" source="media/azure-key-vault/pipeline-summary.png" alt-text="The pipeline summary":::

  5. Under Job select the secret.txt file to open it.

    :::image type="content" border="false" source="media/azure-key-vault/view-artifact.png" alt-text="Viewing the secret in the artifact":::

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

Warning

This tutorial is for 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.

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";
Login-AzureRmAccount -SubscriptionId your-subscription-ID;
$spn=(Get-AzureRmADServicePrincipal -SPN service-principal-ID);
$spnObjectId=$spn.Id;
Set-AzureRmKeyVaultAccessPolicy -VaultName key-vault-tutorial -ObjectId $spnObjectId -PermissionsToSecrets get,list;

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

Next steps

[!div class="nextstepaction"] Artifacts in Azure Pipelines Publish and download artifacts in Azure Pipelines Release artifacts and artifact sources