> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-platform/use-harness-platform/secrets/secrets-management/azure-key-vault.md).

# Add an Azure Key Vault secret manager

To store and use encrypted secrets (such as access keys) and files, you can add an Azure Key Vault Secret Manager.

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

* Go to [Harness Secret Manager Overview](/harness-platform/use-harness-platform/secrets/secrets-management/harness-secret-manager-overview.md).
* Go to [About Azure Key Vault](https://docs.microsoft.com/en-us/azure/key-vault/general/overview) by Microsoft.
* Go to [Azure Key Vault Basic Concepts](https://docs.microsoft.com/en-us/azure/key-vault/general/basic-concepts).
* Go to [Store authentication credentials](/harness-platform/use-harness-platform/secrets/secrets-management/store-authentication-credentials.md).
* Make sure you have set up an Azure account.
* Make sure you have **View** and **Create/Edit** permissions for secrets.

### Secret manager overview <a href="#secret-manager-overview" id="secret-manager-overview"></a>

For a full overview of how your secrets are used with the Secrets Managers you configure in Harness, go to [Harness Secrets Management Overview](/harness-platform/use-harness-platform/secrets/secrets-management/harness-secret-manager-overview.md) and [Harness Security FAQs](/faqs/harness-security-faqs.md).

Here's a visual summary:

![](/files/AW8VevMtYrluQCYfcEob)

### Limitations <a href="#limitations" id="limitations"></a>

* Key Vault stores and manages secrets as sequences of octets (8-bit bytes), with a maximum size of 25k bytes each. For more information, go to [Azure Key Vault secrets](https://docs.microsoft.com/en-us/azure/key-vault/secrets/about-secrets).

{% hint style="info" %}
**IMPORTANT**

You can **only use Harness Built-in Secret Manager to** [**store authentication credentials**](/harness-platform/use-harness-platform/secrets/secrets-management/store-authentication-credentials.md) for access to the corresponding secret manager.

Storing credentials from one secret manager within another can result in complex and challenging situations. Moreover, these configurations might introduce vulnerabilities, posing potential security risks.

The Harness platform has several validations, including the disabling of self-references.
{% endhint %}

### Create an Azure Reader role <a href="#create-an-azure-reader-role" id="create-an-azure-reader-role"></a>

To enable Harness to later fetch your Azure vaults (in Step 7 below), you must first set up a **Reader** role in Azure. You can do this two ways:

* Azure portal
* PowerShell command

#### Create a Reader role in Azure <a href="#create-a-reader-role-in-azure" id="create-a-reader-role-in-azure"></a>

To create a **Reader** role in the Azure portal UI:

Navigate to Azure's **Subscriptions** page.

![](/files/mAj2kherqTCIRch13Gg6)

Under **Subscription name**, select the subscription where your vaults reside.

![](/files/tA8hshGm5H4Fm7woCVdE)

{% hint style="info" %}
Copy and save the **Subscription ID**. You can paste this value into Harness Manager below at Option: Enter Subscription.Select your **Subscription's Access control (IAM)** property.
{% endhint %}

![](/files/Kdgi3X9UhkvLpZuv5qRJ)

On the resulting **Access control (IAM)** page, select **Add a role assignment**.

In the resulting right pane, set the **Role** to **Reader**.

![](/files/gLShsO21z4W8bEwsXhlF)

Accept the default value: **Assign access to**: **Azure AD user**, **group, or service principal**.

In the **Select** drop-down, select the name of your Azure App registration.

![](/files/uUXxTz4uGcMBmLgsKqZs)

Select **Save**.

On the **Access control (IAM)** page, select the **Role assignments** tab. Make sure your new role now appears under the **Reader** group.

![](/files/bsNMOWqcgvgALnLQnm43)

{% hint style="info" %}
Microsoft Azure's [Manage subscriptions](https://docs.microsoft.com/en-us/azure/cost-management-billing/manage/add-change-subscription-administrator#to-assign-a-user-as-an-administrator) documentation adds details about the above procedure but focuses on the **Administrator** rather than the **Reader** role.
{% endhint %}

#### Create a Reader role using a PowerShell command <a href="#create-a-reader-role-using-a-powershell-command" id="create-a-reader-role-using-a-powershell-command"></a>

You can also create a **Reader** role programmatically via this PowerShell command, after gathering the required parameters:

```
New-AzRoleAssignment -ObjectId <object_id> -RoleDefinitionName "Reader" -Scope /subscriptions/<subscription_id>
```

For details and examples, go to Microsoft Azure's [Add or remove role assignments](https://docs.microsoft.com/en-us/azure/role-based-access-control/role-assignments-powershell#application-at-a-subscription-scope) documentation.

#### Required Permissions for Azure Key Vault Connectors <a href="#required-permissions-for-azure-key-vault-connectors" id="required-permissions-for-azure-key-vault-connectors"></a>

While the **Reader** role enables Harness to list available vaults, it does **not** provide sufficient permissions to **create or update secrets**, which is required during **Test Connection** and certain runtime operations.

To ensure full functionality and a successful Test Connection, you must assign **additional roles** with write access to Key Vault secrets.

| **Role**                  | **Purpose**                            | **Can List Vaults** | **Can Read Secrets** | **Can Write Secrets** | **Passes Test Connection** |
| ------------------------- | -------------------------------------- | ------------------- | -------------------- | --------------------- | -------------------------- |
| Reader                    | Lists vaults only                      | ✅                   | ❌                    | ❌                     | ❌                          |
| Key Vault Secrets User    | Read-only access to secrets            | ✅ (with Reader)     | ✅                    | ❌                     | ❌                          |
| Key Vault Secrets Officer | Read + write access to secrets         | ✅                   | ✅                    | ✅                     | ✅                          |
| Key Vault Administrator   | Full control (incl. policies and RBAC) | ✅                   | ✅                    | ✅                     | ✅                          |

**Least-Privilege Option**

For a secure, least-privilege setup:

* Assign **Key Vault Secrets Officer** to your App Registration or Service Principal at the **vault level**.
* The **Reader** role is not required if Secrets Officer is already granted.

**About the Test Connection Behavior**

When you test the connector in Harness, it attempts to create a **temporary dummy secret** (e.g., `harnessazurevaultvalidation`) to validate permissions. This requires the **`setSecret`** action, which is not included in the Reader or Secrets User roles.

If your organization prefers not to assign write permissions:

* You can use a combination of **Key Vault Secrets User** and **Reader** roles.
* In this case, the **connector test will fail**, but Harness will still be able to **read existing secrets** at runtime, and your pipelines can succeed.

{% hint style="info" %}
**IMPORTANT**

If you choose the read-only approach, it's recommended to validate secret access manually after connector creation.
{% endhint %}

### Add an Azure Key Vault secret manager in Harness <a href="#add-an-azure-key-vault-secret-manager-in-harness" id="add-an-azure-key-vault-secret-manager-in-harness"></a>

You can add an Azure Key Vault connector in account or org or project [scope](/harness-platform/use-harness-platform/platform-access-control.md#permissions-hierarchy-scopes).

This topic explains steps to add an Azure Key Vault connector in the project scope.

To add an Azure Key Vault secret manager:

1. In Harness, select your project.
2. Select **Connectors** and then select **New Connector**.

   ![](/files/wW9WcFKyhiTIFJfieHDV)
3. In **Secret Managers**, select **Azure Key Vault**.

   ![](/files/WpdQm2jZ8LvNu2wC1RuS)
4. Enter a **Name** for the secret manager.

   You can choose to update the **ID** or let it be the same as your secret manager's name. For more information, go to [Entity Identifier Reference](/harness-platform/use-harness-platform/references/entity-identifier-reference.md).
5. Enter **Description** and **Tags** for your secret manager.
6. Select **Continue**.

### Configure details of the Azure Key Vault connector <a href="#configure-details-of-the-azure-key-vault-connector" id="configure-details-of-the-azure-key-vault-connector"></a>

To configure the details for your Azure Key Vault connector, you can do one of the following:

* Specify credentials
* Use the credentials of a specific delegate

#### Specify credentials <a href="#specify-credentials" id="specify-credentials"></a>

1. Select **Specify credentials here**.
2. Enter **Client ID**, **Tenant ID** corresponding to the fields highlighted below in the Azure UI:

   ![](/files/B5G7USxDv8oswIkin02S)

   To provide these values:

   * In Microsoft Entra admin center, navigate to the **Identity** > **Applications** > **App registrations** page, then select your App registration. (For details, go to Microsoft Entra's [Quickstart: Register an application with the Microsoft identity platform](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-v1-add-azure-ad-app).)
   * Copy the **Application (client) ID** for the Azure App registration you are using, and paste it into the Harness dialog's **Client ID** field.
   * Copy the **Directory (tenant) ID** of the Microsoft Entra ID where you created your application, and paste it into the Harness dialog's **Tenant ID** field. (For details, go to Microsoft Azure's [Get values for signing in](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal#get-values-for-signing-in) topic.)
3. In **Subscription**, you can optionally enter your Azure Subscription ID (GUID).

   To find this ID, navigate to Azure's **Subscriptions** page, as outlined above in [Step 1: Create Azure Reader Role](#create-an-azure-reader-role). From the resulting list of subscriptions, copy the **Subscription ID** beside the subscription that contains your vaults.

   ![](/files/tA8hshGm5H4Fm7woCVdE)

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>If you do not enter a GUID, Harness uses the default subscription for the <a href="#setup-delegates">Client ID</a> you've provided above.</p></div>
4. In **Key**, select **Create or Select a Secret**. For detailed steps on creating a new secret, go to [Add Text Secrets](/harness-platform/use-harness-platform/secrets/add-use-text-secrets.md).

   ![](/files/ONxPQ7FOjhkWZ7B4jAPf)

   The secret that you reference here should have the Azure authentication key as the **Secret Value**.

   To create and exchange the azure authentication key, follow these steps:

   1. Navigate to Azure's **Certificates & secrets** page. (For details, go to Microsoft Azure's [Create a new application secret](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-create-service-principal-portal#get-application-id-and-authentication-key) documentation.)
   2. In the resulting page's **Client secrets** section, select **New client secret**.

   ![](/files/voLePmT4JPEzHSynFseJ)

   3. Enter a **Description** and expiration option, then click **Add**.

   ![](/files/wXX6mWrDMouM5iV3jHCJ)

   4. Find your new key in the **Client secrets** section, and copy its value to your clipboard.

   ![](/files/WMeH1gJRDMMel40ZLmyw)

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>This is your only chance to view this key's value in Azure. Store the value somewhere secure, and keep it on your clipboard.</p></div>
5. Optional: Deselect **Purge Secrets**.

   ![](/files/Hld9Hv67CrdCqf3McUUE)

   This option is selected by default and purges deleted secrets instead of soft deleting them. For more information, go to [Purge deleted secret](https://learn.microsoft.com/en-us/rest/api/keyvault/secrets/purge-deleted-secret/purge-deleted-secret) in the Microsoft documentation.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>Purge Protection Handling</strong></p><ul><li>If you have Purge Protection enabled on the Azure side, you must ensure that the <code>enablePurge</code> setting is set to <code>false</code> in the Azure vault connector. This is crucial because, with Purge Protection enabled in Azure, you will not be able to delete secrets if the <code>enablePurge</code> setting is <code>true</code>.</li><li>Purge Protection is a feature in Azure that prevents the permanent deletion of secrets. When enabled, any deletion operation is soft-deleted, and the secret can be recovered within a certain retention period. Setting <code>enablePurge</code> to false ensures compatibility with this feature.</li></ul></div>
6. Select **Continue**.

#### Use the credentials of a specific delegate <a href="#use-the-credentials-of-a-specific-delegate" id="use-the-credentials-of-a-specific-delegate"></a>

1. Select **Use the credentials of a specific Harness Delegate (IAM role, service account, managed identity, etc)**.
2. In **Subscription**, enter your Azure Subscription ID (GUID).
3. In **Environment**, select your environment.
4. In **Authentication**, select one of the following:
   * **System Assigned Managed Identity**: If you select this, you need not provide any Ids.

     ![](/files/WNqkTML0KE60XsjVSCb7)
   * **User Assigned Managed Identity**: If you select this, you need to provide the Application (client) Id in **Client Id**.

     ![](/files/6LbhZHIngyaN5DWYT0DY)

### Set up delegates <a href="#set-up-delegates" id="set-up-delegates"></a>

In **Delegates Setup**, enter [**Selectors**](/harness-platform/use-harness-platform/delegates/delegate/manage-delegates/select-delegates-with-selectors.md#option-select-a-delegate-for-a-connector-using-tags) for specific delegates that you want to allow to connect to this Connector. Select **Continue**.

### Set up vault <a href="#set-up-vault" id="set-up-vault"></a>

Select **Fetch Vault**.

After a slight delay, the **Vault** drop-down list populates with vaults corresponding to your client secret. Select the Vault you want to use.

Select **Save and Continue**.

### Test connection <a href="#test-connection" id="test-connection"></a>

Once the Test Connection succeeds, select **Finish**. You can now see the connector in **Connectors**.

{% hint style="info" %}
**IMPORTANT**

Important: Harness tests connections by generating a fake secret in the Secret Manager or Vault. For the Test Connection to function successfully, make sure you have the Create permission for secrets. The Test Connection fails if you do not have the Create permission. However, Harness still creates the Connector for you. You may use this Connector to read secrets if you have View permissions.
{% endhint %}

### Creating and referencing Azure Vault secrets <a href="#creating-and-referencing-azure-vault-secrets" id="creating-and-referencing-azure-vault-secrets"></a>

To create a new Harness text or file secret in Azure Key Vault, do the following:

1. In **Account/Organization/Project Settings**, select **Secrets**.
2. Select New Secret and then select **Text**, **File**, **SSH Credential**, or **WinRM Credential**. For details on creating **SSH Credential** or **WinRM Credential**, go to [Add SSH keys](/harness-platform/use-harness-platform/secrets/add-use-ssh-secrets.md) or [Add WinRM keys](/harness-platform/use-harness-platform/secrets/add-winrm-keys.md).
3. In **Secrets Manager**, select the Harness Azure Key Vault connector to use.

#### Text secrets <a href="#text-secrets" id="text-secrets"></a>

Select **Inline Secret Value** or **Reference Secret**:

* **Inline Secret Value:** Enter the value for the encrypted text. For Azure Key Vault, you can set an expiry date in **Expires on**.
* **Reference Secret:** Enter the *name* of the existing secret in your **Azure Key Vault**, and then select **Test** to test the reference path. You can also specify the secret's version (for example: `azureSecret/05`).

For details on text secrets, go to [Add and reference text secrets](/harness-platform/use-harness-platform/secrets/add-use-text-secrets.md).

#### File secrets <a href="#file-secrets" id="file-secrets"></a>

For details on file secrets, go to [Add and reference file secrets](/harness-platform/use-harness-platform/secrets/add-file-secrets.md).

### Reference JSON secrets <a href="#reference-json-secrets" id="reference-json-secrets"></a>

Harness allows you to manage the lifecycle of your secrets independently by referencing JSON secrets in the vault.

For example, you can store a secret in vault with the following JSON.

```json
{
  "key1": "value1",
  "key2": {
    "key21": "value21",
    "key22": "value22"
  },
  "key3": {
    "key31": {
      "key311": "value311"
    }
  }
}
```

Here are sample outputs for the respective JSONPath from the above JSON file:

`test-secret` (without any # key)

```json
{
  "key1": "value1",
  "key2": {
    "key21": "value21",
    "key22": "value22"
  },
  "key3": {
    "key31": {
      "key311": "value311"
    }
  }
}
```

`test-secret#key1`

```
"value1"
```

`test-secret#key2`

```json
{
   "key21": "value21",
   "key22": "value22"
}
```

`test-secret#key3`

```json
{
   "key31": {
     "key311": "value311"
  }
}
```

`test-secret#key3.key31`

```json
{
 "key311": "value311"
}
```

`test-secret#key3.key31.key311`

```
  "value311"
```

{% hint style="info" %}
You cannot use a JSON XPath for nested keys in expressions. For example, `<+secrets.getValue("account.YOUR_SECRET_MANAGER://myVault/harness/testpath/example")>`.

Harness provides limited support for keys that include dots. Keys with dots only work when the key is present at first level in the JSON. For example:

```json
{
  "key.abc": "some-value",
  "key": {
    "nested.key1": "some-value"
  },
  "key.pqr": {
    "nestedKey": "some-value"
  },
  "pqr.xyz": "some-value",
  "pqr": {
    "xyz": "some-nested-value"
  }
}
```

Here are sample outputs for the respective JSONPath from the above JSON file:

* `/path/to/secret#key.abc` returns `some-value`.
* `/path/to/secret#key.pqr` returns `{"nestedKey": "some-value"}`.
* `/path/to/secret#key.nested.key1` and `key.pqr.nestedKey` are not supported.
* `/path/to/secret#pqr.xyz` returns `some-nested-value` and not `some-value`. (Hierarchical paths take precedence over keys with dots.)
  {% endhint %}

{% hint style="warning" %}
Harness does not recommend using keys that include dots and might deprecate support in future releases.
{% endhint %}