Before a client can interact with Vault, it must authenticate against an auth method to acquire a token. This token has policies attached so that the behavior of the client can be governed.
In this tutorial, you will enable and configure AppRole auth method.
Important: As with secrets engines and policies, auth methods are tied to
a namespace. The auth method enabled on the
admin namespace is only
available to the
admin namespace and generates a token available to use
The steps described in this tutorial involve two personas:
- admin - Vault admin with privileged permissions to configure an auth method
- app - Vault client that consumes secrets stored in Vault
NOTE: This step assumes that you created and connected to the HCP Vault
cluster in the Create a Vault Cluster on HashiCorp Cloud Platform
(HCP) step, and also completed the Create
Vault Policies tutorial so that the
»Enable AppRole auth method
The AppRole auth method must be enabled before it can be used.
NOTE: If you receive any errors after making a configuration change in the
Vault UI, such as
404 page could not be found refresh the page.
In the Vault UI, make sure that current namespace is
Click the Access tab on top.
Click Enable new method.
Select the AppRole radio button and click Next.
Leave the path value unchanged and click Enable Method.
Without making any change, click < approle to view its current configuration.
»Create a role with policy attached
When you enabled the AppRole auth method, it was mounted at the default
path. In this example, you are going to create a role for the
webapp in our scenario) with
tester policy attached.
You will now create a new
webapp role with the generated token's time-to-live (TTL)
set to 1 hour and can be renewed for up to 4 hours from the time of its creation.
Click the Vault CLI shell icon (
>_) to open a command shell in the browser.
Copy the command below.
vault write auth/approle/role/webapp token_policies="tester" token_ttl=1h token_max_ttl=4h
Paste the command into the command shell in the browser and press the enter button.
»Generate RoleID and SecretID
The RoleID and SecretID are like a username and password that a machine or app uses to authenticate.
To retrieve the RoleID, invoke the
endpoint. To generate a new SecretID, invoke the
Click the Vault CLI shell icon (
>_) to open a command shell.
Read the RoleID.
$ vault read auth/approle/role/webapp/role-id
Generate a new SecretID of the
$ vault write -force auth/approle/role/webapp/secret-id
-f) flag forces the
writeoperation to continue without any data values specified. Or you can set parameters such as
secret-idare the credentials that your trusted application uses to authenticate with Vault.
The RoleID is similar to a username; therefore, you will get the same value
for a given role. In this case, the
webapp role has a fixed RoleID. While
SecretID is similar to a password that Vault will generate a new value every
time you request it.
»Test and validate
The client (in this case, webapp) uses the RoleID and SecretID passed by the admin to authenticate with Vault. If webapp did not receive the RoleID and/or SecretID, the admin needs to investigate.
Refer to the Advanced Features section for further discussion on distributing the RoleID and SecretID to the client app securely.
- To login, use the
auth/approle/loginendpoint by passing the RoleID and SecretID.
Important: Replace the role_id and secret_id values in the example with those generated in the Generate RoleID and SecretID section above.
$ vault write auth/approle/login \ role_id="675a50e7-cfe0-be76-e35f-49ec009731ea" \ secret_id="ed0a642f-2acf-c2da-232f-1b21300d5f29"
Key Value--- -----token s.o5llFbKeMOpoNxi58MwNYk8p.0YFbAtoken_accessor FILPoDWPoqd5zeo62HAoWexN.0YFbAtoken_duration 1htoken_renewable truetoken_policies ["default" "tester"]identity_policies policies ["default" "tester"]token_meta_role_name webapp
Vault returns a client token with
tester policies attached.
- Store the generated token value in an environment variable named,
Important: Replace the APP_TOKEN value in the example with the one generated above.
$ export APP_TOKEN="s.ncEw5bAZJqvGJgl8pBDM0C5h"
Access the secrets at
secret/test/webappauthenticated with the
$ VAULT_TOKEN=$APP_TOKEN vault kv get secret/test/webapp ====== Metadata ======Key Value--- -----created_time 2021-06-17T03:06:34.063027186Zdeletion_time n/adestroyed falseversion 1 ===== Data =====Key Value--- -----api-key ABC0DEFG9876
To learn more about the Key/Value v2 secrets engine, read the Versioned Key/Value Secrets Engine tutorial.
If you followed the tutorials all the way through, you completed the common Vault operations workflow.
The differences between the HCP Vault and self-managed Vault are:
- HCP Vault runs Vault Enterprise
- The root namespace of HCP Vault is
You can follow any of the Vault tutorials on
values are different from what the tutorials may say, but you know how to set
them for your HCP Vault cluster. In addition, be sure to set
Next, continue onto the Vault Operations Tasks tutorial which demonstrates the cluster-level operations.
If you wish to delete the resources you created to clean up your Vault environment, go through the steps in this section.
Disable the AppRole auth method enabled at
$ vault auth disable approleSuccess! Disabled the auth method (if it existed) at: approle/
$ vault policy delete testerSuccess! Deleted policy: tester
Disable the key/value v2 secrets engine at
$ vault secrets disable secretSuccess! Disabled the secrets engine (if it existed) at: secret/
$ vault namespace delete -namespace=admin/education training WARNING! The following warnings were returned from Vault: * Namespace deletion has been queued. Progress will be reported in debug-level logs in Vault's server log.
$ vault namespace delete education WARNING! The following warnings were returned from Vault: * Namespace deletion has been queued. Progress will be reported in debug-level logs in Vault's server log.
Delete the stored token.
$ unset VAULT_TOKEN