Parent Child Token Hierarchy

This is a brief guide that uses a practical example to build on the Token Hierarchies and Orphan Tokens documentation and demonstrates the token hierarchy in a parent token/child token manner.

This example uses the vault CLI for convenience, but it could also be demonstrated directly with API calls if necessary.

Define Example Policy

We will begin by defining a contrived example policy providing a minimum of capabilities for creating tokens:

$ vault policy write example-token-create - << EOF
// Example token creation policy
path "auth/token/create" {
  capabilities = ["create", "update"]
}
EOF
Success! Uploaded policy: example-token-create

Create Initial (Parent) Token

Next, let’s create a token with an explicit TTL of 5 minutes:

$ vault token create -policy=example-token-create -ttl=5m
Key                  Value
---                  -----
token                s.vx6zfziRnKYzZ4SXngh0NlzG
token_accessor       y60QzO3mf7xSXoCDw2Drn17k
token_duration       5m
token_renewable      true
token_policies       ["default" "example-token-create"]
identity_policies    []
policies             ["default" "example-token-create"]

Login with Parent Token

Then we log in with that token:

$ vault login s.vx6zfziRnKYzZ4SXngh0NlzG
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.vx6zfziRnKYzZ4SXngh0NlzG
token_accessor       y60QzO3mf7xSXoCDw2Drn17k
token_duration       4m40s
token_renewable      true
token_policies       ["default" "example-token-create"]
identity_policies    []
policies             ["default" "example-token-create"]

Create Second (Child) Token

Now while logged in with the Parent token, we create a new token (the child token) with a TTL of 15 minutes:

$ vault token create -ttl=15m
Key                  Value
---                  -----
token                s.LpdjmDpSOlOu7r6NXZx6o1CU
token_accessor       uRSsO3lh4OfBiDkZw7vrCnZb
token_duration       15m
token_renewable      true
token_policies       ["default" "example-token-create"]
identity_policies    []
policies             ["default" "example-token-create"]

Login with Child Token

Login with the child token, which we expect to be usable for 15 minutes:

vault login s.LpdjmDpSOlOu7r6NXZx6o1CU
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.LpdjmDpSOlOu7r6NXZx6o1CU
token_accessor       uRSsO3lh4OfBiDkZw7vrCnZb
token_duration       13m29s
token_renewable      true
token_policies       ["default" "example-token-create"]
identity_policies    []
policies             ["default" "example-token-create"]

Perform Token Lookup

Now let’s check our current token with vault token lookup:

$ vault token lookup
Key                 Value
---                 -----
accessor            uRSsO3lh4OfBiDkZw7vrCnZb
creation_time       1567182084
creation_ttl        15m
display_name        token
entity_id           n/a
expire_time         2019-08-30T16:36:24.9685698Z
explicit_max_ttl    0s
id                  s.LpdjmDpSOlOu7r6NXZx6o1CU
issue_time          2019-08-30T16:21:24.9685569Z
meta                <nil>
num_uses            0
orphan              false
path                auth/token/create
policies            [default example-token-create]
renewable           true
ttl                 13m18s
type                service

A lookup of the token shows 13 minutes, 18 seconds remaining; your time will differ, but it will certainly be greater than 5 minutes (unless you took a long break).

Now, wait about 4 minutes and try again:

$ vault token lookup
Error looking up token: Error making API request.

URL: GET https://127.0.0.1:8200/v1/auth/token/lookup-self
Code: 403. Errors:

* permission denied

What happened?!

The parent token (the one with the TTL of 5 minutes) expired, and since the child token we created was a child of that token it was also revoked even though we specified 15 minutes for its TTL.

Resources

1. Token Hierarchies and Orphan Tokens documentation
2. Vault Commands