vHSM Proxy quickstart
Learn to start vHSM Proxy and read secrets from a specified path in the vHSM server through vHSM Proxy.
vHSM Proxy is designed to simplify and accelerate the adoption of vHSM by providing a scalable, lightweight way for applications to interact with vHSM server seamlessly. Acting as an API proxy, vHSM Proxy streamlines authentication and token management, enabling applications to integrate with vHSM without handling complex auth workflows directly.
vHSM Proxy runs as a client-side daemon and offers the following key capabilities:
Auto-Auth: Automatically authenticates to vHSM and handles the lifecycle of dynamic secrets, including token acquisition and renewal.
API Proxy: Transparently proxies requests to vHSM’s API, with the option to use—or enforce the use of—an automatically authenticated token for all client interactions.
Caching: Supports local caching of responses for newly created tokens and leased secrets, reducing latency and minimizing redundant requests. It also manages the renewal of cached tokens and leases automatically.
Prerequisites
Install jq for better readability of the JSON output
1. Create a directory for storing test files and configuration.
mkdir -p $HOME/vhsm-test && cd $HOME/vhsm-test2. Create a mock dataset data.json representing a customer record, using an editor of your choice:
{
"organization": "Enclaive",
"customer_id": "ABXX2398YZPIE7391",
"region": "US-West",
"zip_code": "94105",
"type": "premium",
"contact_email": "[email protected]",
"status": "active"
}Upload the test data to the vHSM KV v2 secrets engine:
vhsm kv put secret/customers/enclaive @data.json4. Create the proxy configuration file vhsm-proxy-config.json that defines API endpoint for the client application to send requests to rather than VAULT_ADDR.
pid_file = "./pidfile"
vault {
address = "http://127.0.0.1:8200"
tls_skip_verify = true
}
auto_auth {
method {
type = "token_file"
config = {
token_file_path = "$HOME/.vault-token"
}
}
sink "file" {
config = {
path = "$HOME/vault-proxy"
}
}
}
listener "tcp" {
address = "127.0.0.1:8100"
tls_disable = true
}
api_proxy {
use_auto_auth_token = true
enforce_consistency = "always"
}
Note: The
vaultandauto_authstanzas in the vHSM Proxy and vHSM Agent configurations are identical; however, you must definelistenerandapi_proxystanzas for vHSM Proxy.
Start the vHSM Proxy.
vhsm proxy -config=vault-proxy-config.jsonThe output is similar to:
==> vHSM Proxy started! Log data will stream in below:
==> vHSM Proxy configuration:
Api Address 1: http://127.0.0.1:8100
Cgo: disabled
Log Level:
Version: Vhsm v1.3.7-0, built 2025-01-29T15:11:42Z
Version Sha: 00d245ed8143844db6761fd947433aab237f914f+CHANGES
2025-03-10T18:28:43.946+0530 [INFO] proxy.sink.file: creating file sink
2025-03-10T18:28:43.947+0530 [INFO] proxy.sink.file: file sink configured: path=/Users/rkodhandapani/vault-token-via-agent mode=-rw-r-----
2025-03-10T18:28:43.947+0530 [INFO] proxy.sink.server: starting sink server
2025-03-10T18:28:43.947+0530 [INFO] proxy.auth.handler: starting auth handler
2025-03-10T18:28:43.947+0530 [INFO] proxy.auth.handler: authenticating
2025-03-10T18:28:43.949+0530 [INFO] proxy.auth.handler: authentication successful, sending token to sinks
2025-03-10T18:28:43.949+0530 [INFO] proxy.auth.handler: not starting token renewal process, as token has unlimited TTOpen another command terminal and send an API request to the vHSM Proxy.
Read the secrets at
secret/customers/enclaivevia the proxy address.curl -s http://127.0.0.1:8100/v1/secret/data/customers/enclaive \ | jq -r ".data.data"Output:
{ "contact_email": "[email protected]", "customer_id": "ABXX2398YZPIE7391", "organization": "Enclaive", "region": "US-West", "status": "active", "type": "premium", "zip_code": "94105" }A token was automatically attached to the request by the vHSM Proxy because you set the
use_auto_auth_tokenparameter totruein the configuration.Read the secrets again. This time, vHSM's Proxy returns the cached secrets.
curl --verbose -s http://127.0.0.1:8100/v1/secret/data/customers/enclaive \ | jq -r ".data.data"Use the
--verboseor-voption with the cURL command so that you can see more detail.* Trying 127.0.0.1:8100... * Connected to 127.0.0.1 (127.0.0.1) port 8100 (#0) > GET /v1/secret/data/customers/enclaive HTTP/1.1 > Host: 127.0.0.1:8100 > User-Agent: curl/8.1.2 > Accept: */* > < HTTP/1.1 200 OK < Cache-Control: no-store < Content-Length: 465 < Content-Type: application/json < Date: Mon, 10 Mar 2025 15:43:34 GMT < Strict-Transport-Security: max-age=31536000; includeSubDomains < X-Cache: MISS < { [465 bytes data] * Connection #0 to host 127.0.0.1 left intact { "contact_email": "[email protected]", "customer_id": "ABXX2398YZPIE7391", "organization": "Enclaive", "region": "US-West", "status": "active", "type": "premium", "zip_code": "94105" }Update the secrets to see what happens.
vhsm kv patch secret/customers/enclaive "customer_since"="2011"Read the secrets again through vHSM Proxy.
curl --verbose http://127.0.0.1:8100/v1/secret/data/customers/enclaive \ | jq -r ".data.data"The output is similar to:
* Connected to 127.0.0.1 (127.0.0.1) port 8100 (#0) > GET /v1/secret/data/customers/enclaive HTTP/1.1 > Host: 127.0.0.1:8100 > User-Agent: curl/8.1.2 > Accept: */* > < HTTP/1.1 200 OK < Cache-Control: no-store < Content-Length: 489 < Content-Type: application/json < Date: Mon, 10 Mar 2025 15:52:55 GMT < Strict-Transport-Security: max-age=31536000; includeSubDomains < X-Cache: MISS < { [489 bytes data] 100 489 100 489 0 0 58612 0 --:--:-- --:--:-- --:--:-- 238k * Connection #0 to host 127.0.0.1 left intact { "contact_email": "[email protected]", "customer_id": "ABXX2398YZPIE7391", "customer_since": "2011", "organization": "Enclaive", "region": "US-West", "status": "active", "type": "premium", "zip_code": "94105" }Press Ctrl + C to stop the running vHSM Proxy.
Last updated
Was this helpful?