Authenticate users in HCP Vault Dedicated

11min
|
HCP
Vault

Before a client can interact with Vault, the client must authenticate against an auth method to get a token. This token has policies attached to govern the behavior of the client.

In this tutorial, Oliver will enable and configure the AppRole auth method to allow workloads, the app persona, to authenticate with Vault.

Like secrets engines and policies, you enable auth methods in 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. The policies attached to the token dictate which namespaces the token can access.

Prerequisites

Completed the Create a Vault Cluster on HashiCorp Cloud Platform (HCP) tutorial.
Completed the Access your HCP Vault Dedicated cluster tutorial.

Enable AppRole auth method

(Persona: operations)

You have to enable the AppRole auth method before you can authenticate with it.

In the Vault UI, make sure that current namespace is admin/.
Click Access > Authentication methods.
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: operations)

When you enabled the AppRole auth method, you mounted it 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 the max TTL 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 provided vault write command.

$ 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. Set the generated token's time-to-live (TTL) to 1 hour, and max renewal window for up to 4 hours from the time of its creation. 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

Example output:

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

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: operations)

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.

Retrieve the RoleID and SecretID of the webapp 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
  }
}

Tip

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

Knowledge checks

A quiz to test your knowledge.

How do the RoleID and SecretID function within the AppRole auth method?
🔘 They serve as the namespace identifier and the policy name for the application.
🔘 They act similar to a username and password that an application uses to authenticate with Vault.
🔘 They function as the encryption key and decryption key for the Key/Value secrets engine.
🔘 They replace the need for a client token by directly granting access to secrets.
❌ They serve as the namespace identifier and the policy name for the application.
✅ They act similar to a username and password that an application uses to authenticate with Vault.
❌ They function as the encryption key and decryption key for the Key/Value secrets engine.
❌ They replace the need for a client token by directly granting access to secrets.
What does Vault return when a client successfully authenticates using the AppRole auth method?
🔘 A new SecretID
🔘 A root token
🔘 A client token with the role's policies attached
🔘 The requested secret data
❌ A new SecretID
❌ A root token
✅ A client token with the role's policies attached
❌ The requested secret data
When you authenticate using an auth method enabled in a specific namespace, what determines which namespaces the resulting token can access?
The policies attached to the generated token dictate which namespaces the token can access, which can include child namespaces if the policies grant those permissions.

Summary

In this tutorial you enabled the AppRole auth method, and retrieved the role ID and secret ID. You can learn more in the AppRole pull authentication tutorial.

In this series of tutorials, you completed the most common Vault operations workflow.

Common Operational Workflow

The differences between the HCP Vault Dedicated and self-managed Vault are:

Vault Dedicated runs Vault Enterprise
The root namespace of Vault Dedicated is admin

You can follow any of the Vault tutorials with HCP Vault Dedicated. Set your VAULT_ADDR, VAULT_NAMESPACE, and VAULT_TOKEN variables with the appropriate values.

If you are new to Vault, follow the Vault foundations series to learn the core concepts and features of Vault.

Next steps

In the next tutorial, you will learn how to configure and manage more advanced features for your HCP Vault cluster, including:

Enable disaster recovery replication
Lock and unlock the cluster
Scale the cluster between different tiers

Manage access to secrets

Manage clusters