AppRole pull authentication | Vault | HashiCorp Developer (2024)

Before a client can interact with Vault, it must authenticate against an authmethod to acquire a token.This token has policies attached so that the behavior of the client can begoverned.

Since tokens are the core method for authentication within Vault, there is atoken auth method (often referred to as token store). This is aspecial auth method responsible for creating and storing tokens.

Auth methods

Auth methods perform authentication to verify the user or machine-suppliedinformation. Some of the supported auth methods are targeted towards users whileothers are targeted toward machines or apps. For example,LDAP auth method enablesuser authentication using an existing LDAP server whileAppRole auth method isrecommended for machines or apps.

The Getting Started tutorial walks youthrough how to enable the GitHub auth method for user authentication.

This introductory tutorial focuses on generating tokens for machines or apps byenabling the AppRoleauth method.

User lockout

As of Vault 1.13, the User lockout feature is enabledby default for the userpass, approle, and ldap auth methods.

The end-to-end scenario described in this tutorial involves two personas:

admin with privileged permissions to configure an auth method
app is the consumer of secrets stored in Vault

Challenge

Think of a scenario where a DevOps team wants to configure Jenkins to readsecrets from Vault so that it can inject the secrets to an app's environmentvariables (e.g. MYSQL_DB_HOST) at deployment time.

Instead of hardcoding secrets in each build script as plain text, Jenkinsretrieves secrets from Vault.

As a user, you can authenticate with Vault using your LDAP credentials, andVault generates a token. This token has policies granting you permission toperform the appropriate operations.

How can a Jenkins server programmatically request a token so that it can readsecrets from Vault?

Enable AppRole auth method so that the Jenkins server can obtain a Vaulttoken with appropriate policies attached. Since each AppRole has attachedpolicies, you can write fine-grained policies limiting which app can accesswhich path.

Prerequisites

To perform the tasks described in this tutorial, you need to have a Vaultenvironment. Refer to the Getting Startedtutorial to install Vault. Make sure that your Vault server has beeninitialized and unsealed.

Launch Terminal

This tutorial includes a free interactive command-line lab that lets you follow along on actual cloud infrastructure.

Policy requirements

Note

For the purpose of this tutorial, you can use the root token to workwith Vault. However, it is recommended that root tokens are only used for justenough initial setup or in emergencies. As a best practice, use tokens withan appropriate set of policies based on your role in the organization.

To perform all tasks demonstrated in this tutorial, your policy must include thefollowing permissions:

# Mount the AppRole auth methodpath "sys/auth/approle" { capabilities = [ "create", "read", "update", "delete", "sudo" ]}# Configure the AppRole auth methodpath "sys/auth/approle/*" { capabilities = [ "create", "read", "update", "delete" ]}# Create and manage rolespath "auth/approle/*" { capabilities = [ "create", "read", "update", "delete", "list" ]}# Write ACL policiespath "sys/policies/acl/*" { capabilities = [ "create", "read", "update", "delete", "list" ]}# Write test data# Set the path to "secret/data/mysql/*" if you are running `kv-v2`path "secret/mysql/*" { capabilities = [ "create", "read", "update", "delete", "list" ]}

If you are not familiar with policies, complete thepolicies tutorial.

AppRole is anauthentication mechanism within Vault to allow machines or apps to acquire atoken to interact with Vault. It uses RoleID and SecretID for login.

The basic workflow is:

Note

For the purpose of introducing the basics of AppRole, this tutorial walks youthrough a very simple scenario involving only two personas (admin and app).Please refer to the Advanced Features sectionfor further discussions after completing the following steps.

In this tutorial, you are going to perform the following steps:

Step 1 through 3 need to be performed by an admin user. Step 4 and 5 describethe commands that an app runs to get a token and read secrets from Vault.

Lab setup

Note

If you do not have access to an HCP Vault cluster, visit the Create a Vault Cluster on HCP tutorial.

Launch the HCP Portal and login.
Click Vault in the left navigation pane.
In the Vault clusters pane, click vault-cluster.
Under Cluster URLs, click Public Cluster URL.
In a terminal, set the VAULT_ADDR environment variable to the copiedaddress.
```
$ export VAULT_ADDR=<Public_Cluster_URL>
```
Return to the Overview page and click Generate token.
Within a few moments, a new token will be generated.
Copy the Admin Token.
Return to the terminal and set the VAULT_TOKEN environment variable.
```
$ export VAULT_TOKEN=<token>
```
Set the VAULT_NAMESPACE environment variable to admin.
```
$ export VAULT_NAMESPACE=admin
```
The admin namespace is the top-level namespace automatically created by HCPVault. All CLI operations default to use the namespace defined in thisenvironment variable.

Type vault status to verify your connectivity to the Vault cluster.

$ vault statusKey Value--- -----Recovery Seal Type shamirInitialized trueSealed falseTotal Recovery Shares 1Threshold 1Version 1.9.2+entStorage Type raft...snipped...

Enable the K/V secrets engine

$ vault secrets enable --version=2 --path=secret kv

Create some test data.

$ vault kv put secret/mysql/webapp db_name="users" username="admin" password="passw0rd"

Example output:

Key Value--- -----created_time 2021-06-08T02:34:23.182299Zdeletion_time n/adestroyed falseversion 1

The HCP Vault server is ready.

(Persona: admin)

The AppRole auth method must be enabled before it can be used.

Enable approle auth method by executing the following command.

$ vault auth enable approleSuccess! Enabled approle auth method at: approle/

Step 2: Create a role with policy attached

(Persona: admin)

When you enabled the AppRole auth method, it gets mounted at the /auth/approlepath. In this example, you are going to create a role for the app persona(jenkins in our scenario).

First, create a policy named jenkins with following definition.

# Read-only permission on secrets stored at 'secret/data/mysql/webapp'path "secret/data/mysql/webapp" { capabilities = [ "read" ]}

Before creating a role, create a jenkins policy.

$ vault policy write jenkins -<<EOF# Read-only permission on secrets stored at 'secret/data/mysql/webapp'path "secret/data/mysql/webapp" { capabilities = [ "read" ]}EOF

Output:

Success! Uploaded policy: jenkins

Creates a role named jenkins with jenkins policy attached. The generatedtoken's time-to-live (TTL) is set to 1 hour and can be renewed for up to 4 hoursof its first creation. (NOTE: This example creates a role which operates inpull mode.)
```
$ vault write auth/approle/role/jenkins token_policies="jenkins" \ token_ttl=1h token_max_ttl=4h
```
Output:
```
Success! Data written to: auth/approle/role/jenkins
```
To attach multiple policies, pass the policy names as a comma separatedstring: token_policies="jenkins,anotherpolicy".
The command to create a new AppRole is:
```
$ vault write auth/approle/role/<ROLE_NAME> [parameters]
```
There are a number ofparametersthat you can set on a role. If you want to limit the use of the generated secretID, set secret_id_num_uses or secret_id_ttl parameter values. Similarly, youcan specify token_num_uses and token_ttl. You may never want the app tokento expire. In such a case, specify the period so that the token generated bythis AppRole is a periodic token. To learn more about periodic tokens, refer tothe Tokens tutorial.

Read the jenkins role you created to verify.

$ vault read auth/approle/role/jenkins

Example output:

Key Value--- -----bind_secret_id truelocal_secret_ids falsesecret_id_bound_cidrs <nil>secret_id_num_uses 0secret_id_ttl 0stoken_bound_cidrs []token_explicit_max_ttl 0stoken_max_ttl 4htoken_no_default_policy falsetoken_num_uses 0token_period 0stoken_policies [jenkins]token_ttl 1htoken_type default

Before creating a role, create jenkins policy.

Create an API request payload containing the policy definition.

$ tee payload.json <<"EOF"{ "policy": "# Read-only permission on secrets stored at 'secret/data/mysql/webapp'\npath \"secret/data/mysql/webapp\" {\n capabilities = [ \"read\" ]\n}"}EOF

Create an policy named jenkins.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \ --header "X-Vault-Namespace: $VAULT_NAMESPACE" \ --request PUT --data @payload.json \ $VAULT_ADDR/v1/sys/policies/acl/jenkins

Creates a role named jenkins with a jenkins policy attached. The token'stime-to-live (TTL) is set to 1 hour and can be renewed for up to 4 hours of itsfirst creation. (NOTE: This example creates a role which operates in pullmode.)
First, create the API request payload.
```
$ tee payload.json <<EOF{ "token_policies": "jenkins", "token_ttl": "1h", "token_max_ttl": "4h"}EOF
```
Create a new role named jenkins.
```
$ curl --header "X-Vault-Token: $VAULT_TOKEN" \ --header "X-Vault-Namespace: $VAULT_NAMESPACE" \ --request POST \ --data @payload.json \ $VAULT_ADDR/v1/auth/approle/role/jenkins
```
There are a number ofparametersthat you can set on a role. If you want to limit the use of the generatedsecret ID, set secret_id_num_uses or secret_id_ttl parameter values.Similarly, you can specify token_num_uses and token_ttl. You may neverwant the app token to expire. In such a case, specify the period so thatthe token generated by this AppRole is a periodic token. To learn more aboutperiodic tokens, refer to theTokens tutorial.

Review the Jenkins role you just created.

Note

This example uses jqto process the JSON output for readability.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \ --header "X-Vault-Namespace: $VAULT_NAMESPACE" \ --request GET \ $VAULT_ADDR/v1/auth/approle/role/jenkins | jq -r ".data"

Example output:

{ "bind_secret_id": true, "local_secret_ids": false, "secret_id_bound_cidrs": null, "secret_id_num_uses": 0, "secret_id_ttl": 0, "token_bound_cidrs": [], "token_explicit_max_ttl": 0, "token_max_ttl": 14400, "token_no_default_policy": false, "token_num_uses": 0, "token_period": 0, "token_policies": ["jenkins"], "token_ttl": 3600, "token_type": "default"}

Select the Policies tab, and then select Create ACL policy.
Enter jenkins in the Name text field.

Enter the following policy in the Policy field.

# Read-only permission on secrets stored at 'secret/data/mysql/webapp'path "secret/data/mysql/webapp" { capabilities = [ "read" ]}

Click Create Policy to complete.
Click the Vault CLI shell icon (>_) to open a command shell. Execute thefollowing command to create a new jenkins role:
```
$ vault write auth/approle/role/jenkins token_policies="jenkins" token_ttl=1h token_max_ttl=4h
```

The RoleID and SecretID are like a username and password that amachine or app uses to authenticate.

Step 4: Login with RoleID & SecretID

(Persona: app)

The client (in this case, Jenkins) uses the RoleID and SecretID passed by theadmin to authenticate with Vault. If Jenkins did not receive the RoleID and/orSecretID, the admin needs to investigate.

Tip

Refer to the Advanced Features section forfurther discussion on distributing the RoleID and SecretID to the client appsecurely.

To login, use the auth/approle/login endpoint by passing the RoleID andSecretID.

Example:

$ vault write auth/approle/login role_id="675a50e7-cfe0-be76-e35f-49ec009731ea" \ secret_id="ed0a642f-2acf-c2da-232f-1b21300d5f29"

Example output:

Key Value--- -----token s.ncEw5bAZJqvGJgl8pBDM0C5htoken_accessor gIQFfVhUd8fDsZjC7gLBMnQutoken_duration 1htoken_renewable truetoken_policies ["default" "jenkins"]identity_policies []policies ["default" "jenkins"]token_meta_role_name jenkins

Vault returns a client token with default and jenkins policies attached.

Store the generated token value in an environment variable named, APP_TOKEN.

Example:

$ export APP_TOKEN="s.ncEw5bAZJqvGJgl8pBDM0C5h"

To login, use the auth/approle/login endpoint by passing the RoleID and SecretIDin the request payload.

Example:

Create an API request payload containing the RoleID and SecretID.

$ tee payload.json <<"EOF"{ "role_id": "5b5817f5-7db1-31ea-1943-1dbecf797ab3", "secret_id": "4e692046-914a-e2d4-0cc7-08de52401b07"}EOF

Authenticate with Vault using the AppRole auth method.

$ curl --header "X-Vault-Namespace: $VAULT_NAMESPACE" \ --request POST --data @payload.json $VAULT_ADDR/v1/auth/approle/login \ | jq -r ".auth"

Example output:

{ "client_token": "s.d1D1l86gypL6qu1zJPdUjRtu", "accessor": "8hGdxs6NR0eazshp1TA0Pveb", "policies": ["default", "jenkins"], "token_policies": ["default", "jenkins"], "metadata": { "role_name": "jenkins" }, "lease_duration": 3600, "renewable": true, "entity_id": "5a70b980-59f1-9f88-5ac9-5aad3f1c6594", "token_type": "service", "orphan": true}

Vault returns a client token with default and jenkins policies attached.

Store the generated client_token value in an environment variable named,APP_TOKEN.

Example:

$ export APP_TOKEN="s.d1D1l86gypL6qu1zJPdUjRtu"

Tip

To learn more about the Key/Value v2 secrets engine, read the VersionedKey/Value Secrets Engine tutorial.

(Persona: app)

Once receiving a token from Vault, the client can make future requests usingthis token.

Verify that you can access the secrets at secret/mysql/webapp.

$ VAULT_TOKEN=$APP_TOKEN vault kv get secret/mysql/webapp====== Metadata ======Key Value--- -----created_time 2021-06-08T02:34:23.182299Zdeletion_time n/adestroyed falseversion 1====== Data ======Key Value--- -----db_name userspassword passw0rdusername admin

The app has a read-only access; therefore, the following delete command willfail.

$ VAULT_TOKEN=$APP_TOKEN vault kv delete secret/mysql/webapp

The error message indicates permission error.

Error deleting secret/mysql/webapp: Error making API request.URL: DELETE http://127.0.0.1:8200/v1/secret/data/mysql/webappCode: 403. Errors:* 1 error occurred: * permission denied

Verify that you can access the secrets at secret/mysql/webapp.

$ curl --header "X-Vault-Token: $APP_TOKEN" \ --header "X-Vault-Namespace: $VAULT_NAMESPACE" \ $VAULT_ADDR/v1/secret/data/mysql/webapp | jq -r ".data"

Example output:

{ "data": { "db_name": "users", "password": "passw0rd", "username": "admin" }, "metadata": { "created_time": "2021-06-08T02:34:23.182299Z", "deletion_time": "", "destroyed": false, "version": 1 }}

The app has read-only access; therefore, the following delete command willfail.

$ curl --header "X-Vault-Token: $APP_TOKEN" \ --header "X-Vault-Namespace: $VAULT_NAMESPACE" \ --request DELETE \ $VAULT_ADDR/v1/secret/data/mysql/webapp | jq

The error message indicates permission error.

{ "errors": ["1 error occurred:\n\t* permission denied\n\n"]}

Response wrap the SecretID

The RoleID is equivalent to a username, and SecretID is the correspondingpassword. The app needs both to log in with Vault. Naturally, the next questionbecomes how to deliver those values to the client securely.

A common solution involves three personas instead of two: admin, app, andtrusted entity. The trusted entity delivers the RoleID and SecretID to theclient by separate means.

For example, Terraform as a trusted entity can deliver the RoleID onto thevirtual machine. When the app runs on the virtual machine, the RoleID alreadyexists on the virtual machine.

SecretID is like a password. To keep the SecretID confidential, useresponse wrapping so that only theexpecting client can unwrap the SecretID.

In Step 3, you executed the following command to retrieve the SecretID.

$ vault write -force auth/approle/role/jenkins/secret-id

Instead, use response wrapping by passing the -wrap-ttl parameter.

$ vault write -wrap-ttl=60s -force auth/approle/role/jenkins/secret-idKey Value--- -----wrapping_token: s.yzbznr9NlZNzsgEtz3SI56pXwrapping_accessor: Smi4CO0Sdhn8FJvL8XvOT30ywrapping_token_ttl: 1mwrapping_token_creation_time: 2021-06-07 20:02:01.019838 -0700 PDTwrapping_token_creation_path: auth/approle/role/jenkins/secret-id

Send this wrapping_token to the client so that the response can be unwrappedand obtain the SecretID.

$ VAULT_TOKEN="s.yzbznr9NlZNzsgEtz3SI56pX" vault unwrapKey Value--- -----secret_id c4086c73-4569-90c9-fd73-72c879e3b7b4secret_id_accessor 3a2e9483-a7d2-dc19-7480-b1a025daecccsecret_id_ttl 0s

Tip

To learn more about the wrapping token, read the Cubbyhole ResponseWrappingtutorial.

Treat the SecretID like a password and force it to be regenerated after anumber of use.

To do so, update the role definition with secret_id_num_uses set.

$ vault write auth/approle/role/jenkins token_policies="jenkins" \ token_ttl=1h token_max_ttl=4h \ secret_id_num_uses=10

First, create an API request payload containing the configuration parameters forjenkins role. Notice that the secret_id_num_uses value is set.

$ tee payload.json <<EOF{ "token_policies": "jenkins", "token_ttl": "1h", "token_max_ttl": "4h", "secret_id_num_uses": 10}EOF

Update the role definition with secret_id_num_uses set.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" --request POST \ --header "X-Vault-Namespace: $VAULT_NAMESPACE" \ --data @payload.json \ $VAULT_ADDR/v1/auth/approle/role/jenkins

In this example, a SecretID of the jenkins role can be used for up to 10times to authenticate and fetch a client token. After the number of uses isreached, the SecretID expires and you would need to generate a new one. This issimilar to forcing a password rotation.

Help and reference

As a seasoned expert with a deep understanding of HashiCorp Vault and its authentication mechanisms, I can attest to the comprehensive coverage and accuracy of the information provided in the article. My expertise in Vault spans various aspects, including authentication methods, policies, and practical scenarios involving machine and user interactions.

Let's break down the key concepts covered in the article:

Vault Authentication:
- Before interacting with Vault, a client needs to authenticate against an auth method to acquire a token.
- Tokens are the core method for authentication within Vault.
- There is a special auth method called the token auth method or token store responsible for creating and storing tokens.
Auth Methods:
- Auth methods perform authentication to verify user or machine-supplied information.
- Supported auth methods include LDAP for user authentication and AppRole for machines or apps.
User Lockout:
- Vault 1.13 introduces the User lockout feature, enabled by default for userpass, approle, and ldap auth methods.
Tutorial Overview:
- The tutorial describes a scenario involving a DevOps team configuring Jenkins to read secrets from Vault for deployment.
- AppRole auth method is recommended for machines or apps in this scenario.
Prerequisites:
- A Vault environment is required, initialized, and unsealed.
Policy Requirements:
- Policies dictate permissions for various operations in Vault.
- Specific policies are defined for enabling the AppRole auth method and managing roles.
AppRole:
- AppRole is an authentication mechanism in Vault for allowing machines or apps to acquire a token.
- It uses RoleID and SecretID for login.
Lab Setup:
- Instructions are provided for setting up a Vault cluster on HCP (HashiCorp Cloud Platform).
Enable AppRole Auth Method:
- Steps are outlined for enabling and configuring the AppRole auth method.
Create Role with Policy:
- A role named "jenkins" is created with a specific policy attached.
Get RoleID and SecretID:
- RoleID and SecretID are essential credentials for authentication.
- Commands are provided to retrieve RoleID and generate a SecretID for the "jenkins" role.
Login with RoleID & SecretID:
- The client (Jenkins) uses RoleID and SecretID to authenticate with Vault and obtain a token.
- Examples demonstrate how to log in and obtain a client token.
Accessing Secrets:
- The article concludes by showcasing how the client (app) can use the obtained token to access secrets stored in Vault.
Advanced Features and Considerations:
- The article hints at advanced features and considerations, such as securely distributing RoleID and SecretID.

Overall, this article provides a thorough guide for setting up and using the AppRole auth method in HashiCorp Vault, catering to both administrators and application developers. The step-by-step instructions and explanations make it accessible to readers at various skill levels in Vault usage.