Token roles, leases, renewals and documentation.

[Henti Smith]

Good morning all. 

I need some help in clarifying how the new token roles system works. My requirement is to create a renewable token with a backup policy and a lease the token is valid for, which then gets used in a backup script. Once the backup scripts runs successfully, it renews the lease the token is valid for, for the next run. So the only way the token becomes invalid, is that the token is not renewed within the lease period, or is specifically revoked. this means as long as the backup script runs as expected. the token will be valid indefinitely. 

My understanding of the documentation is as follows to create this setup. 

I have a backup policy 

path "transit/datakey/plaintext/backupkey" {
    policy = "write"
}

I then create the token role with 

vault write auth/token/roles/backup period=432000 allowed_policies="backup"

And then create the token with 

vault write -f auth/token/create/backup

Which outputs 

token          74ee13f0-4316-484b-a44a-f5d208d8404b
token_accessor 27aa8d35-76b3-4e1d-a18a-6a99fcfa797c
token_duration 432000
token_renewable true
token_policies [backup default]

Now this is the first place where things get confusing as the documentation at https://www.vaultproject.io/docs/auth/token.html has the following as the expected output. 

{
  "auth": {
    "client_token": "ABCD",
    "policies": ["web", "stage"],
    "metadata": {"user": "armon"},
    "lease_duration": 3600, "renewable": true,
  }
}

As you can see, there is no matches in key names between the output of the write command and the documentation. 

Next I read the token data. 

$ vault read /auth/token/lookup/f05b36da-8349-f191-7282-4d5daa2ac118
Key             Value
---             -----
accessor         27aa8d35-76b3-4e1d-a18a-6a99fcfa797c
creation_time    1471239078
creation_ttl     432000
display_name     token
explicit_max_ttl 0
id               74ee13f0-4316-484b-a44a-f5d208d8404b
meta             <nil>
num_uses         0
orphan           false
path             auth/token/create/backup
policies         [backup default]
renewable        true
role             backup
ttl              431117

So far, this looks good. Token is renewable, explicit_max_ttl is 0 (unlimited), which by my understanding of the documentation, means there is no TTL. When I try to renew the token, however. 

$ vault renew 74ee13f0-4316-484b-a44a-f5d208d8404b
Renew error: Error making API request.


URL: PUT https://vault.test.local:8200/v1/sys/renew/74ee13f0-4316-484b-a44a-f5d208d8404b
Code: 400. Errors:

I'm sure I'm missing something somewhere, but really not sure where to look. 

The differences between TTL and Lease is not really clear in my head, nor the processes on how to interact with them to achieve my goal as set out above. 

Can somebody please point me in the right direction. 

Regards

Henti 

[Jeff Mitchell]

Hi Henti,

> vault write -f auth/token/create/backup
>
> Which outputs
>
> token 74ee13f0-4316-484b-a44a-f5d208d8404b
> token_accessor 27aa8d35-76b3-4e1d-a18a-6a99fcfa797c
> token_duration 432000
> token_renewable true
> token_policies [backup default]
>
> Now this is the first place where things get confusing as the documentation
> at https://www.vaultproject.io/docs/auth/token.html has the following as the
> expected output.
>
> {
> "auth": {
> "client_token": "ABCD",
> "policies": ["web", "stage"],
> "metadata": {"user": "armon"},
> "lease_duration": 3600, "renewable": true,
> }
> }

The example on the docs is listing the output from an API call
directly against Vault. The CLI is an API client but doesn't pass this
through directly, and instead is doing some formatting to make it
obvious what the token properties are. If you use '-format=json'
you'll see the raw output.

> Next I read the token data.
>
> $ vault read /auth/token/lookup/f05b36da-8349-f191-7282-4d5daa2ac118
> Key Value
> --- -----
> accessor 27aa8d35-76b3-4e1d-a18a-6a99fcfa797c
> creation_time 1471239078
> creation_ttl 432000
> display_name token
> explicit_max_ttl 0
> id 74ee13f0-4316-484b-a44a-f5d208d8404b
> meta <nil>
> num_uses 0
> orphan false
> path auth/token/create/backup
> policies [backup default]
> renewable true
> role backup
> ttl 431117
>
> So far, this looks good. Token is renewable, explicit_max_ttl is 0
> (unlimited), which by my understanding of the documentation, means there is
> no TTL.

No, this isn't the case. The explicit max TTL is a property of the
token that can allow you to limit its lifetime irrespective of any
settings within Vault (the default max, mount max, etc.) I recommend
taking a look at
https://github.com/hashicorp/vault/blob/master/website/source/docs/concepts/tokens.html.md
which has been totally rewritten and explains these concepts (it'll
replace the version on the website right now when 0.6.1 is final).

What will allow you to keep renewing this token forever is the period
that you set on the role associated with the token.

> When I try to renew the token, however.
> $ vault renew 74ee13f0-4316-484b-a44a-f5d208d8404b
> Renew error: Error making API request.
>
>
> URL: PUT
> https://vault.test.local:8200/v1/sys/renew/74ee13f0-4316-484b-a44a-f5d208d8404b
> Code: 400. Errors:

For tokens, the CLI command is `vault token-renew`. `vault renew` is
used for leases like database credentials. In addition, if you give
the token value to the token-renew command, it will use the
auth/token/renew endpoint which is not part of the default policy, so
if you have not added it to the backup policy you won't have access.
Instead, simply call the token-renew command with no argument and it
will use the value of the token from VAULT_TOKEN or ~/.vault-token (if
you used 'vault auth'). This path then uses the auth/token/renew-self
endpoint, which *is* a part of the default policy.

Best,
Jeff