Vault Associate Certification (Part 4): Manage Vault leases

In the previous post I covered the topic of tokens. One property of a token I did not cover was lease. Leases show up in one other part of Vault as well: dynamic secrets. I will cover secret engines in the next section of this post, so in this post I will mainly focus on leases in the context of tokens and return to leases for secrets in the next post.

Leases make up the fourth objective in the Vault certification journey. This objective covers the following sub-objectives:

• Explain the purpose of a lease ID
• Renew leases
• Revoke leases

This is a relatively short objective - that is a nice contrast to the previous objective which was rather long! But keep in mind that we will hear more about leases in the next post.

Let's get started exploring leases!

Explain the purpose of a lease ID

This sub-objective starts with a brief introduction to the concept of leases and how leases for secrets and tokens differ in one major way:

The concept of leases: The concept of a lease is a bit fuzzy when we talk about tokens. It is much more explicit when we talk about secrets! However, as I stated in the introduction of this post I will focus on leases for tokens in this post. Thus, I need to shortly discuss the concept of leases and why token leases are a bit fuzzy compared to secret leases.

When you generate a token you get the token ID and a bunch of metadata attached to the token. Specifically related to the concept of a lease the token has some metadata concerning the time-to-live (TTL). Think of a leased token as a borrowed token. We borrow, or lease, a token from Vault. The token, or lease, is valid for a given TTL. Possibly we could extend the TTL, as long as the token metadata allows for it (i.e. renewable is true and we have not surpassed the explicit_max_ttl). If we do not extend the TTL (i.e. renew the token), then our lease expires - and with it the token validity.

Why do I say that the concept of a token lease is a bit fuzzy? It is because we have no explicit token lease ID. The current sub-objective we are going through explicitly asks for an explanation of the purpose of a lease ID. This is why token leases are a bit fuzzy.

When we look at leases in relation to secrets in the next post we'll see that secret leases have lease IDs. We'll also see how the Vault CLI allows us to explicitly work with secret leases through vault lease commands. More on that in the next post! For now, let us accept that token leases have no explicit ID except for the token ID itself. In the rest of this post we'll think of the token ID as the lease ID, but remember that they are only conceptually similar.

The purpose of a lease ID is to easily be able to refer to the lease and perform actions on it. These actions could be to look up details of the lease, to renew the lease, or to revoke the lease. This is true for token leases and secret leases. The following two sections will show examples of how to renew leases for tokens and secrets, as well as how to revoke leases for tokens and secrets. My third example concerned looking up the details for a lease. For a token this is done using the following command:

$ vault token lookup <token ID>

And for a secret lease this is done using the following command:

$ vault lease lookup <lease ID>

These command show the similarity of working with token leases and secret leases, and this will also be true for the rest of the commands in this post.

Renew leases

Let us create (or lease) a new token to begin with:

$ vault token create -policy=default -ttl=10m -renewable=true

Key                  Value
---                  -----
token                hvs.CAESIJHUWM<truncated>QmluaGFlZDFsa2o
token_accessor       yYpBXi0dhhM3Fo3j5s13cFeR
token_duration       10m
token_renewable      true
token_policies       ["default"]
identity_policies    []
policies             ["default"]

This token is leased for ten minutes (-ttl=10m). It is renewable (-renewable=true), so we should be able to extend our lease for this token.

Renewing a lease, or extending the lease, for a token is as simple as running the following Vault CLI command:

$ vault token renew hvs.CAESIJHUWM<truncated>QmluaGFlZDFsa2o

Key                  Value
---                  -----
token                hvs.CAESIJHUWM<truncated>QmluaGFlZDFsa2o
token_accessor       yYpBXi0dhhM3Fo3j5s13cFeR
token_duration       10m
token_renewable      true
token_policies       ["default"]
identity_policies    []
policies             ["default"]

The TTL is once again ten minutes.

We'll see in the next post that the command for renewing a lease for a secret is similar in nature, but we use a different sub-command in the Vault CLI and we use a lease ID to refer to the lease:

$ vault lease renew <lease ID>

Revoke leases

This section continues where the last section stopped. We have a valid token, but what if we want to revoke it before the TTL expires by itself? This is done using the following command:

$ vault token revoke hvs.CAESIJHUWM<truncated>QmluaGFlZDFsa2o

Success! Revoked token (if it existed)

The command output says that the token was revoked, but the output is the same no matter if the token existed or not. This is a nice feature because it means that the command is idempotent, it produces the same result even if we run it multiple times in a row.

In the next post we'll see that a lease for a secret is revoked in a similar way, through the use of the following command:

$ vault lease revoke <lease ID>