HashiCorp Vault

HashiCorp Vault supports multiple secret engines. Secret Agent supports fetching secrets from the KV (V2) Secrets Engine only.

Secret Agent can authenticate with the HashiCorp Vault server using one of the following methods:

Token auth method

This method authenticates with a Vault token. You must generate a Vault token and store it in a file. Secret Agent reads the token from the file for every fetch request, so if you update the token in the file, Secret Agent uses the new token for the next request. The file must have permissions that restrict read access to the Secret Agent process.

Sample configuration file:

service:
  tcp:
    endpoint: 0.0.0.0:3005

secret-manager:
  vault:
    endpoint: http://127.0.0.1:8200
    token-file: /path/to/token/file
    namespace: asd # (optional) Vault Enterprise namespace
    convert-to-base64: false
    resources:
      mount: mysecrets
      secret: TestingSecret
      version: 0 # 0 means latest version

log:
  level: info

To configure Secret Agent with the token auth method:

Enable KV (V2) Secrets Engine in Vault with mount (path) mysecrets.
Create a secret under the mysecrets mount. In this example, the secret is named TestingSecret.
Add one or more key-value pairs to TestingSecret.
Generate a Vault token and store it in a file. In this example, the file is /path/to/token/file.
Install Secret Agent on the machine.
Configure Secret Agent to fetch secrets from Vault.
Start Secret Agent.

Username and password auth method

To authenticate with Vault using a username and password, create a user in Vault and store the password in a file. Secret Agent reads the password from the file and uses it to authenticate. Specify the username in the Secret Agent configuration file.

When Secret Agent authenticates with this method, it creates a Vault token to fetch secrets. If the token is renewable, Secret Agent automatically renews it before it expires. If the token is not renewable, Secret Agent creates a new token when the existing one expires, using the same username and password.

Sample configuration file:

service:
  tcp:
    endpoint: 0.0.0.0:3005

secret-manager:
  vault:
    endpoint: http://127.0.0.1:8200
    username: testuser
    password-file: /path/to/password/file
    namespace: asd # (optional) Vault Enterprise namespace
    convert-to-base64: false
    resources:
      mount: mysecrets
      secret: TestingSecret
      version: 0 # 0 means latest version

log:
  level: info

To configure Secret Agent with the username and password auth method:

Enable KV (V2) Secrets Engine in Vault with mount (path) mysecrets.
Create a secret under the mysecrets mount. In this example, the secret is named TestingSecret.
Add one or more key-value pairs to TestingSecret.
Create a username and password in Vault. In this example, the username is testuser and the password is stored in /path/to/password/file.
Verify that testuser has policies attached that allow reading TestingSecret.
Install Secret Agent on the machine.
Configure Secret Agent to fetch secrets from Vault.
Start Secret Agent.

Sample Vault policy to read secrets under the mysecrets mount:

path "mysecrets/*" {
  capabilities = ["read", "list"]
}

TLS certificates auth method

With this method, no tokens or passwords are stored on the machine. The TLS certificates auth method authenticates using SSL/TLS client certificates that are either signed by a CA or self-signed. The Vault server determines whether a matching certificate exists to authenticate Secret Agent. On success, the auth method returns a token. Token renewal works the same way as the username and password auth method.

Sample configuration file:

service:
  tcp:
    endpoint: 0.0.0.0:3005

secret-manager:
  vault:
    endpoint: https://127.0.0.1:8200
    tls-auth-mount: authcerts
    client-cert-file: /path/to/client/cert/file
    client-key-file: /path/to/client/key/file
    ca-file: /path/to/ca/file
    namespace: asd # (optional) Vault Enterprise namespace
    convert-to-base64: false
    resources:
      mount: mysecrets
      secret: TestingSecret
      version: 0 # 0 means latest version

log:
  level: info

To configure Secret Agent with the TLS certificates auth method:

Create a TLS auth method in Vault. In this example, the mount (path) is authcerts.
Enable KV (V2) Secrets Engine in Vault with mount (path) mysecrets.
Create a secret under the mysecrets mount. In this example, the secret is named TestingSecret.
Add one or more key-value pairs to TestingSecret.
Verify that the TLS auth method has policies attached that allow reading TestingSecret.
Install Secret Agent on the machine.
Configure Secret Agent to fetch secrets from Vault.
Start Secret Agent.

Configuration parameters

Parameter	Description	Notes
`endpoint`	Vault server endpoint	Required. Can be `http` or `https`.
`ca-file`/`ca-path`	File or path to the CA certificate	Required if the Vault server uses `https`.
`namespace`	Namespace for authentication	Required when using Vault Enterprise or HashiCorp Cloud Platform (HCP) Vault.
`token-file`	Path to the file containing the Vault token	Required when using the token auth method.
`username`	Username for authentication	Required when using the username and password method.
`password-file`	Path to the file containing the password	Required when using the username and password method.
`tls-auth-mount`	Mount point of the TLS certificates auth method	Required when using the TLS certificates method.
`client-cert-file`	Path to the client certificate file	Required when using the TLS certificates method.
`client-key-file`	Path to the client key file	Required when using the TLS certificates method.
`convert-to-base64`	If `true`, Secret Agent converts secret values to base64-encoded format
`resources`	Contains the mount point, secret name, and version of the secret	Required.
`mount`	Mount point (path) of the secret engine
`secret`	Name of the secret
`version`	Version of the secret. Default `0` fetches the latest version.