Secrets Manager Configuration - Hoop.dev - Automated Access and Data Protection

This page covers how to configure Secrets Management for a resource role — in the Web App or via the CLI — plus the reference syntax for each supported provider: HashiCorp Vault, AWS Secrets Manager, and Env JSON.

For an introduction to what Secrets Management does, see the Secrets Management overview.

Provider credentials are read by the agent. The provider’s environment variables (for example VAULT_ADDR / VAULT_TOKEN, or AWS region and credentials) must be exposed on the machine running the agent — not on the gateway.

Configure in the Web App

When you create or edit a resource role (Setup your Resource roles), pick a Role connection method:

Manual Input — enter credentials directly (host, user, password, port, and other connection details).
Secrets Manager — fetch credentials from a secrets provider automatically.
AWS IAM Role — assume an IAM role to authenticate to AWS resources. This is a separate method — see RDS IAM Authentication for that flow.

Choosing Secrets Manager reveals a Secrets manager provider dropdown:

HashiCorp Vault — KV version 1
HashiCorp Vault — KV version 2
AWS Secrets Manager

The Web App automates the reference prefix based on the selected provider — you don’t have to type _aws: / _vaultkv1: / _vaultkv2: by hand. Each field (Host, User, Pass, Port, DB, SSL Mode) also has its own source selector, so you can mix sources within a single role — for example, pull the password from Vault while entering the host manually.

The Web App is a convenience layer over the same backend integration documented below — the prefixes it generates are exactly the per-provider syntax in the following sections. Env JSON is available only via the CLI, not in the Web App.

AWS Secrets Manager Provider

This provider allows for the expansion of environment variables from an AWS key-value secret or a literal one.

Credentials Configuration

It requires an instance profile in the agent with the permissions below: Required IAM Roles

secretsmanager:GetSecretValue
secretsmanager:GetResourcePolicy
secretsmanager:DescribeSecret
secretsmanager:ListSecretVersionIds

Make sure to export the AWS_REGION environment variable in the machine running the agent.

Syntax

_aws:SECRET-NAME:SECRET-KEY

A secret configured as:

cat - > /tmp/pgconfig.json <<EOF
{
  "PG_HOST": "127.0.0.1",
  "PG_PORT": "3306"
}
EOF
aws secretsmanager create-secret --name pgprod \
    --secret-string file:///tmp/pgconfig.json

Can be exposed to an environment variable in a resource role as:

_aws:pgprod:PG_HOST
_aws:pgprod:PG_PORT

Example:

MYSECRET=_aws:prod-secret-name:MYSECRET

The environment key value will be replaced when the user opens a session with the agent.

Testing

Create a bash resource role.

hoop admin create connection bash --agent test-agent \
    -e PG_HOST=_aws:pgprod:PG_HOST \
    --overwrite -- /bin/bash

Then, execute the env command to dump the environment variables of a session.

hoop exec bash -i 'env' |grep PG_HOST

HashiCorp Vault Provider

This provider expands environment variables from an Vault Key Value Secrets Engine. It supports versions 1 and 2.

Configuration

It requires the environment variables exported in the machine running the agent. The implementation follows the specification of the Vault Cli and it’s limited to the configuration below:

Name	Required	Description
VAULT_ADDR	yes	Address of the Vault server expressed as a URL and port, for example: `https://127.0.0.1:8200/`.
VAULT_TOKEN	yes*	Vault authentication token. Conceptually similar to a session token on a website, the VAULT_TOKEN environment variable holds the contents of the token. It’s required if App Role authentication is not being used.
VAULT_APP_ROLE_ID	no	The Role ID in case App Role Authentication is used.
VAULT_APP_ROLE_SECRET_ID	no	The Secret ID in case App Role Authentication is used.
VAULT_CACERT	no	Path or inline base64 content of PEM-encoded CA certificate file on the local disk. This file is used to verify the Vault server’s SSL certificate.

Example of how to define expose the env VAULT_CACERT

# load from /tmp/ca.pem file
export VAULT_CACERT=file:///tmp/ca.pem
# load from inline base64 content
export VAULT_CACERT=base64://<inline-base64-content>

App Role Authentication

The approle auth method allows machines or apps to authenticate with Vault-defined roles. This auth method is oriented to automated workflows (machines and services), and is less useful for human operators. The agent will perform a request to POST /auth/approle/login and obtain a valid token to access secrets in Vault Key Value store. Make sure to configure the environment variables when deploying the agent:

export VAULT_APP_ROLE_ID=<role-id>
export VAULT_APP_ROLE_SECRET_ID=<secret-id>

It’s important to use batch tokens when using the App Role method. Refer to Vault App Role documentation for more information.

Testing

Install Vault

This step requires a Vault installation, for the sake of this documentation we recommend using a Vault development server. Check the getting started with dev server

You can use the option -dev-listen-address="0.0.0.0:8200" to expose the Vault Server to your host network.

Configure Secrets

KV Version 1
KV Version 2

The command below will enable and configure a secret in a KV version 1

vault secrets enable -version=1 kv
vault kv put kv/pgprod \
    DBHOST=mydbhost.tld \
    DBUSER=dbuser \
    DBPASSWD=dbsupersecret \
    DBPORT=5432

A resource role could be mapped using the following syntax:

_vaultkv1:SECRETNAME:SECRET-KEY

Set this as the resource role’s field value. In the Web App, selecting HashiCorp Vault — KV version 1 as the provider applies the _vaultkv1: prefix automatically (see Configure in the Web App).

The command below will enable and configure a secret in a KV version 2

vault secrets enable -version=2 -path=dbsecrets kv
vault kv put -mount=dbsecrets pgtest \
    DBHOST=mydbhost.tld \
    DBUSER=dbuser \
    DBPASSWD=dbsupersecret \
    DBPORT=5432

A resource role could be mapped using the following syntax:

_vaultkv2:SECRETNAME:SECRET-KEY

Set this as the resource role’s field value. In the Web App, selecting HashiCorp Vault — KV version 2 as the provider applies the _vaultkv2: prefix automatically (see Configure in the Web App).

It’s possible to obtain a versioned secret as well. For this example would be: _vaultkv2:/dbsecrets/data/pgtest?version=3:DBHOST

Testing

Go to the Webapp and run a query in this Resource Role.

Env Json Provider

This provider allows the exposure of environment variables from an agent by exposing a JSON environment variable. It is useful for maintaining compatibility with older runops agents.

Syntax

_envjson:MYJSON_ENV:ENVKEY

So an environment variable configured in an agent:

ENV_CONFIG='{"PG_HOST": "127.0.0.1", "PG_DB": "testdb"}'

Can be exposed to an environment variable in a resource role as:

_envjson:ENVCONFIG:PG_HOST

Testing

Create a bash resource role.

hoop admin create connection bash --agent test-agent \
    -e PG_HOST=_envjson:ENV_CONFIG:PG_HOST \
    --overwrite -- /bin/bash

Then, execute the env command to dump the environment variables of a session.

hoop exec bash -i 'env' |grep PG_HOST

​Configure in the Web App

​AWS Secrets Manager Provider

​Credentials Configuration

​Syntax

​Testing

​HashiCorp Vault Provider

​Configuration

​App Role Authentication

​Testing

​Env Json Provider

​Syntax

​Testing

Configure in the Web App

AWS Secrets Manager Provider

Credentials Configuration

Syntax

Testing

HashiCorp Vault Provider

Configuration

App Role Authentication

Testing

Env Json Provider

Syntax

Testing