Chapter 15 / 28
Leasing, TTL, and Vault's Secret Lifecycle
HashiCorp Vault For Beginners6 min read
Now that you've seen Vault dynamically generate MySQL credentials for you (magic, right?), you might be wondering:
- How long do those credentials last?
- What happens when they expire?
- Can I revoke them early?
- Can I extend them?
- Can I restrict how many times they’re used?
This chapter dives into Vault's leasing mechanism — the core engine that governs how long secrets live, how they're revoked, and how they behave after being handed out.
What Is a Lease?
When Vault generates a dynamic secret (like our MySQL credentials), it also generates a lease. A lease is like a signed contract between you and Vault:
"Here’s your secret. You're allowed to use it for X seconds or Y number of times. After that, it's gone."
Every lease has:
- A
lease_id - A
lease_duration(TTL) - A
renewableflag - Optionally, a
num_useslimit
Example:
lease_id: database/creds/readonly-role/abc123456
lease_duration: 1h
renewable: true
TTL (Time to Live)
TTL determines how long the secret remains valid. After the TTL, Vault automatically revokes the secret.
TTL can be configured:
- On the secret engine
- On the role
- At the Vault server level
Example during role creation:
vault write database/roles/readonly-role \
db_name=my-mysql-database \
creation_statements="..." \
default_ttl="1h" \
max_ttl="24h"
default_ttl: Applies to leases unless manually overridden.max_ttl: The maximum TTL even if a lease is renewed multiple times.
3. num_uses: Expire After X Uses
Besides TTL, Vault allows you to set a num_uses on a role — which limits how many times a generated secret can be used, regardless of the TTL.
Once the credential is used the specified number of times, Vault automatically revokes the lease.
This is incredibly useful for:
- One-time login credentials
- Scripts or apps that only need brief access
- Preventing credential reuse in CI/CD pipelines
Here’s how to set it correctly during role creation:
vault write database/roles/readonly-role \
db_name=my-mysql-database \
creation_statements="..." \
default_ttl="1h" \
max_ttl="24h"
num_uses=1
num_uses : Every time a secret is issued using this role, that username/password will expire after one use — no matter how much time is left on the TTL.
You can verify this behavior by issuing credentials:
vault read database/creds/readonly-role
Try using the username and password once — it’ll work.
Try again? It’s already revoked.
4. Viewing Active Leases
To list leases for a role:
vault list sys/leases/lookup/database/creds/readonly-role
To look up lease details:
vault lease lookup <lease_id>
5. Renewing a Lease
If the lease is renewable and TTL hasn’t hit max_ttl, you can extend the lease:
vault lease renew <lease_id>
This is especially useful for long-running applications or sessions that don’t want to re-authenticate.
6. Revoking a Lease
Need to shut off access early? Use:
vault lease revoke <lease_id>
This invalidates the associated secret and revokes access on the spot.
You can also revoke everything under a path:
vault lease revoke -prefix database/creds/readonly-role
7. Lease vs Static Secrets
Let’s make the distinction clear:
| Feature | Static Secret (e.g., KV) | Dynamic Secret (e.g., DB) |
|---|---|---|
| Manually managed | Yes | No |
| Automatically expired | No | Yes |
| TTL-based | No | Yes |
| num_uses support | No | Yes |
| Auto-revocation | No | Yes |
8. Why Leases Matter
This leasing model gives you control, auditability, and peace of mind. Imagine:
- An app gets hacked. Revoke the lease = instant kill switch.
- You want a password to expire after one use.
num_uses = 1. - You rotate secrets every hour. TTL handles it for you.
Vault isn’t just storing secrets. It’s managing their lifecycle securely, on your behalf.