Skip to main content

​
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 or AWS Secrets Manager
  • Inject secrets at runtime so users never see the actual values
  • Rotate credentials without updating resource role configs
  • Audit who accessed what, without credential exposure

​
How It Works

1

Store Secrets

Save credentials in your secrets provider (HashiCorp Vault or AWS Secrets Manager).
2

Reference in Resource Role

Configure the resource role’s environment variables with a secret reference (for example, _aws:my-secret:DB_PASSWORD) instead of a literal value.
3

Runtime Resolution

When a user opens a session, the agent fetches the secret from the provider and injects it.
4

Secure Access

The user connects successfully without ever seeing the credential.

​
What Users See

When a user connects to a database configured with secrets: 
$ hoop connect prod-postgres
Connected to prod-postgres
psql>
They connect successfully, but never see the database password. The password is fetched from the secrets provider and injected by Hoop.

​
Supported Providers

HashiCorp Vault

Key/Value Secrets Engine, versions 1 and 2

AWS Secrets Manager

AWS-native key/value secrets

Env JSON

Expand values from a JSON environment variable on the agent. CLI-only — kept for compatibility with older agents.
Provider credentials are read by the agent, so the provider’s environment variables must be exposed on the machine running the agent — not on the gateway.
Connecting to AWS? Instead of storing static credentials, a resource role can also use an AWS IAM Role (assume-role) as its connection method. See RDS IAM Authentication.

​
Use Cases

​
1. Database Credentials

Store database passwords in your secrets provider instead of in the resource role config. The resource role references the secret, so the literal password never lives in Hoop.

​
2. API Keys

Inject API keys for application resource roles at runtime, so scripts and commands can authenticate without the key being visible to the user.

​
3. SSH Keys

Keep SSH private keys in the secrets provider and inject them only at session time, keeping them out of resource role configs.

​
Credential Rotation

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

Update Secret in Provider

Change the password in Vault or AWS Secrets Manager.
2

No Resource Role Changes Needed

Resource role configs reference the secret, not the value.
3

New Sessions Use the New Credential

Next time someone connects, the agent fetches and injects the new password.

​
Rotation Best Practices

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

​
Security Best Practices

Least Privilege

Grant the agent only read access to the secrets it needs

Audit Logging

Enable audit logs on your secrets provider

Rotate Regularly

Schedule regular credential rotation

Separate by Environment

Use different secrets for dev/staging/prod

​
What NOT to Do

  • Don’t store secrets in resource role 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”
Ready to set it up? The Secrets Management configuration guide covers the Web App flow and the per-provider reference syntax for HashiCorp Vault, AWS Secrets Manager, and Env JSON.

​
Next Steps

Configuration Guide

Provider setup and reference syntax

Access Control

Control who can access resource roles

Session Recording

Audit all resource role activity

HashiCorp Vault

Vault documentation