Manage Authentication Methods

10min
HCP
Vault

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.

Note

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 against the admin namespace.

Personas

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 completed the Create Vault Policies tutorial so the tester policy exists.

Enable AppRole auth method

(Persona: admin)

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

In the Vault UI, make sure that current namespace is admin/.
Click the Access tab.
Click Enable new method.
Select AppRole and click Next.
Leave the path value unchanged and click Enable Method.
Without making any change, click < approle to view its current configuration.

If you did not set the VAULT_ADDR and VAULT_TOKEN environment variables, refer to the steps in the Create a Vault Cluster on HCP tutorial.

Set the VAULT_NAMESPACE environment variable to admin.
```
$ export VAULT_NAMESPACE=admin
```

Enable approle auth method.

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

If you did not set the VAULT_ADDR and VAULT_TOKEN environment variables, refer to the steps in the Create a Vault Cluster on HCP tutorial.

Enable approle auth method by mounting its endpoint at /sys/auth/approle.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: admin" \
    --request POST \
    --data '{"type": "approle"}' \
    $VAULT_ADDR/v1/sys/auth/approle

The above example passes the type (approle) in the request payload to the sys/auth/approle endpoint.

Create a role with policy attached

(Persona: admin)

When you enabled the AppRole auth method, it was mounted at the default /auth/approle path. In this example, you are going to create a role for the app persona with tester policy attached.

Create the 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.

Create the webapp role with the tester policy attached. The generated token's time-to-live (TTL) is set to 1 hour and can be renewed for up to 4 hours from the time of its creation. (NOTE: This example creates a role which operates in pull mode.)

$ vault write auth/approle/role/webapp token_policies="tester" \
    token_ttl=1h token_max_ttl=4h

Output:

Success! Data written to: auth/approle/role/webapp

Creates a role named webapp with a webapp policy attached. The token's time-to-live (TTL) is set to 1 hour and can be renewed for up to 4 hours from the time of its creation. (NOTE: This example creates a role which operates in pull mode.)

Create the API request payload.

$ tee payload-approle.json <<EOF
{
  "token_policies": "tester",
  "token_ttl": "1h",
  "token_max_ttl": "4h"
}
EOF

Create a new role named webapp.

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

There are a number of parameters that you can set on a role. If you want to limit the use of the generated secret ID, set secret_id_num_uses or secret_id_ttl parameter values. Similarly, you can specify token_num_uses and token_ttl. You may never want the app token to expire. In such a case, specify the period so that the token generated by this AppRole is a periodic token. To learn more about periodic tokens, refer to the Tokens tutorial.

Generate RoleID and SecretID

(Persona: admin)

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

To retrieve the RoleID, invoke the auth/approle/role/<ROLE_NAME>/role-id endpoint. To generate a new SecretID, invoke the auth/approle/role/<ROLE_NAME>/secret-id endpoint.

Click the Vault CLI shell icon (>_) to open a command shell.

Read the RoleID.

$ vault read auth/approle/role/webapp/role-id

Example output:

Key     Value
role_id b6ccdcca-183b-ce9c-6b98-b556b9a0edb9

Generate a new SecretID of the webapp role.
```
$ vault write -force auth/approle/role/webapp/secret-id
```
```
Key                Value
secret_id          735a47cc-7a98-77cc-0128-12b1e96a4157
secret_id_accessor 3ab305d1-1eab-df4b-4079-ef7135635c49
...snip...
```
The -force (or -f) flag forces the write operation to continue without any data values specified. Or you can set parameters such as cidr_list.
The acquired role-id and secret-id are the credentials that your trusted application uses to authenticate with Vault.

Now, you need to fetch the RoleID and SecretID of a role.

Retrieve the RoleID for the webapp role.

$ vault read auth/approle/role/webapp/role-id

Key     Value
---     -----
role_id 675a50e7-cfe0-be76-e35f-49ec009731ea

Generate a SecretID for the webapp role.

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

Key                 Value
---                 -----
secret_id           ed0a642f-2acf-c2da-232f-1b21300d5f29
secret_id_accessor  a240a31f-270a-4765-64bd-94ba1f65703c

The -force (or -f) flag forces the write operation to continue without any data values specified. Or you can set parameters such as cidr_list.

Read the RoleID for the webapp role.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: admin" \
    $VAULT_ADDR/v1/auth/approle/role/webapp/role-id | jq -r ".data"

Example output:

{
  "role_id": "5b5817f5-7db1-31ea-1943-1dbecf797ab3"
}

To generate a new SecretID for the webapp role.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: admin" \
    --request POST \
    $VAULT_ADDR/v1/auth/approle/role/webapp/secret-id | jq -r ".data"

Example output:

{
  "secret_id": "4e692046-914a-e2d4-0cc7-08de52401b07",
  "secret_id_accessor": "8003b5f6-b42a-bf27-429c-4b09f67544e4",
  "secret_id_ttl": 0
}

You can pass parameters in the request payload, or invoke the API with an empty payload.

Tip

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

(Persona: app)

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.

Tip

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/login endpoint by passing the RoleID and SecretID.

Note

Replace the role_id and secret_id values in the example with those generated in the Generate RoleID and SecretID section above.

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                   hvs.BMXSIJvlm6OjYeWiBmkLxnhgkPAkr3Lx8CbvU1WRnCGTwufIGicKImh2cyDYN0hhaWJIcE5yQUlRWGMxYzZFc05DcDUuWFA1T2oQjQI
token_accessor          FILPoDWPoqd5zeo62HAoWexN.0YFbA
token_duration          1h
token_renewable         true
token_policies          ["default" "tester"]
identity_policies       []
policies                ["default" "tester"]
token_meta_role_name    webapp

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

Store the generated token value in an environment variable named, APP_TOKEN.
Note
Replace the APP_TOKEN value in the example with the one generated above.
Example:
```
$ export APP_TOKEN="hvs.BMXSIJvlm6OjYeWiBmkLxnhgkPAkr3Lx8CbvU1WRnCGTwufIGicKImh2cyDYN0hhaWJIcE5yQUlRWGMxYzZFc05DcDUuWFA1T2oQjQI"
```

Access the secrets at secret/test/webapp authenticated with the APP_TOKEN.

$ VAULT_TOKEN=$APP_TOKEN vault kv get secret/test/webapp

====== Metadata ======
Key              Value
---              -----
created_time     2021-06-17T03:06:34.063027186Z
deletion_time    n/a
destroyed        false
version          1

===== Data =====
Key        Value
---        -----
api-key    ABC0DEFG9876

Use the auth/approle/login endpoint to authenticate by passing the RoleID and SecretID in the request payload.

Create an API request payload containing the RoleID and SecretID.
Note
Replace the role_id and secret_id values in the example with those generated in the Generate RoleID and SecretID section above.
Example:
```
$ tee payload_login.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 --request POST \
    --header "X-Vault-Namespace: admin" \
    --data @payload_login.json \
    $VAULT_ADDR/v1/auth/approle/login | jq -r ".auth"

Example output:

{
  "client_token": "s.5qC0xVI6bLDAcr2AelXQWvHt.0YFbA",
  "accessor": "TJiwkCcl4wmobQUd1Fc66grI.0YFbA",
  "policies": [
    "default",
    "tester"
  ],
  "token_policies": [
    "default",
    "tester"
  ],
  "metadata": {
    "role_name": "webapp"
  },
  "lease_duration": 3600,
  "renewable": true,
  "entity_id": "bd490f90-d0bf-2c42-03b0-5a9555f647d3",
  "token_type": "service",
  "orphan": true
}

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

Store the generated client_token value in an environment variable named, APP_TOKEN.
Note
Replace the APP_TOKEN value in the example with the one generated above.
Example:
```
$ export APP_TOKEN="s.d1D1l86gypL6qu1zJPdUjRtu"
```

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

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

Example output:

{
  "data": {
    "api-key": "ABC0DEFG9876"
  },
  "metadata": {
    "created_time": "2021-06-17T03:06:34.063027186Z",
    "deletion_time": "",
    "destroyed": false,
    "version": 1
  }
}

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

Next steps

To learn more about the AppRole auth method, refer to the AppRole Pull Authentication and AppRole with Terraform & Chef tutorials.

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 admin

You can follow any of the Vault tutorials on Learn. Your VAULT_ADDR and VAULT_TOKEN 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 VAULT_NAMESPACE.

Next, continue onto the Vault Operations Tasks tutorial which demonstrates the cluster-level operations.

Clean up

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 approle.

$ vault auth disable approle
Success! Disabled the auth method (if it existed) at: approle/

Delete the tester policy.

$ vault policy delete tester
Success! Deleted policy: tester

Disable the key/value v2 secrets engine at secret/.

$ vault secrets disable secret
Success! Disabled the secrets engine (if it existed) at: secret/

Delete the education/training namespace.

$ 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.

Delete the education namespace.

$ 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
```