Azure Key Vault

The Azure Key Vault destination enables Vault to sync and unsync secrets of your choosing into an external Azure account. When configured, Vault will actively maintain the state of each externally-synced secret in realtime. This includes sending new secrets, updating existing secret values, and removing secrets when they either get dissociated from the destination or deleted from Vault.

Prerequisites:

• Ability to read or create KVv2 secrets
• Ability to create Azure AD user credentials with access to an Azure Key Vault
• Ability to create sync destinations and associations on your Vault server

Setup

1. If you do not already have an Azure Key Vault instance, navigate to the Azure Portal to create a new Key Vault.

2. A service principal with a client id and client secret will be needed to configure Azure Key Vault as a sync destination. This guide will walk you through creating the service principal.

3. Once the service principal is created, the next step is to grant the service principal access to Azure Key Vault. To quickly get started, we recommend using the "Key Vault Secrets Officer" built-in role, which gives sufficient access to manage secrets. For more information, see the Permissions section.

1. Configure a sync destination with the service principal credentials and Key Vault URI created in the previous steps.

   $ vault write sys/sync/destinations/azure-kv/my-azure-1 \
       key_vault_uri="$KEY_VAULT_URI" \
       client_id="$CLIENT_ID" \
       client_secret="$CLIENT_SECRET" \
       tenant_id="$TENANT_ID"
   

   Copy

   Output:

   Key                   Value
   ---                   -----
   connection_details    map[client_id:123 client_secret:***** key_vault_uri:***** tenant_id:123]
   name                  my-azure-1
   type                  azure-kv
   

Usage

1. If you do not already have a KVv2 secret to sync, mount a new KVv2 secrets engine.

   $ vault secrets enable -path='my-kv' kv-v2
   

   Copy

   Output:

   Success! Enabled the kv-v2 secrets engine at: my-kv/
   

2. Create secrets you wish to sync with a target Azure Key Vault.

   $ vault kv put -mount='my-kv' my-secret foo='bar'
   

   Copy

   Output:

   ==== Secret Path ====
   my-kv/data/my-secret
   
   ======= Metadata =======
   Key                Value
   ---                -----
   created_time       2023-09-19T13:17:23.395109Z
   custom_metadata    <nil>
   deletion_time      n/a
   destroyed          false
   version            1
   

3. Create an association between the destination and a secret to synchronize.

   $ vault write sys/sync/destinations/azure-kv/my-azure-1/associations/set \
       mount='my-kv' \
       secret_name='my-secret'
   

   Copy

   Output:

   Key                   Value
   ---                   -----
   associated_secrets    map[kv_7532a8b4/my-secret:map[accessor:kv_7532a8b4 secret_name:my-secret sync_status:SYNCED updated_at:2023-09-21T13:53:24.839885-07:00]]
   store_name            my-azure-1
   store_type            azure-kv
   

4. Navigate to Azure Key Vault in the Azure portal to confirm your secret was successfully created.

Moving forward, any modification on the Vault secret will be propagated in near real time to its Azure Key Vault counterpart. Creating a new secret version in Vault will create a new version in Azure Key Vault. Deleting the secret or the association in Vault will delete the secret in your Azure Key Vault as well.

Permissions

For a more minimal set of permissions, you can create a custom role using the following JSON role definition. Be sure to replace the subscription id placeholder.

{
  "properties": {
    "roleName": "Key Vault Secrets Reader Writer",
    "description": "Custom role for reading and updating Azure Key Vault secrets.",
    "permissions": [
      {
        "actions": [
          "Microsoft.KeyVault/vaults/secrets/read",
          "Microsoft.KeyVault/vaults/secrets/write"
        ],
        "notActions": [],
        "dataActions": [
          "Microsoft.KeyVault/vaults/secrets/delete",
          "Microsoft.KeyVault/vaults/secrets/backup/action",
          "Microsoft.KeyVault/vaults/secrets/purge/action",
          "Microsoft.KeyVault/vaults/secrets/recover/action",
          "Microsoft.KeyVault/vaults/secrets/restore/action",
          "Microsoft.KeyVault/vaults/secrets/readMetadata/action",
          "Microsoft.KeyVault/vaults/secrets/getSecret/action",
          "Microsoft.KeyVault/vaults/secrets/setSecret/action"
        ],
        "notDataActions": []
      }
    ],
    "assignableScopes": [
      "/subscriptions/{subscriptionId}/"
    ]
  }
}

API

Please see the secrets sync API for more details.