Hashicorp Vault Secret Manager

danger

Configuring Vault is deprecated in Database 7.0. Secret Agent is the recommended way to fetch secrets from Vault.

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

Secret Agent can use one of the following authentication methods to authenticate with the Hashicorp Vault server:

1. Token auth method
2. Username/password auth method
3. TLS certificates auth method

Token auth method

This method authenticates you with a Vault token. You must generate a Vault token and store it in a file. Secret Agent reads the token from the file and uses it to authenticate. The token file is read for every fetch request. If the token is changed in a file, Secret Agent uses the new token for the subsequent fetch request. The file should have appropriate permissions so that only Secret Agent can read the token.

Sample configuration file for token auth method:

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

Use the following steps to configure Secret Agent to use token auth method:

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

Username/password auth method

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

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

Sample configuration file for username/password auth method:

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

Use the following steps to configure Secret Agent to use Username/password auth method:

1. Enable KV (V2) Secrets Engine in Vault with mount (path) as mysecrets.
2. Create a secret under mysecrets mount. In this example, the secret is named TestingSecret.
3. Add one or more key-value pairs to the secret TestingSecret.
4. Create a username and password in Vault. In this example, the username is testuser and the password is stored in /path/to/password/file.
5. Verify that testuser is attached with appropriate policies to read the secret TestingSecret.
6. Install Secret Agent on the machine.
7. Configure Secret Agent to fetch secrets from Vault.
8. Start Secret Agent.
9. Use the Secret Agent endpoint to fetch secrets.

Sample Vault policy to read the secret TestingSecret:

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

TLS certificates auth method

This is a secure method as no tokens or passwords are stored in any file on the machine. TLS certificates auth method allows authentication using SSL/TLS client certificates which are either signed by a CA or self-signed. Vault server determines if there is a matching certificate to authenticate the Secret Agent. If the Secret Agent is authenticated, the auth method returns a token. Renewal of the token is same as mentioned in the previous section.

note

To use this auth method, Vault server must be configured to use TLS. tls_disable and tls_disable_client_certs must be false in the Vault configuration because the certificates are sent through TLS communication itself.

Sample configuration file for TLS certificates auth method:

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

Use the following steps to configure Secret Agent to use the TLS certificate auth method:

1. Create a TLS auth method in Vault. In this example, the mount (path) of the TLS auth method is authcerts.
2. Enable KV (V2) Secrets Engine in Vault with mount (path) as mysecrets.
3. Create a secret under mysecrets mount. In this example, the secret is named TestingSecret.
4. Add one or more key-value pairs to the secret TestingSecret.
5. Make sure that TLS auth method is attached with appropriate policies to read the secret TestingSecret.
6. Install Secret Agent on the machine.
7. Configure Secret Agent to fetch secrets from Vault.
8. Start Secret Agent.
9. Use the Secret Agent endpoint to fetch secrets.

Configuration parameters

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