Skip to content

Configuring a key vault for Azure agent

Public preview

The Azure agent requires access to an Azure key vault. The deployment template will automatically create a key vault in the same resource group as the agent, but if you prefer, the agent can reference a different key vault you have previously created. This other key vault may be in the same or a different resource group. You might want to reference a key vault in a different resource group so that you can have multiple agents referencing the same secrets, for example.

This topic describes the configuration steps you will need to perform in order to use an existing key vault. You don't need to follow these steps if you are allowing the ARM template install to create a new key vault.


To reference a different key vault, ensure the key vault already exists in the desired resource group. Before initiating the deployment process, you will need the following details:

  • Name of the key vault that you want to use.
  • Name of the resource group where the key vault resides.
  • An Azure subscription with appropriate permissions to manage access control.
  • Access to both the resource group containing the key vault and the resource group where the identity resides.

We assume an understanding of basic Azure Identity and Access Management (IAM) concepts if you intend to follow this process.

Grant key vault access

To use an existing key vault located in a different resource group, you first need to ensure appropriate role permissions have been granted to the identity requiring access. This requires the Key Vault Secrets User role to be granted to the relevant identity via the Azure portal, as follows.

Determine the identity that requires access to the key vault. If you aren't familiar with the concept of identities, read What are managed identities for Azure resources? or Assign a managed identity access to a resource by using the Azure portal in the Microsoft documentation.

You have two options:

  • Create a managed identity in the Azure portal that you then assign to the resource group where the agent will be deployed, and then deploy the agent as described in Agent installation using an ARM template.
  • Deploy the agent as described in Agent installation using an ARM template without first granting the access. This will automatically create a managed identity with ${resourcePrefix}-identity as a default name. Note that the deployment will initially fail due to missing permissions. You will then have to perform the following steps, and then redeploy the agent in the Deployments section of the resource group where you initially attempt to deploy.

To add secrets in the Azure agent's key vault, an Azure user needs to be added as an administrator to the key vault.

To assign the identity:

  1. Log in to the Azure portal.
  2. Click Key vaults and click the name of the key vault you want to use.
  3. Click Access control (IAM).
  4. In the Access Control (IAM) panel, click + Add then click Add role assignment to create a new role assignment.
  5. Search for the role Key Vault Administrator, click it to select it, then click Next.
  6. Click + Select members, search for the identity requiring access to the key vault, click it to select it, then click Select.
  7. Click Review + assign.

If you have the key vault firewall enabled, you also need to allow the local IP address that you will use to add secrets to the key vault. To do this:

  1. Log in to the Azure portal.
  2. Click Key vaults and click the name of the key vault you want to use.
  3. Click Networking.
  4. Click the Firewalls and virtual networks tab.
  5. Under Allow access from, click Selected networks.
  6. Click + Add existing virtual networks.
  7. Select the subscription, virtual networks, and subnets that you want to allow access to this key vault.
  8. Click Save.

Verify access

To verify that access has been successfully granted, you can:

  • Use the identity that was granted access to retrieve secrets from the key vault.
  • Attempt to retrieve secrets programmatically or via the Azure portal using the granted identity's credentials.
  • Review access logs or audit logs to confirm successful access attempts.