> ## Documentation Index
> Fetch the complete documentation index at: https://hoopdev-docs-improve-idp-sso-pages.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets Management

> Securely inject credentials into connections without exposing them to users

<Frame>
  <img src="https://mintcdn.com/hoopdev-docs-improve-idp-sso-pages/mOi9paMdj4zBZvQ5/images/learn/features/secrets-manager.png?fit=max&auto=format&n=mOi9paMdj4zBZvQ5&q=85&s=4c47c02a8a6271c9c077cd9836676ab0" alt="Secrets Management" width="1408" height="768" data-path="images/learn/features/secrets-manager.png" />
</Frame>

## What You'll Accomplish

Secrets Management lets you connect to databases and servers without exposing credentials to users. Instead of sharing passwords, you can:

* Store credentials in HashiCorp Vault, AWS Secrets Manager, or other providers
* Inject secrets at runtime—users never see the actual values
* Rotate credentials without updating connection configs
* Audit who accessed what, without credential exposure

***

## How It Works

<Steps>
  <Step title="Store Secrets">
    Save credentials in your secrets provider (Vault, AWS, etc.)
  </Step>

  <Step title="Reference in Connection">
    Configure connections using secret references like `_envs/vault/DB_PASSWORD`
  </Step>

  <Step title="Runtime Resolution">
    When a user connects, Hoop fetches the secret and injects it
  </Step>

  <Step title="Secure Access">
    User connects successfully without ever seeing the credential
  </Step>
</Steps>

### What Users See

When a user connects to a database configured with secrets:

```bash theme={null}
$ hoop connect prod-postgres
Connected to prod-postgres
psql>
```

They connect successfully, but never see the database password. The password is fetched from Vault and injected by Hoop.

***

## Supported Providers

<CardGroup cols={2}>
  <Card title="HashiCorp Vault" icon="vault">
    Most popular self-hosted secrets manager
  </Card>

  <Card title="AWS Secrets Manager" icon="aws">
    AWS-native secrets storage
  </Card>

  <Card title="Azure Key Vault" icon="microsoft">
    Azure-native key and secret management
  </Card>

  <Card title="GCP Secret Manager" icon="google">
    Google Cloud secrets storage
  </Card>

  <Card title="Environment Variables" icon="terminal">
    Simple secrets via gateway environment
  </Card>

  <Card title="Kubernetes Secrets" icon="dharmachakra">
    Native Kubernetes secret references
  </Card>
</CardGroup>

***

## Quick Start

### Example: HashiCorp Vault

#### Step 1: Store a Secret in Vault

```bash theme={null}
vault kv put secret/databases/prod-postgres \
  username=app_user \
  password=supersecretpassword
```

#### Step 2: Configure Hoop Gateway

Set environment variables for Vault access:

```bash theme={null}
VAULT_ADDR=https://vault.example.com:8200
VAULT_TOKEN=hvs.your-vault-token
```

#### Step 3: Create Connection with Secret Reference

In the Web App or via CLI, create a connection that references the secret:

```bash theme={null}
hoop admin create connection prod-postgres \
  --agent default \
  --type postgres \
  -- psql "postgresql://_envs/vault/secret/databases/prod-postgres#username:_envs/vault/secret/databases/prod-postgres#password@db.example.com:5432/myapp"
```

Or configure in the Web App:

* **Username:** `_envs/vault/secret/databases/prod-postgres#username`
* **Password:** `_envs/vault/secret/databases/prod-postgres#password`

#### Step 4: Test the Connection

```bash theme={null}
hoop connect prod-postgres
```

The connection works, with credentials fetched from Vault at runtime.

***

## Secret Reference Syntax

Secrets are referenced using a special syntax:

```
_envs/<provider>/<path>#<key>
```

| Component    | Description                               | Example                        |
| ------------ | ----------------------------------------- | ------------------------------ |
| `_envs/`     | Prefix indicating a secret reference      |                                |
| `<provider>` | Secret provider name                      | `vault`, `aws`, `azure`, `gcp` |
| `<path>`     | Path to the secret in the provider        | `secret/databases/prod`        |
| `#<key>`     | (Optional) Specific key within the secret | `#password`                    |

### Examples

**HashiCorp Vault:**

```
_envs/vault/secret/databases/prod-postgres#password
```

**AWS Secrets Manager:**

```
_envs/aws/prod/databases/postgres#password
```

**Environment Variable:**

```
_envs/DB_PASSWORD
```

***

## Provider Configuration

### HashiCorp Vault

**Gateway environment variables:**

| Variable          | Description                |
| ----------------- | -------------------------- |
| `VAULT_ADDR`      | Vault server URL           |
| `VAULT_TOKEN`     | Authentication token       |
| `VAULT_NAMESPACE` | (Optional) Vault namespace |

**Reference format:**

```
_envs/vault/<mount>/<path>#<key>
```

### AWS Secrets Manager

**Gateway environment variables:**

| Variable                | Description    |
| ----------------------- | -------------- |
| `AWS_REGION`            | AWS region     |
| `AWS_ACCESS_KEY_ID`     | AWS access key |
| `AWS_SECRET_ACCESS_KEY` | AWS secret key |

Or use IAM roles for EC2/ECS.

**Reference format:**

```
_envs/aws/<secret-name>#<key>
```

### Azure Key Vault

**Gateway environment variables:**

| Variable              | Description                 |
| --------------------- | --------------------------- |
| `AZURE_VAULT_URL`     | Key Vault URL               |
| `AZURE_CLIENT_ID`     | Service principal client ID |
| `AZURE_CLIENT_SECRET` | Service principal secret    |
| `AZURE_TENANT_ID`     | Azure tenant ID             |

**Reference format:**

```
_envs/azure/<secret-name>
```

### GCP Secret Manager

**Gateway environment variables:**

| Variable                         | Description                  |
| -------------------------------- | ---------------------------- |
| `GCP_PROJECT_ID`                 | Google Cloud project         |
| `GOOGLE_APPLICATION_CREDENTIALS` | Path to service account JSON |

**Reference format:**

```
_envs/gcp/<secret-name>
```

***

## Use Cases

### 1. Database Credentials

Store database passwords in Vault instead of connection configs:

```yaml theme={null}
# Instead of this (insecure):
password: mysecretpassword

# Use this (secure):
password: _envs/vault/secret/databases/prod#password
```

### 2. API Keys

Inject API keys for application connections:

```bash theme={null}
# Command that needs an API key
curl -H "Authorization: Bearer _envs/vault/secret/api-keys/stripe#key" https://api.stripe.com/v1/charges
```

### 3. SSH Keys

Store SSH private keys securely:

```
ssh -i _envs/vault/secret/ssh-keys/prod-server#private_key user@server.example.com
```

### 4. Kubernetes Secrets

For agents running in Kubernetes, reference native secrets:

```
_envs/k8s/my-namespace/db-credentials#password
```

***

## Credential Rotation

One of the biggest benefits of secrets management is seamless credential rotation:

<Steps>
  <Step title="Update Secret in Provider">
    Change the password in Vault/AWS/etc.
  </Step>

  <Step title="No Connection Changes Needed">
    Connection configs reference the secret, not the value
  </Step>

  <Step title="New Connections Use New Credential">
    Next time someone connects, they get the new password
  </Step>
</Steps>

### Rotation Best Practices

1. **Schedule regular rotations** - Monthly or quarterly
2. **Test after rotation** - Verify connections still work
3. **Keep previous version** - Some providers support versioning
4. **Audit access** - Check who accessed secrets recently

***

## Troubleshooting

### Connection Fails with "Secret Not Found"

**Check:**

1. Secret path is correct (including mount point for Vault)
2. Provider credentials are configured on the gateway
3. Provider is accessible from the gateway network
4. Secret exists and has the expected key

**Debug:**

```bash theme={null}
# Test Vault access from gateway
vault kv get secret/databases/prod-postgres

# Test AWS access
aws secretsmanager get-secret-value --secret-id prod/databases/postgres
```

### "Permission Denied" Errors

**Check:**

1. Gateway credentials have read access to the secret
2. Vault policy allows reading the path
3. IAM role/policy includes the secret ARN

### Secret Value Not Substituted

If you see the literal `_envs/...` string instead of the secret value:

1. Check the syntax is exactly correct
2. Verify provider is configured in gateway environment
3. Restart the gateway after configuration changes

***

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Least Privilege" icon="shield-check">
    Grant gateway only read access to needed secrets
  </Card>

  <Card title="Audit Logging" icon="clipboard-list">
    Enable audit logs on your secrets provider
  </Card>

  <Card title="Rotate Regularly" icon="rotate">
    Schedule regular credential rotation
  </Card>

  <Card title="Separate by Environment" icon="layer-group">
    Use different secrets for dev/staging/prod
  </Card>
</CardGroup>

### What NOT to Do

* Don't store secrets in connection configs directly
* Don't share provider tokens with users
* Don't use the same credentials across environments
* Don't skip rotation because "it's working"

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration Guide" icon="gear" href="/setup/configuration/secrets-manager-configuration">
    Detailed provider setup instructions
  </Card>

  <Card title="Access Control" icon="lock" href="/learn/features/access-control">
    Control who can access connections
  </Card>

  <Card title="Session Recording" icon="video" href="/learn/features/session-recording">
    Audit all connection activity
  </Card>

  <Card title="HashiCorp Vault" icon="vault" href="https://www.vaultproject.io/docs">
    Vault documentation
  </Card>
</CardGroup>