Introduction
Tokens are the main method by which clients authenticate with Vault. Each token has a time-to-live value associated with it, which controls how long the token is valid for.
TTL Hierarchy
When a token TTL is being assigned, in general it will be limited by the shortest time configured in the following order:
- Requested/Configured - The TTL requested as part of a creation or configured as part of a role or group.
- Mount Tune - The default TTL given to any token generated by an authentication method
- System Default - The configured system default TTL as part of the Vault configuration (Default: 32 days)
*There are certain scenarios where this does not apply, such as AppRole Secret-ID TTLs.
Example
Lets take an example of the system default TTL being 32 days, and the mount tunes being the following (output trimmed for clarity):
Path Plugin Accessor Default TTL Max TTL
---- ------ -------- ----------- -------
token/ token auth_token_45c4da03 system system
userpass/ userpass auth_userpass_4f54020c 1800 system
userpass-default-ttl/ userpass auth_userpass_81a96121 system system
If I were to log in using the following command:
$ vault login -method=userpass username=test password=test
we would get a token with a TTL being 30m since the configured tune is set for 30 minutes, and this value is within the bounds of the system default:
$ vault login -method=userpass username=test password=test
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.
Key Value
--- -----
token s.3DRo26azCRzQqJJQPHskX7Ej
token_accessor Btdc4FyODPQQfkmGxa4f7Irs
token_duration 30m
token_renewable true
token_policies ["default"]
identity_policies []
policies ["default"]
token_meta_username test
If we were to log in using the "userpass-default-ttl" path instead we would see that the token generated would be valid for 32 days, as the default TTL is set to whatever the system default is since we didn't specify a TTL on the mount tune itself:
$ vault login -method=userpass -path=userpass-default-ttl username=test password=test
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.
Key Value
--- -----
token s.LuounSWi4SJzAEd3pcfxVSRg
token_accessor X2YBBzzdAyfHu1RtaI5kicUh
token_duration 768h
token_renewable true
token_policies ["default"]
identity_policies []
policies ["default"]
token_meta_username test
If we were to tune the mount to have the default TTL be 60 days and then request a token we would receive a warning, and the TTL of the generated token would be capped at the the system default TTL:
$ vault login -method=userpass username=test password=test
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.
WARNING! The following warnings were returned from Vault:
* TTL of "1440h" exceeded the effective max_ttl of "768h"; TTL value is
capped accordingly
Key Value
--- -----
token s.h8otQUbSAPfIV3D2XdImC7h4
token_accessor Qo3xvnhId5jyZlmgnPNhAF7G
token_duration 768h
token_renewable true
token_policies ["default"]
identity_policies []
policies ["default"]
token_meta_username test
Recommendation
Be aware of the relationships between the different default TTL settings when configuring auth methods. An improperly configured mount can lead to tokens being generated with longer than expected TTLs. Depending on your workflow implementation this can also lead to increased storage usage and unexpected performance issues.