HashiCorp Vault

CLI

Login to Vault, and retrieve a token only

vault login \
  -method=userpass \
  -token-only username=$USERNAME password=$PASSWORD \
  -format=table
  • Use -token-only flag

Add JSON data as a secret

vault kv put $SECRET_PATH @$JSON_FILE
# e.g.
# vault kv put \
# secret/cq-playground/playground-spring-cloud-vault/dev \
# @/vault-secrets/config.json

Add a single key value pair as a secret

vault kv put $SECRET_PATH $key=$value
# e.g.
# vault kv put \
# secret/cq-playground/playground-spring-cloud-vault/dev \
# profile=dev

Partial update to existing data

vault kv patch $SECRET_PATH $key=$value
# e.g.
# vault kv patch \
# secret/cq-playground/playground-spring-cloud-vault/dev \
# profile=dev

Retrieve API help for paths

vault path-help $SECRET_PATH

Read a KV value of JSON format

vault kv get -format json -field $FIELD_NAME $SECRET_PATH
# e.g.
# vault kv get \
# -format json \
# -field data \
# sec_kv/cq-playground/playground-spring-cloud-vault/dev | jq`
  • Field can only be used on the first level of JSON property

Get the equivalent cURL of a Vault CLI command

vault kv get --output-curl-string $SECRET_PATH
  • Note: Vault service must be running and connection can be established

List all folders under the given path

vault kv list $SECRET_PATH

List all folders under the root

vault secrets list

List all versions of a KV secret

vault kv metadata get $SECRET_PATH | jq

Rollback to the specified version of a KV secret

vault kv rollback -version=$VERSION $SECRET_PATH

Web UI

  • A browser refresh will force re-authentication.

Terminal

  • Web UI terminal uses a simplified HTTP API syntax.

  • Use HTTP API as a guide

    e.g. read secret/subkeys/cq-playground/playground-spring-cloud-vault/dev

Spring Cloud Vault

Check reading secrets from Vault at startup

  • LeaseAwareVaultPropertySource.handleLeaseEvent

    // Spring Vault 2.3.2
// Print the secrets
Map<String, Object> secrets = doTransformProperties(flattenMap(created.getSecrets()));

Update and refresh config

  1. Update config in Vault

    vault kv put sec_kv/cq-playground/playground-spring-cloud-vault/dev @vault-secrets/config.json

  2. Refresh Application Context using Actuator refresh endpoint

    curl -X POST http://<app_context_path>/actuator/refresh

Notes

Secrets saved as JSON format is preferably flattened for easier retrieval

  • Nested structure, requiring further JSON parsing to obtain values

    // path: /secret/jenkins
{
  "artifactory": {
    "username": "john@gmail.com",
    "password": "invisible-secret"
  }
}

  • Flattened structure, use path to organize values, easier direct retrieval

    // path: /secret/jenkins/artifactory
{
  "username": "john@gmail.com",
  "password": "invisible-secret"
}

Seal / Unseal

When a Vault server is started, it starts in a sealed state. In this state, Vault is configured to know where and how to access the physical storage, but doesn't know how to decrypt any of it.

Unsealing

Unsealing is the process of obtaining the plaintext root key necessary to read the decryption key to decrypt the data, allowing access to the Vault. Prior to unsealing, almost no operations are possible with Vault. The only possible operations are to unseal the Vault and check the status of the seal.

  • How to unseal

    3 possible ways to unseal the Vault

    • Using Shamir Key Shares or Shards

    • Unsealing Vault with Auto Unseal (The auto-unseal feature delegates the unsealing process to a Key Management Service such as AWS KMS or GCP KMS.)

    • Unsealing with Transit Auto Unseal (The Transit seal configures Vault to use Vault's Transit Secret Engine as the autoseal mechanism.)

Sealing

Vault discard the master key and require another unseal to perform operations with vault. By default, Vault start in sealed state. At any time, you can seal vault using the API, CLI command or UI.

  • Use case

    • Seal the Vault to resolve data breach

References

JSONJava 21 (LTS)