Skip to main content

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​

Secret manager overview​

For a full overview of how your secrets are used with the Secrets Managers you configure in Harness, go to Harness Secrets Management Overview and Harness Security FAQs.

Here's a visual summary:

Limitations​

  • 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.
important

You can only use Harness Built-in Secret Manager to store authentication credentials 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.

Create an Azure Reader role​

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​

To create a Reader role in the Azure portal UI:

Navigate to Azure's Subscriptions page.

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

tip

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.

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

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

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.

Select Save.

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

note

Microsoft Azure's Manage subscriptions documentation adds details about the above procedure but focuses on the Administrator rather than the Reader role.

Create a Reader role using a PowerShell command​

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 documentation.

Add an Azure Key Vault secret manager in Harness​

You can add an Azure Key Vault connector in account or org or project scope.

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.

  3. In Secret Managers, select Azure Key Vault.

  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.

  5. Enter Description and Tags for your secret manager.

  6. Select Continue.

Configure details of the Azure Key Vault connector​

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​

  1. Select Specify credentials here.

  2. Enter Client ID, Tenant ID corresponding to the fields highlighted below in the Azure UI:

    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.)
    • 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 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. From the resulting list of subscriptions, copy the Subscription ID beside the subscription that contains your vaults.

    note

    If you do not enter a GUID, Harness uses the default subscription for the Client ID you've provided above.

  4. In Key, select Create or Select a Secret. For detailed steps on creating a new secret, go to Add Text Secrets.

    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 documentation.)
    2. In the resulting page’s Client secrets section, select New client secret.

    1. Enter a Description and expiration option, then click Add.

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

    note

    This is your only chance to view this key's value in Azure. Store the value somewhere secure, and keep it on your clipboard.

  5. Optional: Deselect Purge Secrets.

    This option is selected by default and purges deleted secrets instead of soft deleting them. For more information, go to Purge deleted secret in the Microsoft documentation.

  6. Select Continue.

Use the credentials of a specific delegate​

  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.

    • User Assigned Managed Identity: If you select this, you need to provide the Application (client) Id in Client Id.

Set up delegates​

In Delegates Setup, enter Selectors for specific delegates that you want to allow to connect to this Connector. Select Continue.

Set up vault​

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​

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

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.

Creating and referencing Azure Vault secrets​

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 or Add WinRM keys.
  3. In Secrets Manager, select the Harness Azure Key Vault connector to use.

Text secrets​

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.

File secrets​

For details on file secrets, go to Add and reference file secrets.

Reference JSON secrets​

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.

{
  "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)

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

test-secret#key1

"value1"

test-secret#key2

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

test-secret#key3

{
  "key31": {
    "key311": "value311"
 }
}

test-secret#key3.key31

{
  "key311": "value311"
}

test-secret#key3.key31.key311

 "value311"
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:

{
  "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.)
warning

Harness does not recommend using keys that include dots and might deprecate support in future releases.