HashiCorp Vault Setup

The HashiCorp Vault integration enables rConfig V8 to securely retrieve device credentials from HashiCorp Vault during connection operations. This guide covers the configuration of rConfig to communicate with your HashiCorp Vault instance and the setup of vault-backed device credentials.

When to Use This Page

Use this page when you want device credentials pulled live from HashiCorp Vault at connection time instead of stored directly in rConfig. Set up the connection once per rConfig instance, then create a Vault-backed credential set for each group of devices that should use it. HashiCorp Vault can be switched on alongside the other supported vaults.

Caution

Good working knowledge of HashiCorp Vault in your environment is required. If you are unsure of your environment, contact your identity or security administrator. rConfig support for vault system configuration is limited.

Prerequisites

• HashiCorp Vault instance installed and operational
• A Vault authentication token with appropriate read permissions
• Secrets stored in Vault with device credentials
• Administrator access to rConfig V8
• Network connectivity between rConfig server and Vault API endpoint

Vault Secret Structure

By default, rConfig looks for a secret with these key names:

{
  "device_username": "admin",
  "device_password": "your_device_password",
  "device_enable_password": "your_enable_password"
}

Example Vault path (KV v2):

secret/data/network/devices/router1

Note

The key names (device_username, device_password, device_enable_password) can be customized per credential set in the Field Mapping fields if your Vault secrets use different key names.

Configure rConfig V8

From V8.4.2, the Vault connection is set up in the rConfig UI. Nothing needs editing on the server and no cache clear is needed.

Step 1: Open the HashiCorp Vault page

Navigate to Platform → Integrations. In the Device Credentials section, click Configure next to Hashicorp Vault.

Step 2: Enter the connection settings

Field	Required	Notes
Vault address	Yes	Full URL of the Vault server, including the port, for example https://vault.example.com:8200.
Namespace	No	Vault Enterprise and HCP only. Sent as the X-Vault-Namespace header. Leave blank otherwise.
Token	Yes	A Vault token with read access to the device secrets, sent as the X-Vault-Token header. Once saved, the box shows Saved. Leave blank to keep it. Type a new token to replace it.

Turn on Use this vault for credential sets. rConfig won’t save it switched on until the address and token are filled in.

Note

rConfig authenticates to Vault with a single static token. AppRole and per-credential-set tokens are not supported: every Vault-backed credential set in this instance shares the same token and namespace.

Step 3: Test, then save

Click Test Connection. rConfig calls /v1/sys/health with the values in the form, including any you haven’t saved yet, and shows the response. Then click Save.

Upgrading from .env settings

If you set VAULT_HASHICORP_ADDR, VAULT_HASHICORP_TOKEN and VAULT_SERVICE_NAME=hashicorp in .env before V8.4.2, Vault keeps working after the upgrade. The page shows a notice that its settings are read from .env, with the address filled in and the token marked as saved. Click Save to store them in rConfig. After that, rConfig ignores the VAULT_HASHICORP_* lines and you can remove them from .env.

Create Vault Credential Set

Step 1: Access Device Credentials

Navigate to System Settings → Security & Access → Device Credentials.

Step 2: Add Vault Credential Set

Click the Add Vault Credential Set button. If more than one vault is switched on, pick Hashicorp Vault in the Vault dropdown.

Step 3: Configure Credential Set

Complete the form with the following information:

Credential Name:

• Descriptive name for the credential set (e.g., “Production Routers - Vault”)

Vault Endpoint URL:

• Full path to the secret in Vault (e.g., secret/data/network/devices/router1 for a KV v2 mount named secret)
• This path must exist in Vault and contain the device credentials

Field Mapping:

• Username Key: Vault key containing username (default: device_username)
• Password Key: Vault key containing password (default: device_password)
• Enable Password Key: Vault key containing enable password (default: device_enable_password)

Tip

If your Vault secrets use different key names, update the field mappings accordingly.

Click Add to create the credential set.

Step 4: Verify Creation

After saving, you will see the new credential set with a Vault icon next to it, indicating it retrieves credentials from HashiCorp Vault.

Configure Device to Use Vault Credentials

Step 1: Edit Device

Navigate to Devices and select a device to edit.

Step 2: Select Vault Credential Set

In the device edit form:

1. Locate the Credential Set dropdown
2. Select the newly created Vault credential set
3. Note that username and password fields are no longer visible (credentials will be retrieved from Vault)

Step 3: Save Device Configuration

Click Save to apply the Vault credential set to the device.

Step 4: Test Connectivity

Use the debug command or connectivity test feature to verify rConfig can successfully:

1. Retrieve credentials from Vault
2. Authenticate to the device
3. Execute commands or download configurations

Vault Secret Management

Creating Secrets for Multiple Devices

For multiple devices sharing the same credentials:

# Using Vault CLI
vault kv put secret/network/devices/shared \
  device_username=admin \
  device_password=SecurePassword123 \
  device_enable_password=EnablePass456

For devices with unique credentials:

# Router 1
vault kv put secret/network/devices/router1 \
  device_username=admin \
  device_password=Router1Pass \
  device_enable_password=Router1Enable

# Router 2
vault kv put secret/network/devices/router2 \
  device_username=admin \
  device_password=Router2Pass \
  device_enable_password=Router2Enable

Updating Credentials

When credentials change in Vault, rConfig automatically retrieves the updated values on the next device operation: no rConfig configuration changes required.

# Update secret in Vault
vault kv put secret/network/devices/router1 \
  device_username=admin \
  device_password=NewSecurePassword \
  device_enable_password=NewEnablePassword

Troubleshooting

Connection test fails

Symptoms:

• Test Connection button returns error
• Cannot authenticate to Vault

Resolution:

Check Vault server accessibility:

curl -k https://your-vault-server.com:8200/v1/sys/health

Verify token validity:

vault token lookup

Check token permissions:

vault token capabilities secret/data/network/devices

Device authentication fails

Symptoms:

• Device connection fails
• Error indicates invalid credentials

Resolution:

Verify secret exists in Vault:

vault kv get secret/network/devices/router1

Check field mappings match Vault secret structure:

• Ensure username, password, and enable_password keys exist
• Verify field mapping configuration in Device Credential Set

Test credential retrieval manually:

vault kv get -field=device_username secret/network/devices/router1
vault kv get -field=device_password secret/network/devices/router1

Vault endpoint URL errors

Symptoms:

• Error indicates path not found
• Secret retrieval fails

Resolution:

Verify Vault path format:

• KV v1: secret/network/devices/router1
• KV v2: secret/data/network/devices/router1

Check Vault version:

vault secrets list -detailed

Ensure path includes correct prefix based on KV version.

Token expired

Symptoms:

• Connection test succeeds initially but fails later
• Authentication errors after period of time

Resolution:

Check token TTL:

vault token lookup

Renew token:

vault token renew

Or create a new token and paste it into the Token box on the HashiCorp Vault page, then click Save:

vault token create -policy=rconfig-policy

Since AppRole isn’t supported, renewal is either a manual vault token renew on a long-lived token, or a new token entered on the HashiCorp Vault page when the old one nears expiry.

Permission denied errors

Symptoms:

• Vault returns “permission denied” errors
• Cannot read secrets despite correct path

Resolution:

Verify token policy allows reading secrets:

# Example policy for rConfig
path "secret/data/network/devices/*" {
  capabilities = ["read", "list"]
}

Apply policy to token:

vault policy write rconfig-policy policy.hcl
vault token create -policy=rconfig-policy

Security Best Practices

Restrict token permissions: Grant read-only access to only the secret paths needed by rConfig.

Enable Vault audit logging: Monitor credential access patterns and detect anomalies.

Rotate tokens regularly: Set appropriate TTL values and implement token renewal processes.

Use TLS encryption: Always use HTTPS for Vault communications (verify with valid certificates).

Namespace isolation: Use Vault namespaces to isolate rConfig credentials from other applications. rConfig sends one namespace for the whole instance, so keep all its secrets in that namespace.

Common Gotchas

Common gotchas

• rConfig authenticates to Vault with a single static token. There is no AppRole support and no per-credential-set token: every Vault-backed credential set in this instance shares the same token.
• The default Field Mapping keys are device_username, device_password, and device_enable_password, not the generic username/password/enable_password. If your Vault secret uses different key names, update the Field Mapping fields to match rather than renaming the keys in Vault.
• KV v2 mounts require the /data/ segment in the path (secret/data/...). Forgetting it is the most common cause of “path not found” errors, since KV v1 and v2 use different URL structures for the same logical path.
• Once the HashiCorp Vault page has been saved, the VAULT_HASHICORP_* lines in .env are ignored. Change the token or address on the page, not in .env.
• Switching Use this vault for credential sets off stops every Vault-backed credential set until it’s back on.

Related Documentation

• Vault Credentials Overview - Understanding Key Vault integration
• Idira (CyberArk) Setup and Delinea Secret Server Setup - the other supported vaults
• Security Hardening Guide - Securing your rConfig deployment