Vault KV Provider¶

This provider fetches secrets from HashiCorp Vault’s KV secrets engine and imports them into environment variables. It represents one of the most common and straightforward use cases for secrets.env.

Tip

To streamline workflow and minimize context switching, this provider supports configuration via environment variables.

By default, it retrieves configuration from environment variables prefixed with SECRETS_ENV_. However, for alignment with the official Vault CLI tool, it can also be set up to read from environment variables prefixed with VAULT_.

Configuration layout¶

toml

[[sources]]
name = "strongbox"
type = "vault"
url = "https://vault.example.com"
proxy = "http://proxy:3128"

[sources.auth]
method = "okta"
username = "user@example.com"

[sources.tls]
ca_cert = "/path/ca.cert"
client_cert = "/path/client.cert"
client_key = "/path/client.key"

[sources.teleport]
proxy = "teleport.example.com"
cluster = "dev.example.com"
user = "demo-user"
app = "my-app"

[[secrets]]
name = "DEMO_TOKEN"
source = "strongbox"
path = "secret/default"
field = "token"

[[secrets]]
name = "NESTED_SECRET"
source = "strongbox"
path = "secret/default"
field = [
   "subpath",
   "to",
   "secret",
]

yaml

sources:
  - name: strongbox
    type: vault
    url: https://vault.example.com
    auth:
      method: okta
      username: user@example.com
    proxy: http://proxy:3128
    tls:
      ca_cert: /path/ca.cert
      client_cert: /path/client.cert
      client_key: /path/client.key
    teleport:
      proxy: teleport.example.com
      cluster: dev.example.com
      user: demo-user
      app: my-app

secrets:
  - name: DEMO_TOKEN
    source: strongbox
    path: secret/default
    field: token

  - name: NESTED_SECRET
    source: strongbox
    path: secret/default
    field:
      - subpath
      - to
      - secret

json

{
  "sources": [
    {
      "name": "strongbox",
      "type": "vault",
      "url": "https://vault.example.com",
      "auth": {
        "method": "okta",
        "username": "user@example.com"
      },
      "proxy": "http://proxy:3128",
      "tls": {
        "ca_cert": "/path/ca.cert",
        "client_cert": "/path/client.cert",
        "client_key": "/path/client.key"
      },
      "teleport": {
        "proxy": "teleport.example.com",
        "cluster": "dev.example.com",
        "user": "demo-user",
        "app": "my-app"
      }
    }
  ],
  "secrets": [
    {
      "name": "DEMO_TOKEN",
      "source": "strongbox",
      "path": "secret/default",
      "field": "token"
    },
    {
      "name": "NESTED_SECRET",
      "source": "strongbox",
      "path": "secret/default",
      "field": [
        "subpath",
        "to",
        "secret"
      ]
    }
  ]
}

pyproject.toml

[[tool.secrets-env.sources]]
name = "strongbox"
type = "vault"
url = "https://vault.example.com"
proxy = "http://proxy:3128"

[tool.secrets-env.sources.auth]
method = "okta"
username = "user@example.com"

[tool.secrets-env.sources.tls]
ca_cert = "/path/ca.cert"
client_cert = "/path/client.cert"
client_key = "/path/client.key"

[tool.secrets-env.sources.teleport]
proxy = "teleport.example.com"
cluster = "dev.example.com"
user = "demo-user"
app = "my-app"

[[tool.secrets-env.secrets]]
name = "DEMO_TOKEN"
source = "strongbox"
path = "secret/default"
field = "token"

[[tool.secrets-env.secrets]]
name = "NESTED_SECRET"
source = "strongbox"
path = "secret/default"
field = [
   "subpath",
   "to",
   "secret",
]

Environment variables¶

SECRETS_ENV_ADDR¶: The URL to the Vault server. Overrides the url field.

SECRETS_ENV_CA_CERT¶: Path to the server side certificate for verifying responses. Overrides the tls.ca_cert field.

SECRETS_ENV_CLIENT_CERT¶: Path to the client certificate for authenticating to the server. Overrides the tls.client_cert field.

SECRETS_ENV_CLIENT_KEY¶: Specifies the path to the client’s private key for authenticating to the server. Overrides the tls.client_key field.

SECRETS_ENV_NO_PROMPT¶: Disables the prompt for username / password when using Login auth methods.

SECRETS_ENV_PASSWORD¶: The password to authenticate with. Used by Login auth methods.

SECRETS_ENV_PROXY¶: Use the specified proxy to access Vault. Overrides the proxy field.

SECRETS_ENV_ROLE¶: Role name used by OpenID Connect. Overrides auth.role field.

SECRETS_ENV_TOKEN¶: The token to use for authentication. Used by Token auth method.

SECRETS_ENV_USERNAME¶: The username to authenticate with. Overrides auth.username field.

Source section¶

A field name followed by a bookmark icon () indicates that it is a required parameter.

`url` ¶

The URL to the Vault server.

You can set this field using the environment variables SECRETS_ENV_ADDR or VAULT_ADDR. However, if the teleport section is configured, it will be ignored.

`auth` ¶

Defines the method and associated arguments for authenticating with Vault.

`auth.method` ¶

The method to use for authentication.

Accepted values are:

ldap, applying the LDAP auth method
oidc, applying the OpenID Connect method
okta, applying the Okta auth method
radius, applying the RADIUS auth method
token, applying the Token auth method
userpass, applying the Userpass auth method

`auth.role`¶

Role name used by OpenID Connect.

`auth.username`¶

Username used by Login auth methods.

Shortcut¶

In certain scenarios, only the method field may be required. For instance, when utilizing Okta auth and providing username through another method such as environment variables, you can simply set the method directly for the auth field:

toml

[[sources]]
name = "strongbox"
type = "vault"
url = "https://vault.example.com"
auth = "okta"

yaml

sources:
  - name: strongbox
    type: vault
    url: https://vault.example.com
    auth: okta

`proxy`¶

Use the specified proxy to access Vault.

Could be set via environment variable SECRETS_ENV_PROXY, VAULT_PROXY_ADDR, VAULT_HTTP_PROXY or uses standard proxy variables.

Important

You must specify protocol for proxy URL. A typical input could be http://proxy or http://proxy:3128. Further, the proxy URL for the https:// addresses should still be http:// scheme in most cases.

`tls`¶

Transport layer security (TLS) configurations.

`tls.ca_cert`¶

Path to the server side certificate for verifying responses.

This value could be set via environment variable SECRETS_ENV_CA_CERT or VAULT_CACERT.

`tls.client_cert`¶

Path to the client certificate for authenticating to the server.

This value could be set via environment variable SECRETS_ENV_CLIENT_CERT or VAULT_CLIENT_CERT.

`tls.client_key`¶

Specifies the path to the client’s private key for authenticating to the server. If your client certificate already includes the client key in its format, please disregard this field.

This value could be set via environment variable SECRETS_ENV_CLIENT_KEY or VAULT_CLIENT_KEY.

`teleport`¶

Configuration for Teleport integration.

`teleport.app` ¶

Specify the name of the Teleport application to request connection information from. This field is necessary when utilizing Teleport integration.

`teleport.proxy`¶

Address to Teleport proxy service.

`teleport.cluster`¶

Teleport cluster to connect.

`teleport.user`¶

Teleport user name.

Token helper¶

Vault offers a feature known as token helper, which stores the Vault token on the disk.

Secrets.env now includes support for this feature. It means you won’t have to provide the token again after the initial login until it expires.

The token helper file is shared among applications, allowing the token obtained by secrets.env to be used with the Vault CLI, and vice versa.
The token helper login attempt takes precedence over any other authentication method.

Secrets.env first attempts to use the token helper to communicate with the Vault server. If the token is not found or has expired, it will then fall back to the configured authentication method.
Secrets.env DOES NOT consider vault configuration. Instead, it solely reads the token from the default path, which is ~/.vault-token.

Authentication methods¶

Vault enforces authentication during requests, requiring an identity to access secrets.

By specifying the auth.method field, the associated authentication method will be applied.

Login auth methods¶

Login authentication methods in secrets.env pertains to a group of authentication methods that mandate a username and password combination.

These authentication methods share the same arguments: username and password. Here are the details on how we retrieve the values:

Username ¶

The username to authenticate with. Could be set via:

Environment variable SECRETS_ENV_USERNAME
From auth.username field
The app prompts for the username if it’s not provided.

If you want to disable the prompt, set the environment variable SECRETS_ENV_NO_PROMPT to true.

Password ¶

The password to authenticate with. Could be retrieved via:

Environment variable SECRETS_ENV_PASSWORD
Keyring Support

You need to save the password in the keyring before running the app.
The app prompts for the password if it’s not provided.

If you want to disable the prompt, set the environment variable SECRETS_ENV_NO_PROMPT to true.

LDAP auth¶

method:: ldap

Okta auth¶

method:: okta

Authenticated through Okta. This method corresponds to the Okta auth method in Vault.

RADIUS auth¶

method:: radius

Authentication using an existing RADIUS server that accepts the PAP authentication scheme. This method corresponds to the RADIUS auth method in Vault.

Userpass auth¶

method:: userpass

A straightforward method for authenticating with Vault using a combination of username and password. This method corresponds to the userpass auth method in Vault.

OpenID Connect¶

method:: oidc

Get authentication via configured OpenID Connect provider using your web browser. This method corresponds to the JWT/OIDC auth method in Vault.

Role¶

Role name. Could be retrieved via:

Environment variable SECRETS_ENV_ROLE
From auth.role field

Token auth¶

method:: token

Token auth is one of the simplest ways to authenticate with Vault.

It’s worth noting that secrets.env first tries to retrieve the token using the Token helper before resorting to this authentication method. This method is mainly for manual token input and accepts tokens only from environment variables.

Token ¶

The only argument used for this method is the token itself, which must be set via environment variables SECRETS_ENV_TOKEN or VAULT_TOKEN.

Teleport integration¶

If your Vault is secured using Teleport, you can employ the this feature to establish a connection with Vault.

Enabling¶

Important

To use this feature, additional dependencies are needed. Please check the Teleport Support page for further information.

Once teleport configurations are configured, the Vault provider will request access from Teleport and utilize it to establish a connection to Vault.

Example¶

This configuration instructs secrets.env to request access for “my-vault” from Teleport and establish a connection to the application:

toml

[[sources]]
type = "vault"

[sources.teleport]
proxy = "teleport.example.com"
cluster = "dev.example.com"
app = "my-vault"

yaml

sources:
  type: vault
  teleport:
    proxy: teleport.example.com
    cluster: dev.example.com
    app: my-vault

Since Teleport manages the connection, any URL and TLS configuration provided in the config file will be ignored.

Configuration¶

Just like with the Teleport Provider, the app field is always mandatory for this functionality.

Other fields are optional. Read teleport section above for more information.

Secrets section¶

The configurations within the secrets section determine which secrets are to be read.

`path` ¶

The path to the secret in Vault.

`field` ¶

Indicates the field within the secret to be imported.

For a nested secret object, you have two options:

Specify a list of fields to traverse the hierarchy.
Use a dot-separated string to represent the path to the desired field.

For example, consider a secret object like this:

{
  "prod": {
    "username": "admin"
  },
  "dev": {
    "username": "user"
  }
  "stg.demo-1": {
    "username": "user"
  }
}

You can use any of the following methods to import the “username” for the “prod” environment:

Specify ["prod", "username"]
Use the string prod.username

If the field name contains a dot, you should enclose the field name in double quotes, like "stg.demo-1".username.

Simplified layout¶

This provider accepts strings in the format path#field to represent the path and field of a value. With the simplified layout, you can define config more concisely:

toml simplified

[source]
type = "vault"
url = "https://vault.example.com"
auth = "oidc"

[secrets]
PROD_TOKEN = "secret/default#prod.token"
DEV_TOKEN = { path = "secret/default", field = "dev.token" }

yaml simplified

source:
  type: vault
  url: https://vault.example.com
  auth: oidc

secrets:
  PROD_TOKEN: secret/default#prod.token
  DEV_TOKEN:
    path: secret/default
    field: dev.token

Vault KV Provider¶

Configuration layout¶

Environment variables¶

Source section¶

url ¶

auth ¶

auth.method ¶

auth.role¶

auth.username¶

Shortcut¶

proxy¶

tls¶

tls.ca_cert¶

tls.client_cert¶

tls.client_key¶

teleport¶

teleport.app ¶

teleport.proxy¶

teleport.cluster¶

teleport.user¶

Token helper¶

Authentication methods¶

Login auth methods¶

Username ¶

Password ¶

LDAP auth¶

Okta auth¶

RADIUS auth¶

Userpass auth¶

OpenID Connect¶

Role¶

Token auth¶

Token ¶

Teleport integration¶

Enabling¶

Example¶

Configuration¶

Secrets section¶

path ¶

field ¶

Simplified layout¶

`url` ¶

`auth` ¶

`auth.method` ¶

`auth.role`¶

`auth.username`¶

`proxy`¶

`tls`¶

`tls.ca_cert`¶

`tls.client_cert`¶

`tls.client_key`¶

`teleport`¶

`teleport.app` ¶

`teleport.proxy`¶

`teleport.cluster`¶

`teleport.user`¶

`path` ¶

`field` ¶