Checkpoint
Service Token
/ 100
Managing Vault Tokens
This lab was developed with our partner, Hashicorp. Your personal information may be shared with Hashicorp, the lab sponsor, if you have opted in to receive product updates, announcements, and offers in your Account Profile.
GSP1006
Overview
Tokens are the core method for authentication within Vault. If you log in with Vault via an auth method, a successful authentication generates a token. Regardless, clients need valid tokens to read secrets from Vault. Furthermore, tokens can be used directly or auth methods can be used to dynamically generate tokens based on external identities.
As stated in the authentication concepts, all external authentication mechanisms, such as GitHub, map down to dynamically created tokens. These tokens have all the same properties as a normal manually created token. Within Vault, tokens map to information. The most important information mapped to a token is a set of one or more attached policies. These policies control what the token holder is allowed to do within Vault. Other mapped information includes metadata that can be viewed and is added to the audit log, such as creation time, last renewal time, and more.
In this lab, you will learn how to create, use, revoke, and manage Vault tokens.
Objectives
In this lab, you will:
- Interact with use limit tokens, periodic tokens, and short-lived tokens
- Interact with orphan tokens
- Create and test batch tokens
- Configure and test default TTLs and maximum TTLs to manage tokens
Setup and requirements
Before you click the Start Lab button
Read these instructions. Labs are timed and you cannot pause them. The timer, which starts when you click Start Lab, shows how long Google Cloud resources will be made available to you.
This hands-on lab lets you do the lab activities yourself in a real cloud environment, not in a simulation or demo environment. It does so by giving you new, temporary credentials that you use to sign in and access Google Cloud for the duration of the lab.
To complete this lab, you need:
- Access to a standard internet browser (Chrome browser recommended).
- Time to complete the lab---remember, once you start, you cannot pause a lab.
How to start your lab and sign in to the Google Cloud console
-
Click the Start Lab button. If you need to pay for the lab, a pop-up opens for you to select your payment method. On the left is the Lab Details panel with the following:
- The Open Google Cloud console button
- Time remaining
- The temporary credentials that you must use for this lab
- Other information, if needed, to step through this lab
-
Click Open Google Cloud console (or right-click and select Open Link in Incognito Window if you are running the Chrome browser).
The lab spins up resources, and then opens another tab that shows the Sign in page.
Tip: Arrange the tabs in separate windows, side-by-side.
Note: If you see the Choose an account dialog, click Use Another Account. -
If necessary, copy the Username below and paste it into the Sign in dialog.
{{{user_0.username | "Username"}}} You can also find the Username in the Lab Details panel.
-
Click Next.
-
Copy the Password below and paste it into the Welcome dialog.
{{{user_0.password | "Password"}}} You can also find the Password in the Lab Details panel.
-
Click Next.
Important: You must use the credentials the lab provides you. Do not use your Google Cloud account credentials. Note: Using your own Google Cloud account for this lab may incur extra charges. -
Click through the subsequent pages:
- Accept the terms and conditions.
- Do not add recovery options or two-factor authentication (because this is a temporary account).
- Do not sign up for free trials.
After a few moments, the Google Cloud console opens in this tab.
Activate Cloud Shell
Cloud Shell is a virtual machine that is loaded with development tools. It offers a persistent 5GB home directory and runs on the Google Cloud. Cloud Shell provides command-line access to your Google Cloud resources.
- Click Activate Cloud Shell at the top of the Google Cloud console.
When you are connected, you are already authenticated, and the project is set to your Project_ID,
gcloud
is the command-line tool for Google Cloud. It comes pre-installed on Cloud Shell and supports tab-completion.
- (Optional) You can list the active account name with this command:
- Click Authorize.
Output:
- (Optional) You can list the project ID with this command:
Output:
gcloud
, in Google Cloud, refer to the gcloud CLI overview guide.
Task 1. Install Vault
- In Cloud Shell window, add the HashiCorp GPG key:
- Add the official HashiCorp Linux repository:
- Update and install Vault:
Verify the installation
After installing Vault, verify the installation worked by checking that the Vault binary is available.
- Execute the
vault
command to verify the installation:
You should see help output similar to the following:
Task 2. Start the Vault server
With Vault installed, the next step is to start a Vault server.
Vault operates as a client/server application. The Vault server is the only piece of the Vault architecture that interacts with the data storage and backends. All operations done via the Vault CLI interact with the server over a TLS connection.
In this lab, you will start and interact with the Vault server running in development mode.
This dev-mode server requires no further setup, and your local vault CLI will be authenticated to talk to it. This makes it easy to experiment with Vault or start a Vault instance for development. Every feature of Vault is available in "dev" mode. The -dev
flag just short-circuits a lot of setup to insecure defaults.
Starting the dev server
First, start a Vault dev server. The dev server is a built-in, pre-configured server that is not very secure but useful for playing with Vault locally.
- To start the Vault dev server, run:
You should see output relating to your Vault server configuration. Notice that Unseal Key and Root Token values are displayed.
localhost
without TLS, and automatically unseals and shows you the unseal key and root access key.
Now that you have the Vault development server running, you can continue setting up access to it.
-
Open a new Cloud Shell tab.
-
Copy and run the export
VAULT_ADDR ..
. command from the terminal output. This will configure the Vault client to talk to the dev server:
The Vault CLI determines which Vault servers to send requests using the VAULT_ADDR
environment variable.
-
Save the unseal key somewhere. Don't worry about how to save this securely. For now, just save it anywhere.
-
Set the
VAULT_TOKEN
environment variable value to the generated Root Token value displayed in the terminal output:
Verify the server is running
- Verify the server is running by running the
vault status
command:
If it ran successfully, the output should look like the following:
Great! You've started the Vault development server. You can now continue on to the next section.
Tokens overview
There are two types of Vault tokens: service tokens and batch tokens. Vault persists the service tokens in its storage backend. You can renew a service token or revoke it as necessary. On the other hand, Vault does not persist the batch tokens. Batch tokens are encrypted binary large objects (blobs) that carry enough information to perform Vault actions. Therefore, batch tokens are extremely lightweight and scalable; however, they lack most of the flexibility and features of service tokens. The following features detailed in this section apply to service tokens; their applicability to batch tokens is discussed later.
The token store
Often in documentation or in help channels, the "token store" is referenced. This is the same as the token authentication backend. This is a special backend in that it is responsible for creating and storing tokens, and cannot be disabled. It is also the only auth method that has no login capability -- all actions require existing authenticated tokens.
Root tokens
Root tokens are tokens that have the root
policy attached to them. Root tokens can do anything in Vault. Anything. In addition, they are the only type of token within Vault that can be set to never expire without any renewal needed. As a result, it is purposefully hard to create root tokens; in fact there are only three ways to create root tokens:
- The initial root token generated at
vault operator init
time -- this token has no expiration - By using another root token; a root token with an expiration cannot create a root token that never expires
- By using
vault operator generate-root
(example) with the permission of a quorum of unseal key holders
Root tokens are useful in development but should be extremely carefully guarded in production. In fact, the Vault team recommends that root tokens are only used for just enough initial setup (usually, setting up auth methods and policies necessary to allow administrators to acquire more limited tokens) or in emergencies, and are revoked immediately after they are no longer needed. If a new root token is needed, the operator generate-root
command and associated API endpoint can be used to generate one on-the-fly.
Token hierarchies and orphan tokens
Normally, when a token holder creates new tokens, these tokens will be created as children of the original token; tokens they create will be children of them; and so on. When a parent token is revoked, all of its child tokens -- and all of their leases -- are revoked as well. This ensures that a user cannot escape revocation by simply generating a never-ending tree of child tokens.
Often this behavior is not desired, so users with appropriate access can create orphan tokens. These tokens have no parent, meaning they are the root of their own token tree. These orphan tokens can be created:
- Via
write
access to theauth/token/create-orphan
endpoint - By having
sudo
orroot
access to theauth/token/create
and setting theno_parent
parameter to true - Via token store roles
- By logging in with any other (non-
token
) auth method
Users with appropriate permissions can also use the auth/token/revoke-orphan
endpoint, which revokes the given token but rather than revoke the rest of the tree, it instead sets the tokens' immediate children to be orphans. Use with caution!
Token accessors
When tokens are created, a token accessor is also created and returned. This accessor is a value that acts as a reference to a token and can only be used to perform limited actions:
- Look up a token's properties (not including the actual token ID)
- Look up a token's capabilities on a path
- Renew the token
- Revoke the token
The token making the call, not the token associated with the accessor, must have appropriate permissions for these functions.
There are many useful workflows around token accessors. As an example, a service that creates tokens on behalf of another service (such as the Nomad scheduler) can store the accessor correlated with a particular job ID. When the job is complete, the accessor can be used to instantly revoke the token given to the job and all of its leased credentials, limiting the chance that a bad actor will discover and use them.
Audit devices can optionally be set to not obfuscate token accessors in audit logs. This provides a way to quickly revoke tokens in case of an emergency. However, it also means that the audit logs can be used to perform a larger-scale denial of service attack.
Finally, the only way to "list tokens" is via the auth/token/accessors
command, which actually gives a list of token accessors. While this is still a dangerous endpoint (since listing all of the accessors means that they can then be used to revoke all tokens), it also provides a way to audit and revoke the currently-active set of tokens.
Token time-to-live, periodic tokens, and explicit max TTLs
Every non-root token has a time-to-live (TTL) associated with it, which is a current period of validity since either the token's creation time or last renewal time, whichever is more recent. (Root tokens may have a TTL associated, but the TTL may also be 0, indicating a token that never expires). After the current TTL is up, the token will no longer function——it, and its associated leases, are revoked.
If the token is renewable, Vault can be asked to extend the token validity period using vault token renew
or the appropriate renewal endpoint. At this time, various factors come into play. What happens depends upon whether the token is a periodic token (available for creation by root
/sudo
users, token store roles, or some auth methods), has an explicit maximum TTL attached, or neither.
For more information on TTLs, you can check out the Token Time-To-Live, Periodic Tokens, and Explicit Max TTLs documentation.
Task 3. Service tokens
Tokens allow Vault clients to read or write secrets from Vault; therefore, it is critical to use a specific type of token based on the use case. In this section, you will learn about the lifecycle of different token types and how to manage them.
Service token lifecycle
Every non-root token has a time-to-live (TTL). When a token expires, Vault automatically revokes it. If you create a new token, the token you used to create the token becomes the parent token. Once the parent token expires, so do all its children regardless of their own TTLs.
Suppose a hierarchy exists with respective TTL as follows:
In this scenario, the token s.1d3fd4b2..
will expire in two hours. Although its child token (s.794b6f2f...
) has TTL of three hours, Vault will revoke the child token when its parent expires.
When the top-level token (s.b519c6aa...
) expires, Vault will revoke all tokens under the tree (s.6a2cf3e7...
, s.1d3fd4b2...
, and s.794b6f2f...
) regardless of their TTL.
TTL and max TTL
If the token is renewable, you can use vault token renew
command to extend the token's TTL before it expires. You can repeatedly renew a token until it reaches its maximum TTL.
For example, if a token's TTL is 30 minutes and the maximum TTL is 24 hours, you can renew the token before reaching the 30 minutes. You can renew the token multiple times if you are using it. However, once the token reaches the 24 hours of its first creation, you can no longer renew the token.
Token types
The following table details the different types of service tokens and their associated usages:
Token type | Usage |
---|---|
Use limit tokens | Tokens that are only good to invoke a specific number of operations. |
Periodic service tokens | Tokens that can be renewed indefinitely. |
Short-lived tokens | Tokens that are valid for a short time to avoid keeping unused tokens. |
Orphan tokens | Tokens that are root of their own token tree. |
Tokens with use limit
In addition to TTL and max TTL, you can set the number of uses for tokens. The tokens with a use limit expire at the end of their last use regardless of their remaining TTLs. On the same note, use limit tokens expire at the end of their TTLs regardless of their remaining uses.
To create tokens with a use limit, set the number of uses when you create them.
-
Navigate to your open Cloud Shell tab.
-
To view optional parameters to create tokens, run the command with
-help
flag:
There are a number of parameters you can set.
- Create a token with TTL of 1 hour and a use limit of 2. Attach the
default
policy:
Your output should resemble the following:
- Store the generated token in an environment variable,
USE_LIMIT_TOKEN
:
- Set the
VAULT_TOKEN
value to the token you just generated, and invoke any CLI command:
Notice that the num_uses
is now 1
.
- Run another CLI command using the token:
- Try to read the value now using the same token:
You should see the following error:
The first command read the token's properties and then wrote a value to the cubbyhole secrets engine. This exhausted the use limit of 2 for this token. Therefore, the attempt to read the secret from the cubbyhole failed.
Periodic service tokens
Root or sudo users have the ability to generate periodic tokens. Periodic tokens have a TTL (validity period), but no max TTL; therefore, they may live for an infinite duration of time so long as they are renewed within their TTL. This is useful for long-running services that cannot handle regenerating a token.
- Start by creating a token with 24 hours period with the
default
policy attached:
Your output should resemble the following:
You can see the generated token's metadata. In this example, the generated token value is s.s7bMPX51JesC1VYJwdZf8ylt
.
- Lookup your token:
Notice the period 24h
and renewable true
metadata. You can renew the generated token indefinitely for as long as it does not expire. If you do not renew, the token expires after 24 hours.
Renew service tokens
You can renew the service token's TTL as long as it has not expired.
- Run the following command to create a new token:
The generated token has a TTL of 45 seconds, and max TTL of 2 minutes (120 seconds).
- Set an environment variable
$TOKEN
to your token you just created:
- Use the
vault token renew
command to renew the service token's TTL before the token expires:
You should see the following output:
- Now, renew and extend the token's TTL to 60 seconds:
Notice that the token TTL (token_duration
) is now 1 minute instead of 45 seconds. Because the explicit max TTL is set to 2 minutes, you will not be able to renew the token after 2 minutes.
- Run the renew command again:
As time passes, Vault returns a message such as TTL of "26s" exceeded the effective max_ttl of "10s"
; TTL value is capped accordingly to indicate that the token TTL cannot exceed 2 minutes from its creation time. Eventually, the token expires and Vault automatically revokes it. Once the token expires, the renew command returns token not found message.
- Once the TTL has run out, execute a the following command to verify the revocation:
You should see the following error:
Short-lived tokens
In this section you will create a new service token with TTL of 60 seconds which means that the token gets automatically revoked after 60 seconds.
- Create a token with TTL of 60 seconds:
You should see the following output:
- Lookup the generated token's metadata:
Your output should resemble:
vault token lookup
command returns the token's properties. In this example, it shows that this token has 38 more seconds before it expires.
When you execute a Vault command using the new token immediately following its creation, it should work. Wait for 60 seconds and try again. It returns a 403 error, which indicates a forbidden API call due to expired token usage:
Orphan tokens
Orphan tokens are not children of their parent; therefore, orphan tokens do not expire when their parent does. Note that orphan tokens still expire when their own max TTL is reached.
- Run the following command to create an
orphan
token. Note that the following CLI command requires root token or sudo capability on theauth/token/create
path:
- Lookup the generated token's metadata:
You should see the following output:
Notice the orphan
key is set to true.
Token role
Instead of passing a number of parameters, you can create a role with a set of parameter values set. Roles enforce specific behavior when creating tokens that allow token functionality that is otherwise not available or would require sudo
/ root
privileges to access. Role parameters, when set, override any provided options to the create endpoints.
- Create a token role named
zabbix
:
- Create a token for
zabbix
role:
You should receive the following output:
Revoke service tokens
If a user or machine needs a temporal access to Vault, you can set a short TTL or a number of uses to a service token so the token is automatically revoked at the end of its life. But if any suspicious activity was detected, Vault has built-in support for revocation of service tokens before reaching its TTL.
You can revoke service tokens using the vault token revoke
command or the auth/token/revoke
API endpoint.
In this section, you are going to create tokens with the following hierarchy and inspect the token lifecycle.
- Create a test policy:
- Create a token and save its value in a file,
parent_token.txt
:
The generated token has a TTL of 1 minute (60 seconds).
- Create a token using the parent token and save its value in a file,
child_token.txt
:
The generated token has a TTL of 3 minute (180 seconds) while its parent token's TTL is 1 minute.
- Create an orphan token using the parent token and save its value in a file,
orphan_token.txt
:
The generated token is an orphan token with a TTL of 3 minute (180 seconds).
- Now, revoke the parent token:
- Verify that the token no longer exists by looking it up:
Vault returns an error message.
- Look up the child token:
Vault returns the bad token
error because Vault revoked the child token along with its parent token.
- Look up the orphan token:
Because each orphan token is the root of its own token tree, it exists until it expires. Therefore, the command displays the detail information about the orphan token.
-accessor
flag.
Apply token types
In the previous sections, you've learned how you can set the token's lifecycle. The next step is to apply this to generate tokens for your applications. Vault clients first authenticate with Vault using an auth method to acquire a token. There are auth methods aimed to authenticate applications or machines. Once its identity was verified, Vault server will return a token with appropriate policies attached.
You will be using the AppRole auth method to demonstrate this.
- First, unset the
VAULT_TOKEN
environment variable you created when setting up Vault:
- Enable the
approle
auth method:
- Create a role for your app specifying that the generated token type is periodic and expires after 24 hours if not renewed:
This example defines a role named, "jenkins". The tokens generated for this role will be a periodic token with jenkins
policy attached.
- Retrieve the RoleID for the
jenkins
role and save it in a file,role_id.txt
:
- Generate a SecretID for the
jenkins
role and save it in a file,secret_id.txt
:
- Authenticate with Vault using the generated
role_id
andsecret_id
:
Your output should be similar to the following:
- View the token details:
Your output should resemble the following:
The output shows the period
of 24 hours, and the jenkins
policy is attached.
- Run the following command to copy the values of the policies associated with the token to a text file:
- Run the following command to copy this file to a pre-created Cloud Storage bucket to track your progress:
Click Check my progress to verify that you've performed the above task.
Service tokens overview
This section walked through the Vault token fundamentals. In the real world, you would rarely create tokens using the vault token create
commands or the /auth/token/create
endpoint. In most cases, you specify the type of token in the context of auth methods as demonstrated in the Apply token type section.
Integrating your application to read or write secrets to Vault may require you to:
- Authenticate with Vault using an auth method
- Maintain the token
- Renew or revoke the token if necessary
Vault Agent can help to simplify the introduction of Vault to your applications. The App Integration collection lists tutorials that introduce different approaches.
But first, go through the next section on Batch tokens to understand the difference between the service tokens and batch tokens so that you can decide which token type is best suited for your use case.
Task 4. Batch tokens
Batch tokens are encrypted blobs that carry enough information for them to be used for Vault actions, but they require no storage on disk to track them. As a result they are extremely lightweight and scalable, but lack most of the flexibility and features of service tokens. Batch tokens are not persisted and cannot be listed or manually revoked. In this section you will create, test, and apply batch tokens to demonstrate their capabilities.
Service tokens vs. batch tokens
As the number of machines and apps using Vault for secret management scales, Vault must manage the growing number of client tokens. The creation of service tokens can affect Vault performance since they must be replicated across the primary and secondary clusters. On the other hand, batch tokens are neither persisted to disk nor live in memory; they are not a part of the data replication process.
Due to the lack of features with batch tokens, it's preferable to use service tokens in most use cases. However, think of a scenario where you have a large number of containers (e.g. 100,000s) start up and all request a token from Vault. The use of batch tokens can reduce the stress on the storage backend and improve the overall performance.
Batch tokens are designed to be lightweight with limited flexibility. The following Batch Tokens documentation highlights the differences between batch tokens and service tokens.
Create batch tokens
- Create a test policy:
- Create a batch token with the
test
policy attached, and set a TTL so the token is valid for 20 minutes:
You should receive the following output:
b
. to indicate that it is a batch token.
- Lookup the token details:
Your output should resemble:
renewable
is set to false
.
Test batch tokens
- Log in with the generated batch token:
- Create some secrets in the Cubbyhole secrets engine:
You should see the following output. As you can see, batch tokens do not have a cubbyhole associated with it:
- Create a child token:
You should see the following output. As you can see, batch tokens cannot create child tokens even if their policies have the capabilities to do so.
- Log back in as
root
. Use your root token from the setup section:
- Try revoking the batch token:
You'll see the following error:
The TTL values of batch tokens are fixed. In this example, the TTL is set to 20 minutes. After 20 minutes, the token expires and Vault will revoke it. Batch tokens cannot be renewed.
Apply batch tokens
Similar to what you did in the previously in the Tokens section, use the AppRole auth method as an example to generate a batch token upon a successful login.
- Create a role called "shipping", which generates a batch token with a TTL of 20 minutes:
- Retrieve the RoleID for the
shipping
role and save it to a file:
- Generate a SecretID for the
shipping
role and save it to a file as well:
- Authenticate with Vault using the generated
role_id
andsecret_id
:
Your output should resemble:
- View the token details:
Example output:
Great! The output shows the type is batch
. In this section you learned the characteristics of batch tokens. In the next section you will learn about Token Management and the basic operational tasks for the Token auth method.
Task 5. Token management
The previous sections demonstrated the lifecycle of Vault tokens. Remember that Vault persists the service tokens in the storage backend until they expire and Vault revokes them. Depending on the auth method, the generated service token varies in its size due to the amount of metadata attached to it. To avoid unused tokens from overtaking the storage memory, set an explicit token time-to-live (TTL) so that Vault will automatically revoke expired tokens.
Configure the token TTL
When you create tokens or leases with no specific TTL values, the default value applies to them.
- Create a token with no specific TTL value and attach the
default
policy:
Your output should resemble:
Notice that the token TTL (token_duration
) is 768 hours although you did not provide the TTL value.
- View the token auth method settings:
The token
auth method is the core method of authentication with Vault; therefore, Vault enables it by default while other auth methods must be enabled explicitly. Notice that the token_type
is default-service
.
token
auth method is set to system
.
- Read the default TTL settings for the token auth method:
The default token TTL (default_lease_ttl
) and the max TTL (max_lease_ttl
) is set to 32 days (768 hours). This implies that the tokens are valid for 32 days from its creation whether an app is using the token or not.
The previous sections demonstrated various parameters to control the token lifecycle; however, users often neglect to specify the token TTL.
You can override the default TTL on the token
auth method itself so that Vault will revoke expired token in a reasonable amount of time.
- Run the following command to set the default TTL to 8 hours and max TTL to 30 days (720 hours):
- Read the configuration to verify:
Now you will verify the default TTL and max TTL of your tokens.
- Again, create a new token without specifying its TTL:
Your output should look like the following:
/sys/auth//tune
endpoint to override the system defaults.
Get the token count
If the token TTL is set reasonably, Vault should not be storing many unused tokens.
- Get the service token counts:
Your output should read:
The example output shows that there are 7 service tokens. In reality, you may have hundreds of app instances connecting to Vault. Then it becomes more important to know how many tokens exist in the Vault's storage backend.
sys/internal/counters/tokens
endpoint returns the number of service tokens in Vault.
API call using cURL
You can also get the service token counts using the sys/internal/counters/tokens
endpoint.
- Replace
<your root token>
with your root token:
Your output should resemble:
Congratulations!
In this lab, you learned how to create, use, and revoke use limit tokens, periodic tokens, and short-lived tokens. You then created and tested orphan tokens as well as batch tokens. Lastly, you configued and tested default TTLs and maxmimum TTLs to further control tokens.
Next steps / Learn more
Check out the following for more information on Vault
Google Cloud training and certification
...helps you make the most of Google Cloud technologies. Our classes include technical skills and best practices to help you get up to speed quickly and continue your learning journey. We offer fundamental to advanced level training, with on-demand, live, and virtual options to suit your busy schedule. Certifications help you validate and prove your skill and expertise in Google Cloud technologies.
Manual Last Updated October 21, 2022
Lab Last Tested September 29, 2022
Copyright 2023 Google LLC All rights reserved. Google and the Google logo are trademarks of Google LLC. All other company and product names may be trademarks of the respective companies with which they are associated.