HashiCorp Vault Setup

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.

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

Device credentials must be stored in Vault with the following structure:

{
  "username": "device_username",
  "password": "device_password",
  "enable_password": "enable_password"
}

Example Vault path:

secret/data/network/devices/router1

Note

The key names (username, password, enable_password) can be customized in the Device Credential Set configuration if your Vault uses different field 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_ADDR=https://your-vault-server.com:8200
VAULT_TOKEN=your_vault_token
VAULT_NAMESPACE=your_namespace

Configuration Parameters:

• VAULT_ADDR: The full URL of your HashiCorp Vault server (including port)
• VAULT_TOKEN: Vault authentication token with read permissions for device secrets
• VAULT_NAMESPACE: Vault namespace (optional, leave blank if not using namespaces)

Alternative: AppRole Authentication

If using AppRole instead of token authentication:

VAULT_ADDR=https://your-vault-server.com:8200
VAULT_ROLE_ID=your_role_id
VAULT_SECRET_ID=your_secret_id
VAULT_NAMESPACE=your_namespace

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 Settings > Integrations in the rConfig interface.

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.

Successful connection output:

✓ Connection successful
✓ Authentication validated
✓ Read permissions confirmed

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 Settings > 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)
• This path must exist in Vault and contain the device credentials

Field Mapping:

• Username Key: Vault key containing username (default: username)
• Password Key: Vault key containing password (default: password)
• Enable Password Key: Vault key containing enable password (default: enable_password)

Tip

If your Vault secrets use different key names (e.g., user, pass, enable), 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 \
  username=admin \
  password=SecurePassword123 \
  enable_password=EnablePass456

For devices with unique credentials:

# Router 1
vault kv put secret/network/devices/router1 \
  username=admin \
  password=Router1Pass \
  enable_password=Router1Enable

# Router 2
vault kv put secret/network/devices/router2 \
  username=admin \
  password=Router2Pass \
  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 \
  username=admin \
  password=NewSecurePassword \
  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=username secret/network/devices/router1
vault kv get -field=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.

Related Documentation

• Vault Credentials Overview - Understanding Key Vault integration
• Device Credentials - Managing device credentials in rConfig
• Connection Profiles - Configuring device connections
• Security Best Practices - Securing your rConfig deployment