> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.hoop.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets Manager Configuration

> It enables integration with a known secrets manager, allowing the resource role environment variable to be dynamically expanded for each resource role.

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**.

<Note>
  For an introduction to what Secrets Management does, see the [Secrets Management overview](/learn/features/secrets-manager).
</Note>

<Info>
  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.
</Info>

## 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](/setup/configuration/rds-iam-auth) 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.

<Note>
  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.
</Note>

## 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

<Info>
  Make sure to export the `AWS_REGION` environment variable in the machine running the agent.
</Info>

### Syntax

* `_aws:SECRET-NAME:SECRET-KEY`

A secret configured as:

```bash theme={"dark"}
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.

```bash theme={"dark"}
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.

```bash theme={"dark"}
hoop exec bash -i 'env' |grep PG_HOST
```

## HashiCorp Vault Provider

This provider expands environment variables from an [Vault Key Value Secrets Engine](https://developer.hashicorp.com/vault/docs/secrets/kv). 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](https://developer.hashicorp.com/vault/docs/commands#environment-variables) 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](https://developer.hashicorp.com/vault/docs/auth/approle) is used.                                                                                                      |
| VAULT\_APP\_ROLE\_SECRET\_ID | no       | The Secret ID in case [App Role Authentication](https://developer.hashicorp.com/vault/docs/auth/approle) 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.                                                                  |

<Info>
  Example of how to define expose the env `VAULT_CACERT`

  ```sh theme={"dark"}
  # 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>
  ```
</Info>

### 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:

```sh theme={"dark"}
export VAULT_APP_ROLE_ID=<role-id>
export VAULT_APP_ROLE_SECRET_ID=<secret-id>
```

<Info>
  It's important to use `batch` tokens when using the **App Role** method.
  Refer to [Vault App Role documentation](https://developer.hashicorp.com/vault/docs/auth/approle) for more information.
</Info>

### Testing

<Steps>
  <Step title="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](https://developer.hashicorp.com/vault/tutorials/getting-started/getting-started-dev-server)

    <Info>
      You can use the option `-dev-listen-address="0.0.0.0:8200"` to expose the Vault Server to your host network.
    </Info>
  </Step>

  <Step title="Configure Secrets">
    <Tabs>
      <Tab title="KV Version 1">
        * The command below will enable and configure a secret in a **KV version 1**

        ```sh theme={"dark"}
        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](#configure-in-the-web-app)).
      </Tab>

      <Tab title="KV Version 2">
        The command below will enable and configure a secret in a **KV version 2**

        ```sh theme={"dark"}
        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](#configure-in-the-web-app)).

        <Tip>
          It's possible to obtain a versioned secret as well.
          For this example would be: `_vaultkv2:/dbsecrets/data/pgtest?version=3:DBHOST`
        </Tip>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Testing">
    Go to the Webapp and run a query in this Resource Role.
  </Step>
</Steps>

## 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.

```bash theme={"dark"}
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.

```bash theme={"dark"}
hoop exec bash -i 'env' |grep PG_HOST
```