HashiCorp Vault Integration

Introduction

The HashiCorp Vault Integration simplifies management and governance of non-human identities (NHIs) and secrets stored in HashiCorp Vault. With this integration you can centrally manage and update secrets across one or more HashiCorp Vault clusters, and rotate passwords or values more frequently. With fine-grained roles and permissions, audit, and logging, the HashiCorp Vault integration provides increased governance, visibility, and awareness of secrets managed in Vault without affecting development velocity or processes. The HashiCorp Vault integration is available on Secret Server Cloud, the Platform, and Secret Server On-Premise.

With the HashiCorp Vault connector, you can:

• Link external vaults to Secret Server.
• Identify and categorize non-human identities into folders.
• Manage and sync secrets from external vaults to a central Delinea vault.
• Control access by applying fine-grained permissions.
• Regularly rotate secrets to maintain a strong security posture.
• Use Secret Server to keep external vaults in sync.

What is HashiCorp Vault?

HashiCorp Vault is an open-source secrets management platform that provides policy-driven access control, encryption as a service, and centralized storage for tokens, passwords, certificates, and API keys. Secret Server supports three Vault editions: Community (self-hosted open-source), Enterprise (self-hosted commercial), and HCP Vault Dedicated (HashiCorp-managed cloud).

The Delinea HashiCorp Vault connector supports:

• Auth methods: Token and AppRole
• KV secrets engines: KV v2 (versioned) and KV v1 (un-versioned)

Key features of HashiCorp Vault include:

• Access Control: Policy-driven access using HCL policies bound to tokens or AppRole credentials.
• Auditing and Monitoring: Vault audit devices log every request and response for compliance and forensics.
• Encryption as a Service: The Transit engine provides on-demand encryption/decryption without exposing keys.
• Multiple Secrets Engines: KV (key/value), database credentials, PKI, SSH, cloud provider credentials, and more.
• Namespaces (Enterprise/HCP): Multi-tenant isolation within a single Vault cluster.
• Dynamic Secrets: Generate short-lived credentials for databases, cloud providers, and other systems on demand.

To learn more, see the HashiCorp Vault documentation.

Connecting with HashiCorp Vault—The Credential Setup Process

The following two-part procedure makes HashiCorp Vault clusters available in Secret Server.

Creating a Token or AppRole in HashiCorp Vault

HashiCorp Vault token and AppRole credentials must be created using the Vault CLI or API. The Vault Web UI exposes only the auth-method configuration, not token or AppRole credential generation.

Option A: Token Auth

Run the following command against your Vault cluster:

vault token create -policy=<policy-name> -ttl=0

• Community/Enterprise: -ttl=0 produces a non-expiring token.
• HCP Vault Dedicated: Root tokens expire after 6 hours and regular tokens last approximately 32 days. AppRole is recommended for HCP because of the limited token lifetime.

Option B: AppRole Auth

AppRole authentication is preferred for production use because RoleId and SecretId can be rotated independently, and AppRole credentials are not subject to the short token TTLs imposed on HCP Vault Dedicated.

Enable the AppRole auth method and create the role:

vault auth enable approle
                vault write auth/approle/role/<role-name> \
                token_policies=<policy-name> \
                secret_id_ttl=0 \
            secret_id_num_uses=0

Read the RoleId and generate a SecretId:

vault read auth/approle/role/<role-name>/role-id
            vault write -force auth/approle/role/<role-name>/secret-id

secret_id_ttl=0 and secret_id_num_uses=0 produce a non-expiring SecretId. Record the role name—it is required by Secret Server for SecretId rotation.

Required Vault Policies

The token or AppRole used by Secret Server must be bound to a Vault policy granting the capabilities the integration requires. Use the policy that matches the KV engine version on the mount you intend to link.

KV v2 Policy

path "secret/data/*" {
                capabilities = ["create", "read", "update"]
                }
                path "secret/metadata/*" {
                capabilities = ["read", "list", "update"]
                }
                path "secret/delete/*" {
                capabilities = ["update"]
                }
            

KV v1 Policy

path "secret/*" {
                capabilities = ["create", "read", "update", "list"]
                }
            

Vault Discovery Policy (Enterprise and HCP only)

Required for the Automatic list input type so Secret Server can enumerate namespaces and mounts:

path "sys/namespaces" {
                capabilities = ["list"]
                }
                path "sys/namespaces/*" {
                capabilities = ["list"]
                }
                path "sys/mounts" {
                capabilities = ["read"]
            }

HCP Cross-Namespace Discovery and Operations

For HCP clusters where the credential must reach mounts across child namespaces:

# Child namespace mount discovery
                path "+/sys/mounts" {
                capabilities = ["read"]
                }
                path "+/sys/namespaces" {
                capabilities = ["list"]
                }
                path "+/sys/namespaces/*" {
                capabilities = ["list"]
                }

                # Cross-namespace secret operations
                path "+/+/data/*" {
                capabilities = ["create", "read", "update"]
                }
                path "+/+/metadata/*" {
                capabilities = ["read", "list", "update"]
                }
                path "+/+/delete/*" {
                capabilities = ["update"]
                }
                path "+/+/*" {
                capabilities = ["create", "read", "update", "list"]
            }

Creating the HashiCorp Vault Credential Secret in Secret Server

Secret Server provides two HashiCorp Vault credential templates—pick the one that matches the auth method created in Vault.

HashiCorp Vault (Token) template

1. Access Secret Server.
2. Create a new secret using the HashiCorp Vault (Token) template.
3. Fill in the following fields:
   • Secret Name: Give the secret an appropriate display name.
   • URI: The Vault cluster URL (for example, https://vault.example.com:8200).
   • Namespace: The Vault namespace. Required for HCP, optional for Enterprise, leave blank for Community.
   • Token: The Vault token created in Option A: Token Auth.
   • Optionally, fill in the Notes field.
   • Optionally, change the Site field to one you need, otherwise leave as Default.
4. Select Create Secret to save your changes.

HashiCorp Vault (AppRole) template

1. Access Secret Server.
2. Create a new secret using the HashiCorp Vault (AppRole) template.
3. Fill in the following fields:
   • Secret Name: Give the secret an appropriate display name.
   • URI: The Vault cluster URL.
   • Namespace: The Vault namespace. Required for HCP, optional for Enterprise, leave blank for Community.
   • Role Name: The AppRole role name created in Option B: AppRole Auth. Required for SecretId rotation.
   • RoleId: The RoleId returned by vault read auth/approle/role/<role-name>/role-id.
   • SecretId: The SecretId returned by vault write -force auth/approle/role/<role-name>/secret-id.
   • Optionally, fill in the Notes field.
   • Optionally, change the Site field to one you need, otherwise leave as Default.
4. Select Create Secret to save your changes.

Firewall and Network Requirements

Secret Server communicates with HashiCorp Vault over HTTPS on the configured Vault listener port (default 8200).

• HCP Vault Dedicated: Vault endpoints are internet-accessible. No Distributed Engine is required for connectivity.
• Community / Enterprise (self-hosted): If the Vault cluster sits on a private network unreachable from the Secret Server web server, a Distributed Engine with network access to the cluster is required. Assign the vault to a non-local Site so the Distributed Engine handles the calls. See Distributed Engine Support.
• Self-signed certificates: Enable Skip Certificate Validation on the vault connection if the cluster presents self-signed TLS certificates.

Requirements for self-hosted clusters reached directly from Secret Server:

• Outbound HTTPS to the Vault cluster's listener address (default port 8200).
• DNS resolution of the cluster's hostname from the Secret Server web server (or from the Distributed Engine, if routed).
• If using a proxy for outbound traffic, ensure the proxy allows connections to the Vault cluster on the configured port.

Creating an External Vault Link

1. Access Secret Server.
2. From the left navigation panel, select Secrets > External Secrets. The External Secrets page appears.
3. Click the Create dropdown button and select Create External Vault Link. The Create External Vault Link page appears.
4. For Type, select HashiCorp Vault.
5. For Edition, select one of:
   • HCP—for HCP Vault Dedicated clusters.
   • Enterprise—for self-hosted Enterprise clusters.
   • Community—for self-hosted Community (OSS) clusters.
6. Optionally enable Skip certificate validation if the cluster presents self-signed TLS certificates.
7. For Site, leave at the default for operations to run on the Secret Server web server, or choose a non-local Site to route through a Distributed Engine. See Distributed Engine Support.
8. For Credential secret, select the No secret selected link and choose the secret you created previously. A green Connected indicator confirms the credential can reach the cluster.
9. For Input type, choose one of the following:
   • Automatic list: Secret Server queries the cluster and presents a checklist of discovered namespaces and KV mounts. Click to select the checkboxes for the desired mounts.
   • Manual entry: Provide the mount details directly:
     1. KV mount: The secrets engine mount path (for example, secret).
     2. KV version: Select KV v2 or KV v1.
     3. External name: The identifier Secret Server uses internally. Defaults to (<namespace>)/<mount>. This name MUST exactly match the mount path in Vault to correctly link them.
     4. Display name: Automatically matches the External name unless you change it manually.
10. Select Save.
11. You are prompted to synchronize the external vault. This step performs a pull on the vault and then a push on each active and linked external secret. This pulls all the secrets from the linked Vault mount into the Secret Server UI.
12. Synchronize the vault. The external vault summary page will show these results:
    • Name of the vault.
    • State: enabled or disabled.
    • Last pull status.
    • Number of external secrets.
    • Credential secret used.
13. Select the External Secrets tab to view the list of external secrets.
14. Change the Status to All states to view the list of external secrets. All external secrets are initially disabled. This means no secrets are synchronized from Secret Server to the Vault cluster.

Namespace Behavior by Edition

Vault Discovery (Automatic List)

When Automatic list is chosen, Secret Server queries the Vault cluster using the credential and presents the namespaces and KV mounts it can reach.

• Community: Mount discovery only—does not support namespaces.
• Enterprise: Namespace and mount discovery.
• HCP: Namespace and mount discovery, with the HCP Cross-Namespace Discovery and Operations policy letting discovery span child namespaces.

If the credential lacks namespace-discovery permissions, the list falls back to showing only the authenticated namespace. In that case, use Manual entry instead.

Distributed Engine Support

The cross-vault Distributed Engine concept and procedure are documented on the External Secrets parent page. HashiCorp-specific guidance:

• HCP Vault Dedicated: Vault endpoints are internet-accessible. No Distributed Engine is required for connectivity.
• Community / Enterprise (self-hosted): If the Vault cluster sits on a private network unreachable from the Secret Server web server, assign the vault to a non-local Site so a Distributed Engine on the cluster's network handles the calls.

To route a HashiCorp vault through a Distributed Engine:

1. Create a non-local Site in Admin > Distributed Engine.
2. Register and activate an engine on that Site with network reachability to the Vault cluster.
3. Edit the external vault and set the Site dropdown to the non-local Site.

Managing External Secrets

1. Log in to Secret Server.
2. Navigate to Secrets > External Secrets. The External Secret grid appears. After you have linked at least one external vault, you will see a list of external secrets here.
3. In the grid you can:
   • Search for a specific secret.
   • View all secrets, enabled or disabled.
   • View only "enabled" or "disabled" secrets.
   • View or manage permissions.
   • View audit events.
   • View the log.
4. Select a secret in the grid. Now, you can perform a few more actions:
   • Set remote value: Sets new values on the external secret in HashiCorp Vault.
   • View remote value: View the current values on the external secret in HashiCorp Vault.
   • Push: Propagates the changes made through edits to the secret(s).
   • Edit: Modify the secret and set properties.
   • Enable or disable synchronization for the secret.
   • Select a secret to link to. That secret serves as the master secret in Secret Server.
   • Perform Remote Password Changing (RPC) on the master, which propagates to all the enabled linked external secrets.
   • Transform, which allows you to select the fields you want updated on the external secret(s).

Transforms are defined in the secret template for the master secret. For example, Password (password) links the password field from the master secret and updates all linked enabled external secrets with the value of the password field.

You can also define a string format and insert field values from the linked secret using $secret.slug.notation. For example, Password: $secret.slug.password sets the external secret value as password 1234pass, where 1234pass is the actual password from the master secret. Transform allows you to copy and paste the slug name or simply click on the + sign to add it in the box below.

HashiCorp Vault Stores Key/Value Records

Unlike Azure Key Vault, AWS Secrets Manager, and Google Cloud Secret Manager—which store one value per secret—a HashiCorp Vault path stores multiple key/value pairs. When you create or manage an external secret pointing at a HashiCorp Vault path, Secret Server presents a Mappings table for managing those keys instead of a single value field. Each row in the table maps a master secret field (or a $secret.slug.notation expression) to a key on the Vault path.

Bulk Operations with the External Secret Grid

The external secret grid provides a central location in Secret Server to manage external secrets. When selecting external secrets in the grid, you can select to push or edit these items all at once, which is a bulk operation. This is useful for linking multiple external secrets from one or more Vault mounts to a single master secret.

Performing a bulk operation on multiple external secrets:

1. Select all or a few secrets from the grid.
2. Push and Edit are now available actions for these secrets:
   • Push allows for changes from the master secret or secrets in Secret Server to affect the linked secrets in HashiCorp Vault.
   • Edit allows you to perform additional bulk actions such as:
     • Toggle the Synchronization enabled/disabled state.
     • Select Apply to all or Cancel.

Simultaneously Creating Master and External Secrets in HashiCorp Vault

How to create a new master secret along with an external secret at the same time in HashiCorp Vault:

1. Access Secret Server.
2. Create a secret using any template. For this example, use the Password secret template.
3. Fill in the secret name, user name, and password fields and select Create Secret. The secret loads automatically on the screen.
4. Select External Secrets from the left-hand menu.
5. Click Create, then select Create external secret from the drop-down.
6. Type in the name of the External secret. This will become the path on the selected Vault mount.
7. Choose the External vault where you want to create this secret from the drop-down.
8. Choose whether to enable Synchronization or not by selecting the checkbox.
9. For Linked Secret, click No secret selected and choose the secret you just created.
10. In the Mappings table, add a row for each Vault key you want populated on the external secret. From the Merge secret field drop-down, choose the master field (for example, Password (password)) to sync from the master secret, or enter a $secret.slug.notation string format to construct a value.
11. Select Save to keep your changes.

KV v1 and v2 Behavior Differences

The HashiCorp Vault KV secrets engine has two versions, and the behavior of Secret Server writes differs between them:

• KV v2 (versioned): When Secret Server writes a new version, the previous version is marked deleted. It remains stored in metadata and is recoverable through Vault's version history.
• KV v1 (un-versioned): Writes overwrite in place—there is no version history.

The Vault policy required for each engine differs. See KV v2 Policy and KV v1 Policy for the capability set each version requires.