HashiCorp Developer AI Private beta now available Sign up today
Vault
Vault Home

Tune the lease time-to-live (TTL)

The benefit of using Vault's dynamic secrets engines and auth methods is the ability to control how long the Vault-managed credentials (leases) remain valid. Often times, you generate short-lived credentials or tokens to reduce the risk of unauthorized attacks caused by leaked credentials or tokens. If you do not explicitly specify the time-to-live (TTL), Vault generates leases with TTL of 32 days by default.

For example, you enabled AppRole auth method at approle, and create a role named read-only with max lease TTL of 120 days. 

$ vault write auth/approle/role/read-only token_policies="read-only" \
    token_ttl=90d token_max_ttl=120d

The command returns a warning about the TTL exceeding the mount's max TTL value.

WARNING! The following warnings were returned from Vault:

  * token_max_ttl is greater than the backend mount's maximum TTL value;
  issued tokens' max TTL value will be truncated

Therefore, it will return a client token with TTL of 768 hours (32 days) instead of 120 days.

$ vault write auth/approle/login role_id=<ROLE_ID> secret_id=<SECRET_ID>

WARNING! The following warnings were returned from Vault:

  * TTL of "2880h" exceeded the effective max_ttl of "768h"; TTL value is
  capped accordingly

Key                     Value
---                     -----
token                   hvs.CAESIJeVezY3UObHXTvzpI722q0MmaARB1692fT-MmdzcryvGh4KHGh2cy43czViYXVZS3FnSzltWmdVZ3Q0MmFTdkc
token_accessor          wXTOvz5xxBi2vvUpTBhemUXr
token_duration          768h
token_renewable         true
token_policies          ["default" "read-only"]
identity_policies       []
policies                ["default" "read-only"]
token_meta_role_name    read-only

Max lease TTL on an auth mount

You cannot set the TTL for a role to go beyond the max lease TTL set on the AppRole auth mount (approle in this example). The default lease TTL and max lease TTL are 32 days (768 hours).

$ vault read sys/auth/approle/tune

Output:

Key                  Value
---                  -----
default_lease_ttl    768h
description          n/a
force_no_cache       false
max_lease_ttl        768h
token_type           default-service

If the desired max lease TTL is 120 days (2880 hours), update the max lease TTL on the mount. 

$ vault auth tune -max-lease-ttl=120d approle

The following command lists all available parameters that you can tune.

$ vault auth tune -h

Now, the AppRole will generate a lease with token duration of 120 days (2880 hours). 

$ vault write auth/approle/login role_id=<ROLE_ID> secret_id=<SECRET_ID>

Key                     Value
---                     -----
token                   hvs.CAESIOzTpLX4naKw-epzhcb3DneZ9ZuRTx4tKh5mTT1CajLQGh4KHGh2cy5TUFFhY3QzVzdmSTFwQUduOWlrMVRWaUE
token_accessor          blc2MGA4EmmqEROzqlotFbqr
token_duration          2880h
token_renewable         true
token_policies          ["default" "jenkins"]
identity_policies       []
policies                ["default" "jenkins"]
token_meta_role_name    jenkins

Max lease TTL on a secrets mount

Similar to the AppRole auth method example, you can tune the max lease TTL on dynamic secrets.

For example, you enabled database secrets engine at mongodb and create a role named tester with max lease TTL of 120 days (2880 hours). When you request a database credential for the tester role, it returns a warning, and its lease duration is 32 days (768 hours) instead of 120 days.

$ vault read mongodb/creds/tester

WARNING! The following warnings were returned from Vault:

  * TTL of "2880h" exceeded the effective max_ttl of "768h"; TTL value is
  capped accordingly

Key                Value
---                -----
lease_id           mongodb/creds/tester/fVPt15506k3UW9n4pq0kIpBH
lease_duration     768h
lease_renewable    true
password           Eskkx6yRhAN4--H9WL7B
username           v-token-tester-6BtY903qOZBpzYa4yQs8-1724715513

To set the desired TTL on the role, tune the max lease TTL on the mongodb mount.

$ vault secrets tune -max-lease-ttl=120d mongodb

Verify the configured max lease TTL available on the mount.

$ vault read sys/mounts/mongodb/tune

Key                  Value
---                  -----
default_lease_ttl    768h
description          n/a
force_no_cache       false
max_lease_ttl        2880h

The following command lists all available parameters that you can tune.

$ vault secrets tune -h

When you introduce Vault into your existing system, the existing applications may not be able to handle short-lived leases. You can tune the default TTLs on each mount.

On the similar note, if the system default of 32 days is too long, you can tune the default TTL to be shorter to comply with your organization's policy.

API

Edit this page on GitHub