Configure HashiCorp Vault for secured intercept

Audience: Platform engineers / secrets management owners
Time: ~20 min
Prerequisites: Secured intercept overview, Bouncer on Kubernetes or Docker, a Vault cluster you operate

Use this guide when upstream credentials already live in HashiCorp Vault and you want the Bouncer to read them at intercept time while the Control Plane stores path references only.

What you configure

Before you start

1. Enable Settings → Feature Flags → flags.crypto.dual_custody_intercept (default off).
2. Register at least one Bouncer in Settings → Bouncer Management.
3. Confirm Policy Bridge sync is healthy.

Step 1 — Prepare Vault paths and policy (~10 min)

1. Choose a KV mount (v1 or v2) for upstream credentials, for example: kv/data/production/payments-api/upstream-tls.
2. Store the upstream credential under a value field (string) — this matches the envelope delegate read contract.
3. Create a Vault policy that allows read only on the path prefix your security team approves, for example:

path "kv/data/production/payments-api/*" {
  capabilities = ["read"]
}

4. Configure a Vault auth method for the Bouncer workload (common choices):
   • Kubernetes auth (Bouncer pod authenticates to Vault)
   • AppRole (role ID + secret ID injected from your secrets store)
   • JWT/OIDC (if your platform issues workload tokens Vault trusts)

Troubleshooting: permission denied from Vault → verify the auth role is bound to the correct service account / namespace and the policy is attached.

Step 2 — Inject Vault connectivity into the Bouncer (~5 min)

Never place long-lived root tokens in plain Helm values. Use your platform secrets manager.

Mount the token from a Kubernetes Secret (or external secrets operator) into the Bouncer container environment. Restart the Bouncer after changes.

Step 3 — Register the provider in the Control Plane (~3 min)

curl -sS -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "$CONTROL_PLANE_URL/v1/crypto/settings" \
  -d '{
    "provider": "vault_delegate",
    "vault_address": "https://vault.example.com:8200",
    "vault_namespace": "payments-prod",
    "notes": "Production Vault delegate"
  }'

Or use Settings → Cryptographic Provider when the feature flag is on.

Step 4 — Register envelope metadata (~5 min)

The ciphertext_ref field holds the Vault path to read — not encrypted bytes.

curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "$CONTROL_PLANE_URL/v1/crypto/envelope-secrets" \
  -d '{
    "logical_path": "protected-resources/payments-api/upstream-tls",
    "key_id": "payments-prod",
    "ciphertext_ref": "kv/data/production/payments-api/upstream-tls",
    "provider": "vault_delegate"
  }'

logical_path is your operator label for policies and protected resources. key_id may hold your Vault namespace or a logical key name — it is not the secret itself.

List registrations:

curl -sS -H "Authorization: Bearer $TOKEN" \
  "$CONTROL_PLANE_URL/v1/crypto/envelope-secrets"

Step 5 — Verify (~5 min)

1. From a jump host with Vault CLI (optional), confirm vault kv get on the path returns the expected shape before enabling production traffic.
2. Send test traffic through the Bouncer on a route that uses the registered logical_path.
3. Review Audit — decision events must not contain secret values or Vault tokens.

Troubleshooting: Upstream connection fails after allow → check Vault token TTL/renewal and TLS trust to Vault. 403 on Control Plane crypto APIs → enable the dual-custody feature flag.

Token and path hygiene

• Prefer short-lived tokens with automatic renewal (Vault Agent or CSI driver).
• Rotate tokens on your standard schedule; update the Kubernetes Secret — not the Control Plane envelope row unless the path changes.
• Keep path allowlists narrow; add new upstream credentials under approved prefixes only.

Related guides

• Secured intercept overview
• Configure AWS KMS
• Cryptographic workload identity
• Customer security guide