vault page title Secrets sync Use secrets sync feature to automatically sync Vault managed secrets with external destinations to centralize secrets lifecycle management layout docs Secrets sync EnterpriseAlert product vault

Answer:
---
layout: docs
page_title: Secrets sync
description: >-
  Use secrets sync feature to automatically sync Vault-managed secrets with external destinations to centralize secrets lifecycle management.
---

# Secrets sync

<EnterpriseAlert product="vault" />

In certain circumstances, fetching secrets directly from Vault is impossible or impractical. To help with this challenge,
Vault can maintain a one-way sync for KVv2 secrets into various destinations that are easier to access for some clients.
With this, Vault remains the system of records but can cache a subset of secrets on various external systems acting as
trusted last-mile delivery systems.

A secret that is associated from a Vault KVv2 Secrets Engine into an external destination is actively managed by a continuous
process. If the secret value is updated in Vault, the secret is updated in the destination as well. If the secret is deleted
from Vault, it is deleted on the external system as well. This process is asynchronous and event-based. Vault propagates
modifications into the proper destinations automatically in a handful of seconds.

<Note title="Not related to HCP Vault Secrets">

  Secrets sync is a Vault Enterprise feature. For information on secrets sync
  with [HCP Vault Secrets](/hcp/docs/vault-secrets), refer to the HashiCorp Cloud
  Platform documentation for
  [Vault Secrets integrations](/hcp/docs/vault-secrets/integrations).

</Note>

## Activating the feature

The secrets sync feature requires manual activation through a one-time trigger. If a sync-related endpoint is called prior to
activation, an error response will be received indicating that the feature has not been activated yet. Be sure to understand the
potential [client count impacts](#client-counts) of using secrets sync before proceeding.

Activating the feature can be done through one of several methods:

  1. Activation directly through the UI.

  1. Acitvation through the CLI:

    ```shell-session
    vault write -f sys/activation-flags/secrets-sync/activate
    ```

  1. Activation through a POST or PUT request:

    ```shell-session
    $ curl \
      --request PUT \
      --header "X-Vault-Token: ..." \
      http://127.0.0.1:8200/v1/sys/activation-flags/secrets-sync/activate
    ```

## Destinations

Secrets can be synced into various external systems, called destinations. The supported destinations are:
* [AWS Secrets Manager](/vault/docs/sync/awssm)
* [Azure Key Vault](/vault/docs/sync/azurekv)
* [GCP Secret Manager](/vault/docs/sync/gcpsm)
* [GitHub Repository Actions](/vault/docs/sync/github)
* [Vercel Projects](/vault/docs/sync/vercelproject)

## Associations

Syncing a secret into one of the external systems is done by creating a connection between it and a destination, which is
called an association. These associations are created via Vault's API by adding a KVv2 secret target to one of the configured
destinations. Each association keeps track of that secret's current sync status, the timestamp of its last status change, and
the error code of the last sync or unsync operation if it failed. Each destination can have any number of secret associations.

## Sync statuses

There are several sync statuses which relay information about the outcome of the latest sync
operation to have occurred on that secret. The status information is stored inside each
association object returned by the endpoint and, upon failure, includes an error code describing the cause of the failure.

| Status                   | Description                                                                                |
|:-------------------------|:------------------------------------------------------------------------------------------------|
| `UNKNOWN`                | Vault is unable to determine the current state of the secret in regard to the external service. |
| `PENDING`                | An operation is queued for that secret and has not been processed yet.                          |
| `SYNCED`                 | The sync operation was successful and sent the secret to the external destination.              |
| `UNSYNCED`               | The unsync operation was successful and removed the secret from the external destination.       |
| `INTERNAL_VAULT_ERROR`   | The operation failed due to an issue internal to Vault.                                         |
| `CLIENT_SIDE_ERROR`      | The operation failed due to a configuration error such as invalid privileges.                   |
| `EXTERNAL_SERVICE_ERROR` | The operation failed due to an issue with the external service such as a temporary downtime.    |

## Name template

By default, the name of synced secrets follows this format: `vault/<accessor>/<secret-path>`. The casing and delimiters
may change as they are normalized according to the valid character set of each destination type. This pattern was chosen to
prevent accidental name collisions and to clearly identify where the secret is coming from.

Every destination allows you to customize this name pattern by configuring a `secret_name_template` field to best suit
individual use cases. The templates use a subset of the go-template syntax for extra flexibility.

The following placeholders are available:

| Placeholder         | Description                                                                                |
|:--------------------|:------------------------------------------------------------------------------------------------------------|
| `DestinationType`   | The type of the destination, e.g. "aws-sm"                                                                  |
| `DestinationName`   | The name of the destination                                                                                |
| `NamespacePath`     | The full namespace path where the secret being synced is located                                            |
| `NamespaceBaseName` | The segment following the last `/` character from the full path                                             |
| `NamespaceID`       | The internal unique ID identifying the namespace, e.g. `RQegM`                                              |
| `MountPath`         | The full mount path where the secret being synced is located                                                |
| `MountBaseName`     | The segment following the last `/` character from the full path                                             |
| `MountAccessor`     | The internal unique ID identifying the mount, e.g. `kv_1234`                                                |
| `SecretPath`        | The full secret path                                                                                |
| `SecretBaseName`    | The segment following the last `/` character from the full path                                             |
| `SecretKey`         | The individual secret key being synced, only available if the destination uses the `secret-key` granularity |

Let's assume we want to sync the following secret:

  <CodeBlockConfig hideClipboard>

    $ VAULT_NAMESPACE=ns1/ns2 vault kv get -mount=path/to/kv1 path/to/secret1

    ========== Secret Path ==========
    path/to/kv1/data/path/to/secret1

    ======= Metadata =======
    (...)

    === Data ===
    Key    Value
    ---    -----
    foo    bar

  </CodeBlockConfig>

Let's look at some name template examples and the resulting secret name at the sync destination.

| Name template                            | Result                 |
|:-----------------------------------------|:-----------------------|
| prefix-                 | prefix-path/to/secret1 |
|        | SECRET1                |
| _    | kv_1234_foo            |
|  | path_to_secret1        |

Name templates can be updated. The new template is only effective for new secrets associated with the destination and does
not affect the secrets synced with the previous template. It is possible to update an association to force a recreate operation.
The secret synced with the old template will be deleted and a new secret using the new template version will be synced.

## Custom tags

A destination can also have custom tags so that every secret associated to it that is synced will share that same set of tags.
Additionally, a default tag value of `hashicorp:vault` is used to denote any secret that is synced via Vault Enterprise. Similar
to secret names, tag keys and values are normalized according to the valid character set of each destination type.

## Granularity

Vault KV-v2 secrets are multi-value and their data is represented in JSON. Multi-value secrets are useful to bundle closely
related information together like a username & password pair. However, most secret management systems only support single-value
entries. Secrets sync allows you to choose the granularity that best suits your use case for each destination by specifying a `granularity`
field.

The `secret-path` granularity syncs the entire JSON content of the Vault secret as a single entry at the destination. If
the destination does not support multi-value secret the JSON is encoded as a single-value JSON-string.

The `secret-key` granularity syncs each Vault key-value pair as a distinct entry at the destination. If the value itself is a list or map
it is encoded as a JSON blob.

Granularity can be updated. The new granularity only affects secrets newly associated with the destination and does
not modify the previously synced secrets. It is possible to update an association to force a recreate operation.
The secret synced with the old granularity will be deleted and new secrets will be synced according to the new granularity.

## Security

~> Note: Vault does not control the permissions at the destination. It is the responsibility
of the operator to configure and maintain proper access controls on the external system so synced
secrets are not accessed unintentionally.

### Vault access requirements

Vault verifies the client has read access on the secret before syncing it with any destination. This additional check is
there to prevent users from maliciously or unintentionally leveraging elevated permissions on an external system to access
secrets they normally wouldn't be able to.

Let's assume we have a secret located at `path/to/data/secret1` and a user with write access to the sync feature,
but no read access to that secret. This scenario is equivalent to this ACL policy:

  <CodeBlockConfig hideClipboard>

    # Allow full access to the sync feature
    path "sys/sync/*" {
      capabilities = ["read", "list", "create", "update", "delete"]
    }

    # Allow read access to the secret mount path/to
    path "path/to/*" {
      capabilities = ["read"]
    }

    # Deny access to a specific secret
    path "path/to/data/my-secret-1" {
      capabilities = ["deny"]
    }

  </CodeBlockConfig>

If a client with this policy tries to read this secret they will receive an unauthorized error:

  <CodeBlockConfig hideClipboard>

    $ vault kv get -mount=path/to my-secret-1

    Error reading path/to/data/my-secret-1: Error making API request.

    URL: GET http://127.0.0.1:8200/v1/path/to/data/my-secret-1
    Code: 403. Errors:

    * 1 error occurred:
      * permission denied

  </CodeBlockConfig>

Likewise, if the client tries to sync this secret to any destination they will receive a similar unauthorized error:

  <CodeBlockConfig hideClipboard>

    $ vault write sys/sync/destinations/$TYPE/$NAME/associations/set \
    mount="path/to" \
    secret_name="my-secret-1"

    Error writing data to sys/sync/destinations/$TYPE/$NAME/associations/set: Error making API request.

    URL: PUT http://127.0.0.1:8200/v1/sys/sync/destinations/$TYPE/$NAME/associations/set
    Code: 403. Errors:

    * permission denied to read the content of the secret my-secret-1 in mount path/to

  </CodeBlockConfig>

This read access verification is only done when creating or updating an association. Once the association is created, revoking
read access to the policy that was used to sync the secret has no effect.

### Collisions and overwrites

Secrets Sync operates with a last-write-wins strategy. If a secret with the same name already exists at the destination,
Vault overwrites it when syncing a secret. There are also no automatic mechanisms to prevent a principal with sufficient
privileges at the destination from overwriting a secret synced by Vault.

To prevent Vault from accidentally overwriting existing secrets, it is recommended to use either a name pattern or
built-in tags as an extra policy condition on the role used to configure a Vault sync destination. A negative condition on other
policies may be used to prevent out-of-band overwrites to Vault secrets from non-Vault roles.

To see examples of policies that provide this type of restriction, refer to the access management section of the documentation
for each destination type below:

* [AWS Access Management](/vault/docs/sync/awssm#access-management)
* [GCP Access Management](/vault/docs/sync/gcpsm#access-management)

## Reconciliation

Vault Secrets Sync is designed to automatically recover from transient failures
in two ways: operation retries and reconciliation scans.

Operation retries happen when a sync operation fails. Vault automatically
retries the operation with exponential backoff. Operation retries help in
situations where your network becomes unreliable or overwhelmed.

Reconciliation scans happen periodically in a background thread. Vault scans all
secrets currently managed by the sync system to identify and update out-of-date
secrets, and to ensure that any configured destinations are up-to-date.
Reconciliation scans help in situations where there are external service downtimes
that are outside of your control and provide a way to automatically recover and self-heal.

Operation retries and reconciliation scans are both enabled by default.

Note that reconciliation process do not protect from out-of-band updates
that occur directly in the external service. The secrets sync system is designed to be
one-way and does not support bidirectional sync at this time.

## Client counts

Each secret that is synced with one or more destinations is counted as a
distinct client in Vault's client counting. See [entity assignments with secret
sync](/vault/docs/concepts/client-count#secret-sync-clients)
for more information.

## API

Please see the [secrets sync API](/vault/api-docs/system/secrets-sync) for more details.

layout  docs page title  Secrets sync description       Use secrets sync feature to automatically sync Vault managed secrets with external destinations to centralize secrets lifecycle management         Secrets sync   EnterpriseAlert product  vault      In certain circumstances  fetching secrets directly from Vault is impossible or impractical  To help with this challenge  Vault can maintain a one way sync for KVv2 secrets into various destinations that are easier to access for some clients  With this  Vault remains the system of records but can cache a subset of secrets on various external systems acting as trusted last mile delivery systems   A secret that is associated from a Vault KVv2 Secrets Engine into an external destination is actively managed by a continuous process  If the secret value is updated in Vault  the secret is updated in the destination as well  If the secret is deleted from Vault  it is deleted on the external system as well  This process is asynchronous and event based  Vault propagates modifications into the proper destinations automatically in a handful of seconds    Note title  Not related to HCP Vault Secrets      Secrets sync is a Vault Enterprise feature  For information on secrets sync   with  HCP Vault Secrets   hcp docs vault secrets   refer to the HashiCorp Cloud   Platform documentation for    Vault Secrets integrations   hcp docs vault secrets integrations      Note      Activating the feature  The secrets sync feature requires manual activation through a one time trigger  If a sync related endpoint is called prior to activation  an error response will be received indicating that the feature has not been activated yet  Be sure to understand the potential  client count impacts   client counts  of using secrets sync before proceeding   Activating the feature can be done through one of several methods     1  Activation directly through the UI       1  Acitvation through the CLI              shell session     vault write  f sys activation flags secrets sync activate             1  Activation through a POST or PUT request          shell session       curl           request PUT           header  X Vault Token               http   127 0 0 1 8200 v1 sys activation flags secrets sync activate             Destinations  Secrets can be synced into various external systems  called destinations  The supported destinations are     AWS Secrets Manager   vault docs sync awssm     Azure Key Vault   vault docs sync azurekv     GCP Secret Manager   vault docs sync gcpsm     GitHub Repository Actions   vault docs sync github     Vercel Projects   vault docs sync vercelproject      Associations  Syncing a secret into one of the external systems is done by creating a connection between it and a destination  which is called an association  These associations are created via Vault s API by adding a KVv2 secret target to one of the configured destinations  Each association keeps track of that secret s current sync status  the timestamp of its last status change  and the error code of the last sync or unsync operation if it failed  Each destination can have any number of secret associations      Sync statuses  There are several sync statuses which relay information about the outcome of the latest sync operation to have occurred on that secret  The status information is stored inside each association object returned by the endpoint and  upon failure  includes an error code describing the cause of the failure     Status                     Description                                                                                UNKNOWN                   Vault is unable to determine the current state of the secret in regard to the external service       PENDING                   An operation is queued for that secret and has not been processed yet                                SYNCED                    The sync operation was successful and sent the secret to the external destination                    UNSYNCED                  The unsync operation was successful and removed the secret from the external destination             INTERNAL VAULT ERROR      The operation failed due to an issue internal to Vault                                               CLIENT SIDE ERROR         The operation failed due to a configuration error such as invalid privileges                         EXTERNAL SERVICE ERROR    The operation failed due to an issue with the external service such as a temporary downtime           Name template  By default  the name of synced secrets follows this format   vault  accessor   secret path    The casing and delimiters may change as they are normalized according to the valid character set of each destination type  This pattern was chosen to prevent accidental name collisions and to clearly identify where the secret is coming from   Every destination allows you to customize this name pattern by configuring a  secret name template  field to best suit individual use cases  The templates use a subset of the go template syntax for extra flexibility   The following placeholders are available     Placeholder           Description                                                                                DestinationType      The type of the destination  e g   aws sm                                                                        DestinationName      The name of the destination                                                                                NamespacePath        The full namespace path where the secret being synced is located                                                 NamespaceBaseName    The segment following the last     character from the full path                                                  NamespaceID          The internal unique ID identifying the namespace  e g   RQegM                                                    MountPath            The full mount path where the secret being synced is located                                                     MountBaseName        The segment following the last     character from the full path                                                  MountAccessor        The internal unique ID identifying the mount  e g   kv 1234                                                      SecretPath           The full secret path                                                                                SecretBaseName       The segment following the last     character from the full path                                                  SecretKey            The individual secret key being synced  only available if the destination uses the  secret key  granularity    Let s assume we want to sync the following secret      CodeBlockConfig hideClipboard         VAULT NAMESPACE ns1 ns2 vault kv get  mount path to kv1 path to secret1                 Secret Path                path to kv1 data path to secret1              Metadata                            Data         Key    Value                      foo    bar      CodeBlockConfig   Let s look at some name template examples and the resulting secret name at the sync destination     Name template                              Result                                                                                prefix                    prefix path to secret1              SECRET1                           kv 1234 foo                   path to secret1           Name templates can be updated  The new template is only effective for new secrets associated with the destination and does not affect the secrets synced with the previous template  It is possible to update an association to force a recreate operation  The secret synced with the old template will be deleted and a new secret using the new template version will be synced      Custom tags  A destination can also have custom tags so that every secret associated to it that is synced will share that same set of tags  Additionally  a default tag value of  hashicorp vault  is used to denote any secret that is synced via Vault Enterprise  Similar to secret names  tag keys and values are normalized according to the valid character set of each destination type      Granularity  Vault KV v2 secrets are multi value and their data is represented in JSON  Multi value secrets are useful to bundle closely related information together like a username   password pair  However  most secret management systems only support single value entries  Secrets sync allows you to choose the granularity that best suits your use case for each destination by specifying a  granularity  field   The  secret path  granularity syncs the entire JSON content of the Vault secret as a single entry at the destination  If the destination does not support multi value secret the JSON is encoded as a single value JSON string   The  secret key  granularity syncs each Vault key value pair as a distinct entry at the destination  If the value itself is a list or map it is encoded as a JSON blob   Granularity can be updated  The new granularity only affects secrets newly associated with the destination and does not modify the previously synced secrets  It is possible to update an association to force a recreate operation  The secret synced with the old granularity will be deleted and new secrets will be synced according to the new granularity      Security     Note  Vault does not control the permissions at the destination  It is the responsibility of the operator to configure and maintain proper access controls on the external system so synced secrets are not accessed unintentionally       Vault access requirements  Vault verifies the client has read access on the secret before syncing it with any destination  This additional check is there to prevent users from maliciously or unintentionally leveraging elevated permissions on an external system to access secrets they normally wouldn t be able to   Let s assume we have a secret located at  path to data secret1  and a user with write access to the sync feature  but no read access to that secret  This scenario is equivalent to this ACL policy      CodeBlockConfig hideClipboard         Allow full access to the sync feature     path  sys sync            capabilities     read    list    create    update    delete                Allow read access to the secret mount path to     path  path to            capabilities     read                Deny access to a specific secret     path  path to data my secret 1          capabilities     deny              CodeBlockConfig   If a client with this policy tries to read this secret they will receive an unauthorized error      CodeBlockConfig hideClipboard         vault kv get  mount path to my secret 1      Error reading path to data my secret 1  Error making API request       URL  GET http   127 0 0 1 8200 v1 path to data my secret 1     Code  403  Errors         1 error occurred          permission denied      CodeBlockConfig   Likewise  if the client tries to sync this secret to any destination they will receive a similar unauthorized error      CodeBlockConfig hideClipboard         vault write sys sync destinations  TYPE  NAME associations set       mount  path to        secret name  my secret 1       Error writing data to sys sync destinations  TYPE  NAME associations set  Error making API request       URL  PUT http   127 0 0 1 8200 v1 sys sync destinations  TYPE  NAME associations set     Code  403  Errors         permission denied to read the content of the secret my secret 1 in mount path to      CodeBlockConfig   This read access verification is only done when creating or updating an association  Once the association is created  revoking read access to the policy that was used to sync the secret has no effect       Collisions and overwrites  Secrets Sync operates with a last write wins strategy  If a secret with the same name already exists at the destination  Vault overwrites it when syncing a secret  There are also no automatic mechanisms to prevent a principal with sufficient privileges at the destination from overwriting a secret synced by Vault   To prevent Vault from accidentally overwriting existing secrets  it is recommended to use either a name pattern or built in tags as an extra policy condition on the role used to configure a Vault sync destination  A negative condition on other policies may be used to prevent out of band overwrites to Vault secrets from non Vault roles   To see examples of policies that provide this type of restriction  refer to the access management section of the documentation for each destination type below      AWS Access Management   vault docs sync awssm access management     GCP Access Management   vault docs sync gcpsm access management      Reconciliation  Vault Secrets Sync is designed to automatically recover from transient failures in two ways  operation retries and reconciliation scans   Operation retries happen when a sync operation fails  Vault automatically retries the operation with exponential backoff  Operation retries help in situations where your network becomes unreliable or overwhelmed   Reconciliation scans happen periodically in a background thread  Vault scans all secrets currently managed by the sync system to identify and update out of date secrets  and to ensure that any configured destinations are up to date  Reconciliation scans help in situations where there are external service downtimes that are outside of your control and provide a way to automatically recover and self heal   Operation retries and reconciliation scans are both enabled by default   Note that reconciliation process do not protect from out of band updates that occur directly in the external service  The secrets sync system is designed to be one way and does not support bidirectional sync at this time      Client counts  Each secret that is synced with one or more destinations is counted as a distinct client in Vault s client counting  See  entity assignments with secret sync   vault docs concepts client count secret sync clients  for more information      API  Please see the  secrets sync API   vault api docs system secrets sync  for more details


vault page title Sync secrets from Vault to Azure Key Vault The Azure Key Vault destination enables Vault to sync and unsync secrets of your choosing into Sync secrets from Vault to Azure Key Vault layout docs Automatically sync and unsync the secrets from Vault to Azure Key Vault to centralize visibility and control of secrets lifecycle management

Answer:
---
layout: docs
page_title: Sync secrets from Vault to Azure Key Vault
description: >-
  Automatically sync and unsync the secrets from Vault to Azure Key Vault to centralize visibility and control of secrets lifecycle management.
---

# Sync secrets from Vault to 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](https://learn.microsoft.com/en-us/azure/key-vault/general/quick-create-portal).

1. A service principal with a client id and client secret will be needed to configure Azure Key Vault as a
  sync destination. This [guide](https://learn.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal)
  will walk you through creating the service principal.

1. Once the service principal is created, the next step is to
  [grant the service principal](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide?tabs=azure-cli)
  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](#permissions) section.

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

  ```shell-session
  $ 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"
  ```

  **Output:**

  <CodeBlockConfig hideClipboard>

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

  </CodeBlockConfig>

## Usage

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

  ```shell-session
  $ vault secrets enable -path='my-kv' kv-v2
  ```

  **Output:**

  <CodeBlockConfig hideClipboard>

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

  </CodeBlockConfig>

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

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

  **Output:**

  <CodeBlockConfig hideClipboard>

  ```plaintext
  ==== 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
  ```

  </CodeBlockConfig>

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

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

  **Output:**

  <CodeBlockConfig hideClipboard>

  ```plaintext
  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
  ```

  </CodeBlockConfig>

1. Navigate to [Azure Key Vault](https://portal.azure.com/#view/HubsExtension/BrowseResource/resourceType/Microsoft.KeyVault%2Fvaults)
  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](https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles#steps-to-create-a-custom-role)
using the following JSON role definition. Be sure to replace the subscription id placeholder.

```json
{
  "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}/"
    ]
  }
}
```

## Access management

You can allow or restrict access to secrets by using a separate Azure Key Vault instance for Vault sync destinations.
This corresponds with Microsoft's currently-recommended
[best practices](https://learn.microsoft.com/en-us/azure/key-vault/general/best-practices)
for managing secrets in Key Vault. Maintaining a boundary between Vault-managed secrets and other secrets through
separate Key Vaults provides increased security and access control.

Azure roles can be created to grant the necessary permissions for the service principal to access the Key Vault
with [role-based access control](https://learn.microsoft.com/en-us/azure/role-based-access-control/overview).
A role assignment can be set for the Vault user principal to provide it the role's permissions within the Key Vault
instance, its resource group, or subscription. Additionally,
[Azure policies](https://learn.microsoft.com/en-us/azure/key-vault/general/azure-policy) may further refine access control
limitations, such as denying the Vault user principal access to non-Vault related Key Vaults. The inverse, denying other
users any write-access to the Vault-related Key Vault, may be another choice.

## API

Please see the [secrets sync API](/vault/api-docs/system/secrets-sync) for more details.

layout  docs page title  Sync secrets from Vault to Azure Key Vault description       Automatically sync and unsync the secrets from Vault to Azure Key Vault to centralize visibility and control of secrets lifecycle management         Sync secrets from Vault to 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  https   learn microsoft com en us azure key vault general quick create portal    1  A service principal with a client id and client secret will be needed to configure Azure Key Vault as a   sync destination  This  guide  https   learn microsoft com en us azure active directory develop howto create service principal portal    will walk you through creating the service principal   1  Once the service principal is created  the next step is to    grant the service principal  https   learn microsoft com en us azure key vault general rbac guide tabs azure cli    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   permissions  section    1  Configure a sync destination with the service principal credentials and Key Vault URI created in the previous steps        shell session     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             Output        CodeBlockConfig hideClipboard        plaintext   Key                   Value                                 connection details    map client id 123 client secret       key vault uri       tenant id 123    name                  my azure 1   type                  azure kv            CodeBlockConfig      Usage  1  If you do not already have a KVv2 secret to sync  mount a new KVv2 secrets engine        shell session     vault secrets enable  path  my kv  kv v2            Output        CodeBlockConfig hideClipboard        plaintext   Success  Enabled the kv v2 secrets engine at  my kv             CodeBlockConfig   1  Create secrets you wish to sync with a target Azure Key Vault        shell session     vault kv put  mount  my kv  my secret foo  bar             Output        CodeBlockConfig hideClipboard        plaintext        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            CodeBlockConfig   1  Create an association between the destination and a secret to synchronize        shell session     vault write sys sync destinations azure kv my azure 1 associations set         mount  my kv          secret name  my secret             Output        CodeBlockConfig hideClipboard        plaintext   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            CodeBlockConfig   1  Navigate to  Azure Key Vault  https   portal azure com  view HubsExtension BrowseResource resourceType Microsoft KeyVault 2Fvaults    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  https   learn microsoft com en us azure role based access control custom roles steps to create a custom role  using the following JSON role definition  Be sure to replace the subscription id placeholder      json      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                        Access management  You can allow or restrict access to secrets by using a separate Azure Key Vault instance for Vault sync destinations  This corresponds with Microsoft s currently recommended   best practices  https   learn microsoft com en us azure key vault general best practices  for managing secrets in Key Vault  Maintaining a boundary between Vault managed secrets and other secrets through separate Key Vaults provides increased security and access control   Azure roles can be created to grant the necessary permissions for the service principal to access the Key Vault with  role based access control  https   learn microsoft com en us azure role based access control overview   A role assignment can be set for the Vault user principal to provide it the role s permissions within the Key Vault instance  its resource group  or subscription  Additionally   Azure policies  https   learn microsoft com en us azure key vault general azure policy  may further refine access control limitations  such as denying the Vault user principal access to non Vault related Key Vaults  The inverse  denying other users any write access to the Vault related Key Vault  may be another choice      API  Please see the  secrets sync API   vault api docs system secrets sync  for more details


vault Sync secrets from Vault to AWS Secrets Manager Automatically sync and unsync the secrets from Vault to AWS Secrets Manager to centralize visibility and control of secrets lifecycle management page title Sync secrets from Vault to AWS Secrets Manager The AWS Secrets Manager destination enables Vault to sync and unsync secrets of your choosing into layout docs

Answer:
---
layout: docs
page_title: Sync secrets from Vault to AWS Secrets Manager
description: >-
  Automatically sync and unsync the secrets from Vault to AWS Secrets Manager to centralize visibility and control of secrets lifecycle management.
---

# Sync secrets from Vault to AWS Secrets Manager

The AWS Secrets Manager destination enables Vault to sync and unsync secrets of your choosing into
an external AWS account. When configured, Vault will actively maintain the state of each externally-synced
secret in near-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. This enables the
ability to keep control of all your secrets localized while leveraging the benefits of the AWS Secrets Manager.

Prerequisites:
* Ability to read or create KVv2 secrets
* Ability to create AWS IAM user and access keys with access to the Secrets Manager
* Ability to create sync destinations and associations on your Vault server

## Setup

1. Navigate to the [AWS Identity and Access Management (IAM) console](https://us-east-1.console.aws.amazon.com/iamv2/home#/home)
  to configure a IAM user with access to the Secrets Manager. The following is an example policy outlining the required
  permissions to use secrets syncing.

  ```json
  {
    "Version": "2012-10-17",
    "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "secretsmanager:Create*",
            "secretsmanager:Update*",
            "secretsmanager:Delete*",
            "secretsmanager:TagResource"
          ],
          "Resource": "arn:aws:secretsmanager:*:*:secret:vault*"
        }
    ]
  }
  ```

1.	Configure a sync destination with the IAM user credentials created in the previous step.

	```shell-session
	$ vault write sys/sync/destinations/aws-sm/my-awssm-1 \
		  access_key_id="$ACCESS_KEY_ID" \
		  secret_access_key="$SECRET_ACCESS_KEY" \
		  region='us-east-1'
	```

	**Output:**

	<CodeBlockConfig hideClipboard>

	```plaintext
	Key                   Value
	---                   -----
	connection_details    map[access_key_id:***** region:us-east-1 secret_access_key:*****]
	name                  my-awssm-1
	type                  aws-sm
	```

	</CodeBlockConfig>

## Usage

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

	```shell-session
	$ vault secrets enable -path=my-kv kv-v2
	```

	**Output:**

	<CodeBlockConfig hideClipboard>

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

	</CodeBlockConfig>

1. Create secrets you wish to sync with a target AWS Secrets Manager.

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

	**Output:**

	<CodeBlockConfig hideClipboard>

	```plaintext
	==== 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
	```

	</CodeBlockConfig>

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

	```shell-session
	$ vault write sys/sync/destinations/aws-sm/my-awssm-1/associations/set \
		mount='my-kv' \
		secret_name='my-secret'
	```

	**Output:**

	<CodeBlockConfig hideClipboard>

	```plaintext
	Key                   Value
	---                   -----
	associated_secrets    map[kv_37993f8a/my-secret:map[accessor:kv_37993f8a secret_name:my-secret sync_status:SYNCED updated_at:2023-09-19T13:17:35.085581-05:00]]
	store_name            aws1
	store_type            aws-sm
	```

	</CodeBlockConfig>

1. Navigate to the [Secrets Manager](https://console.aws.amazon.com/secretsmanager/) in the AWS console
	to confirm your secret was successfully synced.

Moving forward, any modification on the Vault secret will be propagated to its AWS Secrets Manager
counterpart. Creating a new secret version in Vault will update the one in AWS to the new version. Deleting either
the secret or the association in Vault will delete the secret in your AWS account as well.

## Access management

You can allow or restrict access to secrets by attaching AWS Resource Tags
to secrets. For example, the following AWS IAM policy prevents Vault from
modifying secrets that were not created by a sync operation:

  <CodeBlockConfig hideClipboard>

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "secretsmanager:*",
          ],
          "Resource": "*",
          "Condition": {
            "StringEquals": {
              "secretsmanager:ResourceTag/hashicorp:vault": "" # This tag is automatically added by Vault on every synced secrets
            }
          }
        }
      ]
    }

  </CodeBlockConfig>

To prevent out-of-band overwrites, we recommend adding a negative condition on
all write-access policies not used by Vault:

  <CodeBlockConfig hideClipboard>

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Deny",
          "Action": [
            "secretsmanager:*"
          ],
          "Resource": "*",
          "Condition": {
            "StringNotEquals": {
              "secretsmanager:ResourceTag/hashicorp:vault": "" # This tag is automatically added by Vault on every synced secrets
            }
          }
        }
      ]
    }

  </CodeBlockConfig>

<Warning title="Use wildcards with extreme caution">

  The previous examples use wildcards for the sake of brevity. We strongly
  recommend you use the principle of least privilege to restrict actions and
  resources for each use case to the minimum necessary requirements.

</Warning>

## Tutorial

Refer to the [Vault Enterprise Secrets Sync tutorial](/vault/tutorials/enterprise/secrets-sync)
to learn how to configure the secrets sync between Vault and AWS Secrets Manager.

## API

Please see the [secrets sync API](/vault/api-docs/system/secrets-sync) for more details.

layout  docs page title  Sync secrets from Vault to AWS Secrets Manager description       Automatically sync and unsync the secrets from Vault to AWS Secrets Manager to centralize visibility and control of secrets lifecycle management         Sync secrets from Vault to AWS Secrets Manager  The AWS Secrets Manager destination enables Vault to sync and unsync secrets of your choosing into an external AWS account  When configured  Vault will actively maintain the state of each externally synced secret in near 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  This enables the ability to keep control of all your secrets localized while leveraging the benefits of the AWS Secrets Manager   Prerequisites    Ability to read or create KVv2 secrets   Ability to create AWS IAM user and access keys with access to the Secrets Manager   Ability to create sync destinations and associations on your Vault server     Setup  1  Navigate to the  AWS Identity and Access Management  IAM  console  https   us east 1 console aws amazon com iamv2 home  home    to configure a IAM user with access to the Secrets Manager  The following is an example policy outlining the required   permissions to use secrets syncing        json          Version    2012 10 17        Statement                          Effect    Allow              Action                  secretsmanager Create                 secretsmanager Update                 secretsmanager Delete                 secretsmanager TagResource                          Resource    arn aws secretsmanager     secret vault                              1  Configure a sync destination with the IAM user credentials created in the previous step       shell session    vault write sys sync destinations aws sm my awssm 1       access key id   ACCESS KEY ID        secret access key   SECRET ACCESS KEY        region  us east 1           Output       CodeBlockConfig hideClipboard       plaintext  Key                   Value                               connection details    map access key id       region us east 1 secret access key         name                  my awssm 1  type                  aws sm          CodeBlockConfig      Usage  1  If you do not already have a KVv2 secret to sync  mount a new KVv2 secrets engine       shell session    vault secrets enable  path my kv kv v2          Output       CodeBlockConfig hideClipboard       plaintext  Success  Enabled the kv v2 secrets engine at  my kv           CodeBlockConfig   1  Create secrets you wish to sync with a target AWS Secrets Manager       shell session    vault kv put  mount my kv my secret foo  bar           Output       CodeBlockConfig hideClipboard       plaintext       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          CodeBlockConfig   1  Create an association between the destination and a secret to synchronize       shell session    vault write sys sync destinations aws sm my awssm 1 associations set     mount  my kv      secret name  my secret           Output       CodeBlockConfig hideClipboard       plaintext  Key                   Value                               associated secrets    map kv 37993f8a my secret map accessor kv 37993f8a secret name my secret sync status SYNCED updated at 2023 09 19T13 17 35 085581 05 00    store name            aws1  store type            aws sm          CodeBlockConfig   1  Navigate to the  Secrets Manager  https   console aws amazon com secretsmanager   in the AWS console  to confirm your secret was successfully synced   Moving forward  any modification on the Vault secret will be propagated to its AWS Secrets Manager counterpart  Creating a new secret version in Vault will update the one in AWS to the new version  Deleting either the secret or the association in Vault will delete the secret in your AWS account as well      Access management  You can allow or restrict access to secrets by attaching AWS Resource Tags to secrets  For example  the following AWS IAM policy prevents Vault from modifying secrets that were not created by a sync operation      CodeBlockConfig hideClipboard                Version    2012 10 17          Statement                          Effect    Allow              Action                  secretsmanager                             Resource                   Condition                  StringEquals                    secretsmanager ResourceTag hashicorp vault        This tag is automatically added by Vault on every synced secrets                                                        CodeBlockConfig   To prevent out of band overwrites  we recommend adding a negative condition on all write access policies not used by Vault      CodeBlockConfig hideClipboard                Version    2012 10 17          Statement                          Effect    Deny              Action                  secretsmanager                            Resource                   Condition                  StringNotEquals                    secretsmanager ResourceTag hashicorp vault        This tag is automatically added by Vault on every synced secrets                                                        CodeBlockConfig    Warning title  Use wildcards with extreme caution      The previous examples use wildcards for the sake of brevity  We strongly   recommend you use the principle of least privilege to restrict actions and   resources for each use case to the minimum necessary requirements       Warning      Tutorial  Refer to the  Vault Enterprise Secrets Sync tutorial   vault tutorials enterprise secrets sync  to learn how to configure the secrets sync between Vault and AWS Secrets Manager      API  Please see the  secrets sync API   vault api docs system secrets sync  for more details


vault Secrets import allows you to safely onboard secrets from external sources into Vault KV for management include alerts enterprise only mdx page title Secrets import layout docs Secrets import

Answer:
---
layout: docs
page_title: Secrets import
description: Secrets import allows you to safely onboard secrets from external sources into Vault KV for management.
---

# Secrets import

@include 'alerts/enterprise-only.mdx'

@include 'alerts/alpha.mdx'

Distributing sensitive information across multiple external systems creates
several challenges, including:

- Increased operational overhead.
- Increased exposure risk from data sprawl.
- Increased risk of outdated and out-of-sync information.

Using Vault as a single source of truth (SSOT) for sensitive data increases
security and reduces management overhead, but migrating preexisting data from multiple
and/or varied sources can be complex and costly.

The secrets import process helps you automate and streamline your sensitive data
migration with codified import plans as HCL files. Import plans tell Vault which KVv2 secrets
engine instance to store the expected secret data in, the source system for which data will be
read from, and how to filter this data. Three HCL blocks make this possible:

- The `destination` block defines target KVv2 mounts.
- The `source` block provides credentials for connecting to the external system.
- The `mapping` block defines how Vault should decide which data gets imported before
  writing the information to KVv2.

## Destinations

Vault stores imported secrets in a Vault KVv2 secrets engine mount. Destination
blocks start with `destination_vault` and define the desired KVv2 mount path and
an optional namespace. The combination of these represent the exact location in your
Vault instance you want the information stored.

### HCL syntax

```hcl
destination_vault {
  name      = "my-dest-1"
  namespace = "ns-1"
  mount     = "mount-1"
}
```

- `name` `(string: <required>)` - A unique name for the destination block that can
  be referenced in subsequent mapping blocks.

- `mount` `(string: <required>)` - The mount path for the target KVv2 instance.

- `address` `(string)` - Optional network address of the Vault server with the
  KVv2 secrets engine enabled. By default, the Vault client's address will be used.

- `token` `(string)` - Optional authentication token for the Vault server at the
  specified address. By default, the Vault client's token will be used.

- `namespace` `(string)` - Optional namespace path containing the specified KVv2
  mount. By default, Vault looks for the KVv2 mount under the root namespace.

## Sources

Vault can import secrets from the following sources:
- [GCP Secret Manager](/vault/docs/import/gcpsm)

To pull data from a source during import, Vault needs read credentials for the
external system. You can provide credentials directly as part of the import
plan, or use Vault to automatically generate dynamic credentials if you already
have the corresponding secrets engine configured.

### HCL syntax

Source blocks start with `source_<external_system>` and include any connection
information required by the target system or the secrets engine to leverage. For example:

```hcl
source_gcp {
  name        = "my-gcp-source-1"
  credentials = "@/path/to/service-account-key.json"
}
```

- `name` `(string: <required>)` - A unique name for the source block that can be
  referenced in subsequent mapping blocks.

- `credentials` `(string: <required>)` - Path to a credential file or token with
  read permissions for the target system.

Depending on the source system, additional information may be required. Refer to
the connection documentation for your source system to determine the full set of
required fields for that system type.

## Mappings

Mappings glue the source and destination together and filter the migrated data,
to determine what is imported and what is ignored. Vault currently supports the
following mapping methods:

- [mapping_passthrough](/vault/docs/import/mappings#passthrough)
- [mapping_metadata](/vault/docs/import/mappings#metadata)
- [mapping_regex](/vault/docs/import/mappings#regex)

### HCL syntax

Mapping blocks start with `mapping_<filter_type>` and require a source name,
destination name, an execution priority, and any corresponding transformations
or filters that apply for each mapping type. For example:

```hcl
mapping_regex {
  name        = "my-map-1"
  source      = "my-gcp-source-1"
  destination = "my-dest-1"
  priority    = 1
  expression  = "^database/.*$"
}
```

- `name` `(string: <required>)` - A unique name for the mapping block.

- `source` `(string: <required>)` - The name of a previously-defined source block
  **from** which the data should be read.

- `destination` `(string: <required>)` - The name of a previously defined
  destination block **to** which the data should be written.

- `priority` `(integer: <required>)` - The order in which Vault should apply the
  mapping block during the import process. The lower the number, the higher the
  priority. For example, a mapping with priority 1 executes before a mapping
  with priority 2.

Depending on the filter type, additional fields may be required or possible. Refer
to the [import mappings documentation](/vault/docs/import/mappings) for the available
supported options and for a list of each mapping's specific fields.

<Tip title="Priority matters">

  Vault applies mapping definitions in priority order and a given secret only
  matches to the first mapping that applies. Once Vault imports a secret with a
  particular mapping, subsequent reads from the same source will ignore that
  secret. See the [priority section](/vault/docs/import/mappings#priority) for an example.

</Tip>

layout  docs page title  Secrets import description  Secrets import allows you to safely onboard secrets from external sources into Vault KV for management          Secrets import   include  alerts enterprise only mdx    include  alerts alpha mdx   Distributing sensitive information across multiple external systems creates several challenges  including     Increased operational overhead    Increased exposure risk from data sprawl    Increased risk of outdated and out of sync information   Using Vault as a single source of truth  SSOT  for sensitive data increases security and reduces management overhead  but migrating preexisting data from multiple and or varied sources can be complex and costly    The secrets import process helps you automate and streamline your sensitive data migration with codified import plans as HCL files  Import plans tell Vault which KVv2 secrets engine instance to store the expected secret data in  the source system for which data will be read from  and how to filter this data  Three HCL blocks make this possible     The  destination  block defines target KVv2 mounts    The  source  block provides credentials for connecting to the external system    The  mapping  block defines how Vault should decide which data gets imported before   writing the information to KVv2      Destinations  Vault stores imported secrets in a Vault KVv2 secrets engine mount  Destination blocks start with  destination vault  and define the desired KVv2 mount path and an optional namespace  The combination of these represent the exact location in your Vault instance you want the information stored       HCL syntax      hcl destination vault     name         my dest 1    namespace    ns 1    mount        mount 1            name    string   required      A unique name for the destination block that can   be referenced in subsequent mapping blocks      mount    string   required      The mount path for the target KVv2 instance      address    string     Optional network address of the Vault server with the   KVv2 secrets engine enabled  By default  the Vault client s address will be used      token    string     Optional authentication token for the Vault server at the   specified address  By default  the Vault client s token will be used      namespace    string     Optional namespace path containing the specified KVv2   mount  By default  Vault looks for the KVv2 mount under the root namespace        Sources  Vault can import secrets from the following sources     GCP Secret Manager   vault docs import gcpsm   To pull data from a source during import  Vault needs read credentials for the external system  You can provide credentials directly as part of the import plan  or use Vault to automatically generate dynamic credentials if you already have the corresponding secrets engine configured       HCL syntax  Source blocks start with  source  external system   and include any connection information required by the target system or the secrets engine to leverage  For example      hcl source gcp     name           my gcp source 1    credentials      path to service account key json            name    string   required      A unique name for the source block that can be   referenced in subsequent mapping blocks      credentials    string   required      Path to a credential file or token with   read permissions for the target system   Depending on the source system  additional information may be required  Refer to the connection documentation for your source system to determine the full set of required fields for that system type        Mappings  Mappings glue the source and destination together and filter the migrated data  to determine what is imported and what is ignored  Vault currently supports the following mapping methods      mapping passthrough   vault docs import mappings passthrough     mapping metadata   vault docs import mappings metadata     mapping regex   vault docs import mappings regex       HCL syntax  Mapping blocks start with  mapping  filter type   and require a source name  destination name  an execution priority  and any corresponding transformations or filters that apply for each mapping type  For example      hcl mapping regex     name           my map 1    source         my gcp source 1    destination    my dest 1    priority      1   expression      database                name    string   required      A unique name for the mapping block      source    string   required      The name of a previously defined source block     from   which the data should be read      destination    string   required      The name of a previously defined   destination block   to   which the data should be written      priority    integer   required      The order in which Vault should apply the   mapping block during the import process  The lower the number  the higher the   priority  For example  a mapping with priority 1 executes before a mapping   with priority 2   Depending on the filter type  additional fields may be required or possible  Refer to the  import mappings documentation   vault docs import mappings  for the available supported options and for a list of each mapping s specific fields    Tip title  Priority matters      Vault applies mapping definitions in priority order and a given secret only   matches to the first mapping that applies  Once Vault imports a secret with a   particular mapping  subsequent reads from the same source will ignore that   secret  See the  priority section   vault docs import mappings priority  for an example     Tip


vault used to filter the scanned secrets and determine which will be imported in to Vault Vault supports multiple filter types for mapping blocks Each of the types provides a different mechanism Import mappings Mappings lets users apply various filtering methods to secrets being imported in to Vault layout docs page title Secrets import mappings

Answer:
---
layout: docs
page_title: Secrets import mappings
description: Mappings lets users apply various filtering methods to secrets being imported in to Vault.
---

# Import mappings

Vault supports multiple filter types for mapping blocks. Each of the types provides a different mechanism
used to filter the scanned secrets and determine which will be imported in to Vault.

## Argument reference

Refer to the [HCL syntax](/vault/docs/import#hcl-syntax-2) for arguments common to all mapping types.

## Passthrough mapping filters

The passthrough mapping block `mapping_passthrough` allows all secrets through from the specified source to the
specified destination. For example, one use case is setting it as a base-case for imported secrets. By assigning
it the lowest priority in the import plan, all other mapping blocks will be applied first. Secrets that fail
to match any of the previous mappings will fall through to the passthrough block and be collected in a single
KVv2 location.

### Additional arguments

There are no extra arguments to specify in a `mapping_passthrough` block.

### Example

In this example, every single secret that `my-gcp-source-1` scans from GCP Secret Manager will be imported
to the KVv2 secrets engine mount defined in `my-dest-1`.

```hcl
mapping_passthrough {
  name        = "my-map-1"
  source      = "my-gcp-source-1"
  destination = "my-dest-1"
  priority    = 1
}
```

## Metadata

The metadata mapping block `mapping_metadata` allows secrets through from the specified source to the specified
destination if they contain matching metadata key-value pairs. Metadata is not supported in all external secret
management systems, and ones that do may use different terminology for metadata. For example, AWS allows tags
on secrets while [GCP](/vault/docs/import/gcpsm) allows labels.

### Additional arguments

* `tags` `(string: <required>)` - A set of key-value pairs to match on secrets from the external system. All of the specified
keys must be found on a secret and all of the values must be exact matches. Specifying a key in this mapping with
an empty value, i.e. `""`, acts as a wildcard match to the external system's key's value.

### Example

In this example, `my-map-1` will only import the secrets into the destination `my-dest-1` that contain a tag with
a key named `importable` and its value set to `true`.

```hcl
mapping_metadata {
  name        = "my-map-1"
  source      = "my-gcp-source-1"
  destination = "my-dest-1"
  priority    = 1

  tags = {
    "importable" = "true"
  }
}
```

## Regex

The regex mapping block `mapping_regex` allows secrets through from the specified source to the specified
destination if their secret name passes a regular expression check.

### Additional arguments

* `expression` `(string: <required>)` - The regular expression used to match secrets' names from the external system.

### Example

In this example, any secret in the GCP source whose name begins with `database/` will be imported into Vault.

```hcl
mapping_regex {
  name        = "my-map-1"
  source      = "my-gcp-source-1"
  destination = "my-dest-1"
  priority    = 1
  expression  = "^database/.*$"
}
```

## Priority

Priority works in a "first match" fashion where lower values are higher priority. To explain in more detail,
consider the above metadata example with a second additional mapping.

Below are two metadata mappings. The first, `my-map-1`, has a priority of 1. This will only import the secrets
into the destination `my-dest-1` that contain both tag keys `database` and `importable`. Each of these keys' values
must also match to `users` and `true` respectively. The second, `my-map-2`, has a priority of 2. Even though all
the secrets in the first mapping would also qualify for the second mapping's filtering rule, those secrets will only
be imported into `my-dest-1` because of `my-map-2`'s lower priority. All remaining secrets that have the tag
`importable` with a value of `true` will be imported into `my-dest-2`.

```hcl
mapping_metadata {
  name        = "my-map-1"
  source      = "my-gcp-source-1"
  destination = "my-dest-1"
  priority    = 1

  tags = {
    "database"   = "users"
    "importable" = "true"
  }
}

mapping_metadata {
  name        = "my-map-2"
  source      = "my-gcp-source-1"
  destination = "my-dest-2"
  priority    = 2

  tags = {
    "importable" = "true"
  }
}
```

layout  docs page title  Secrets import mappings description  Mappings lets users apply various filtering methods to secrets being imported in to Vault         Import mappings  Vault supports multiple filter types for mapping blocks  Each of the types provides a different mechanism used to filter the scanned secrets and determine which will be imported in to Vault       Argument reference  Refer to the  HCL syntax   vault docs import hcl syntax 2  for arguments common to all mapping types      Passthrough mapping filters  The passthrough mapping block  mapping passthrough  allows all secrets through from the specified source to the specified destination  For example  one use case is setting it as a base case for imported secrets  By assigning it the lowest priority in the import plan  all other mapping blocks will be applied first  Secrets that fail to match any of the previous mappings will fall through to the passthrough block and be collected in a single KVv2 location       Additional arguments  There are no extra arguments to specify in a  mapping passthrough  block       Example  In this example  every single secret that  my gcp source 1  scans from GCP Secret Manager will be imported to the KVv2 secrets engine mount defined in  my dest 1       hcl mapping passthrough     name           my map 1    source         my gcp source 1    destination    my dest 1    priority      1           Metadata  The metadata mapping block  mapping metadata  allows secrets through from the specified source to the specified destination if they contain matching metadata key value pairs  Metadata is not supported in all external secret management systems  and ones that do may use different terminology for metadata  For example  AWS allows tags on secrets while  GCP   vault docs import gcpsm  allows labels       Additional arguments     tags    string   required      A set of key value pairs to match on secrets from the external system  All of the specified keys must be found on a secret and all of the values must be exact matches  Specifying a key in this mapping with an empty value  i e        acts as a wildcard match to the external system s key s value       Example  In this example   my map 1  will only import the secrets into the destination  my dest 1  that contain a tag with a key named  importable  and its value set to  true        hcl mapping metadata     name           my map 1    source         my gcp source 1    destination    my dest 1    priority      1    tags          importable     true                Regex  The regex mapping block  mapping regex  allows secrets through from the specified source to the specified destination if their secret name passes a regular expression check       Additional arguments     expression    string   required      The regular expression used to match secrets  names from the external system       Example  In this example  any secret in the GCP source whose name begins with  database   will be imported into Vault      hcl mapping regex     name           my map 1    source         my gcp source 1    destination    my dest 1    priority      1   expression      database                Priority  Priority works in a  first match  fashion where lower values are higher priority  To explain in more detail  consider the above metadata example with a second additional mapping   Below are two metadata mappings  The first   my map 1   has a priority of 1  This will only import the secrets into the destination  my dest 1  that contain both tag keys  database  and  importable   Each of these keys  values must also match to  users  and  true  respectively  The second   my map 2   has a priority of 2  Even though all the secrets in the first mapping would also qualify for the second mapping s filtering rule  those secrets will only be imported into  my dest 1  because of  my map 2  s lower priority  All remaining secrets that have the tag  importable  with a value of  true  will be imported into  my dest 2        hcl mapping metadata     name           my map 1    source         my gcp source 1    destination    my dest 1    priority      1    tags          database       users       importable     true         mapping metadata     name           my map 2    source         my gcp source 1    destination    my dest 2    priority      2    tags          importable     true