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. Complete this setup once per rConfig instance, then create a Vault-backed credential set for each group of devices that should use it.

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
• Vault authentication token or AppRole credentials with appropriate 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

Step 1: Edit Environment Configuration

Open the rConfig .env file:

vim /var/www/html/rconfig8/current/.env

Step 2: Add HashiCorp Vault Configuration

Add or update the following lines:

VAULT_HASHICORP_ADDR=https://your-vault-server.com:8200
VAULT_HASHICORP_TOKEN=your_vault_token

Configuration Parameters:

• VAULT_HASHICORP_ADDR: The full URL of your HashiCorp Vault server (including port)
• VAULT_HASHICORP_TOKEN: Vault authentication token with read permissions for device secrets, sent as the X-Vault-Token header on every request

Note

rConfig authenticates to Vault using a single static token only. AppRole authentication, Vault namespaces, and per-credential-set tokens are not supported: every Vault-backed credential set in this rConfig instance shares the same VAULT_HASHICORP_TOKEN.

Step 3: Clear Application Cache

Save the file and clear the rConfig cache:

php /var/www/html/rconfig8/current/artisan rconfig:clear-all

Test Vault Connection

Step 1: Access Integration Settings

Navigate to Platform → Integrations in the main rConfig sidebar.

Step 2: Configure HashiCorp Vault Integration

Click Configure for the HashiCorp Vault integration.

Step 3: Test Connection

Click the Test Connection button to verify connectivity. A successful test shows a Connection test successful toast notification.

If errors occur:

1. Verify Vault server is accessible from rConfig server
2. Confirm authentication credentials are correct
3. Check Vault token has not expired
4. Ensure network connectivity and firewall rules allow access
5. Review Vault audit logs for authentication failures

Contact your identity administrator for Vault-specific issues before reaching out to rConfig support.

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.

Step 3: Configure Credential Set

Complete the form with the following information:

Credential Set 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 Save 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 generate new token and update .env:

vault token create -policy=rconfig-policy

Consider using AppRole for automatic token renewal.

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

Use AppRole authentication: Prefer AppRole over long-lived tokens for automated systems like rConfig.

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.

Common Gotchas

Common gotchas

• rConfig authenticates to Vault with a single static token defined in .env. There is no AppRole support and no per-credential-set token, every Vault-backed credential set in this instance shares the same VAULT_HASHICORP_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.
• Changes to .env (including VAULT_HASHICORP_ADDR and VAULT_HASHICORP_TOKEN) require php artisan rconfig:clear-all before they take effect.

Related Documentation

• Vault Credentials Overview - Understanding Key Vault integration
• Security Hardening Guide - Securing your rConfig deployment