Simplify management of Vault policies with ACL policy templating

19min
|
Vault
Video
Interactive

Vault operates on a secure by default standard. An empty policy grants no permissions to Vault resources. You must create policies to define the behavior of clients and set up role-based access control (RBAC) by specifying capabilities (authorization) in Vault.

Since everything in Vault is path based, policy authors must be aware of existing paths as well as new paths that may be created.

If you are not familiar with Vault ACL policies, follow the access controls with Vault policies tutorial.

Challenge

You can specify non-static paths in ACL policies by using globs (*) at the end of paths, or the plus-sign (+) for a single directory wildcard match.

path "transit/keys/*" {
  capabilities = [ "read" ]
}

path "secret/+/apikey" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

path "transit/keys/*" {
  capabilities = [ "read" ]
}

path "secret/+/apikey" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

Using wildcards helps simplify policy management, but makes delegation tasks challenging. For example, allowing a user to change their own password by invoking the auth/userpass/users/<user_name>/password endpoint requires either a policy for every user or requires the use of Sentinel, which is a part of Vault Enterprise.

Solution

ACL templating allows you to use a subset of user information within ACL policy paths.

In this tutorial, you will write a policy with templated paths to allow access to Vault.

Prerequisites

Vault installed.
jq for consuming Vault JSON formatted output and capturing specific fields.

Launch Terminal

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

Scenario Introduction

Assume you have the following policy requirements:

Each user can perform all operations on their allocated key/value secret path (user-kv/data/<user_name>).
The education group has a dedicated key/value secret store for each region where all operations can be performed by the group members (group-kv/data/education/<region>).
The group members can update the group information such as metadata about the group (identity/group/id/<group_id>).

Set up the lab

Open a terminal and start a Vault dev server with the literal string root as the root token value, and enable TLS.
```
$ vault server -dev -dev-root-token-id root -dev-tls
```
```
$ vault server -dev -dev-root-token-id root -dev-tls
```
The dev server listens on the loopback interface at 127.0.0.1 on TCP port 8200 with TLS enabled. At runtime, the dev server also automatically unseals, and prints the unseal key and initial root token values to the standard output.
Root tokens
The dev mode server starts with an initial root token value set. Root token use should be extremely guarded in production environments because it provides full access to the Vault server. You can supply the root token value to start Vault in dev mode for convenience and to keep the steps here focused on the learning goals of this tutorial.
In a new terminal, export the VAULT_ADDR and VAULT_CACERT environment variables using the commands suggested in your Vault dev server output.
Copy each command (without the $) from the server output, and paste it into the new terminal session.
Example:
```
export VAULT_ADDR='https://127.0.0.1:8200'
```
```
export VAULT_ADDR='https://127.0.0.1:8200'
```
Example:
```
export VAULT_CACERT='/var/folders/qr/zgztx0sj6n1dxy86sl36ntnw0000gn/T/vault-tls3037226588/vault-ca.pem'
```
```
export VAULT_CACERT='/var/folders/qr/zgztx0sj6n1dxy86sl36ntnw0000gn/T/vault-tls3037226588/vault-ca.pem'
```
Remember to use your dev server's values, not the examples shown here.
Export an environment variable for the vault CLI to authenticate with the Vault server.
```
$ export VAULT_TOKEN=root
```
```
$ export VAULT_TOKEN=root
```
The Vault server is ready.

Note

If you do not have access to an HCP Vault Dedicated 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 copied address.

$ export VAULT_ADDR=<Public_Cluster_URL>

$ export VAULT_ADDR=<Public_Cluster_URL>

Return to the Overview page and click Generate token.
Copy the Admin Token.
Return to the terminal and set the VAULT_TOKEN environment variable.
```
$ export VAULT_TOKEN=<token>
```
```
$ export VAULT_TOKEN=<token>
```
Set the VAULT_NAMESPACE environment variable to admin.
```
$ export VAULT_NAMESPACE=admin
```
```
$ export VAULT_NAMESPACE=admin
```
The admin namespace is the top-level namespace automatically created by HCP Vault. All CLI operations default to use the namespace defined in this environment variable.

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

$ vault status

Key                      Value
---                      -----
Recovery Seal Type       shamir
Initialized              true
Sealed                   false
Total Recovery Shares    1
Threshold                1
Version                  1.9.2+ent
Storage Type             raft
...snipped...

$ vault status

Key                      Value
---                      -----
Recovery Seal Type       shamir
Initialized              true
Sealed                   false
Total Recovery Shares    1
Threshold                1
Version                  1.9.2+ent
Storage Type             raft
...snipped...

The Vault Dedicated server is ready.

Policy requirements

Since this tutorial demonstrates the creation of an admin policy, log in with the root token.

Create templated ACL policies

Policy authors can pass in a policy path containing double curly braces as templating delimiters: {{<parameter>}}.

Identity groups are not directly attached to a token and you can associate an entity with several groups. To reference a group, you must specify the group ID or group name (for example, identity.groups.ids.59f001d5-dd49-6d63-51e4-357c1e7a4d44.name).

Available Templating Parameters

Name	Description
`identity.entity.id`	The entity's ID
`identity.entity.name`	The entity's name
`identity.entity.metadata.<metadata key>`	Metadata associated with the entity for the given key
`identity.entity.aliases.<mount accessor>.id`	Entity alias ID for the given mount
`identity.entity.aliases.<mount accessor>.name`	Entity alias name for the given mount
`identity.entity.aliases.<mount accessor>.metadata.<metadata key>`	Metadata associated with the alias for the given mount and metadata key
`identity.entity.aliases.<mount accessor>.custom_metadata.<custom metadata key>`	Custom metadata associated with the entity alias
`identity.groups.ids.<group id>.name`	The group name for the given group ID
`identity.groups.names.<group name>.id`	The group ID for the given group name
`identity.groups.ids.<group id>.metadata.<metadata key>`	Metadata associated with the group for the given key
`identity.groups.names.<group name>.metadata.<metadata key>`	Metadata associated with the group for the given key

Example policy:

This policy allows users to change their own password given that the username and password are defined in the userpass auth method. The mount accessor value (auth_userpass_6671d643 in this example) can be read from the sys/auth endpoint.

path "auth/userpass/users/{{identity.entity.aliases.auth_userpass_6671d643.name}}" {
  capabilities = [ "update" ]
  allowed_parameters = {
    "password" = []
  }
}

path "auth/userpass/users/{{identity.entity.aliases.auth_userpass_6671d643.name}}" {
  capabilities = [ "update" ]
  allowed_parameters = {
    "password" = []
  }
}

Write user template policy file (user-tmpl.hcl) using the entity name.

$ tee user-tmpl.hcl <<EOF
# Grant permissions on user specific path
path "user-kv/data/{{identity.entity.name}}/*" {
    capabilities = [ "create", "update", "read", "delete", "list" ]
}

# For Web UI usage
path "user-kv/metadata" {
  capabilities = ["list"]
}
EOF

$ tee user-tmpl.hcl <<EOF
# Grant permissions on user specific path
path "user-kv/data/{{identity.entity.name}}/*" {
    capabilities = [ "create", "update", "read", "delete", "list" ]
}

# For Web UI usage
path "user-kv/metadata" {
  capabilities = ["list"]
}
EOF

Write group template policy file (group-tmpl.hcl) using the group name.

$ tee group-tmpl.hcl <<EOF
# Grant permissions on the group specific path
# The region is specified in the group metadata
path "group-kv/data/education/{{identity.groups.names.education.metadata.region}}/*" {
    capabilities = [ "create", "update", "read", "delete", "list" ]
}

# Group member can update the group information
path "identity/group/id/{{identity.groups.names.education.id}}" {
  capabilities = [ "update", "read" ]
}

# For Web UI usage
path "group-kv/metadata" {
  capabilities = ["list"]
}

path "identity/group/id" {
  capabilities = [ "list" ]
}
EOF

$ tee group-tmpl.hcl <<EOF
# Grant permissions on the group specific path
# The region is specified in the group metadata
path "group-kv/data/education/{{identity.groups.names.education.metadata.region}}/*" {
    capabilities = [ "create", "update", "read", "delete", "list" ]
}

# Group member can update the group information
path "identity/group/id/{{identity.groups.names.education.id}}" {
  capabilities = [ "update", "read" ]
}

# For Web UI usage
path "group-kv/metadata" {
  capabilities = ["list"]
}

path "identity/group/id" {
  capabilities = [ "list" ]
}
EOF

A good practice is to manage your Vault policies as code in a version control system such as Git.

Create a new policy in Vault named user-tmpl using the user-tmpl.hcl file.

$ vault policy write user-tmpl user-tmpl.hcl

$ vault policy write user-tmpl user-tmpl.hcl

Create a new policy in Vault named group-tmpl using the group-tmpl.hcl file.

$ vault policy write group-tmpl group-tmpl.hcl

$ vault policy write group-tmpl group-tmpl.hcl

To create a policy, use the /sys/policies/acl endpoint:

$ curl --header "X-Vault-Token: <TOKEN>" \
       --request PUT \
       --data <PAYLOAD> \
       <VAULT_ADDRESS>/v1/sys/policies/acl/<POLICY_NAME>

$ curl --header "X-Vault-Token: <TOKEN>" \
       --request PUT \
       --data <PAYLOAD> \
       <VAULT_ADDRESS>/v1/sys/policies/acl/<POLICY_NAME>

Where <TOKEN> is your Vault token, and <PAYLOAD> includes the policy name and stringified policy.

Create an API request payload containing the stringified policy for user-tmpl.

$ tee payload_user.json <<EOF
{
  "policy": "# Grant permissions on user specific path\npath \"user-kv/data/{{identity.entity.name}}/*\" {\n    capabilities = [ \"create\", \"update\", \"read\", \"delete\", \"list\" ]\n}\n\n# For Web UI usage\npath \"user-kv/\" {\n  capabilities = [\"list\"]\n}"
}
EOF

$ tee payload_user.json <<EOF
{
  "policy": "# Grant permissions on user specific path\npath \"user-kv/data/{{identity.entity.name}}/*\" {\n    capabilities = [ \"create\", \"update\", \"read\", \"delete\", \"list\" ]\n}\n\n# For Web UI usage\npath \"user-kv/\" {\n  capabilities = [\"list\"]\n}"
}
EOF

Create user-tmpl policy.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --request PUT \
       --data @payload_user.json \
       $VAULT_ADDR/v1/sys/policies/acl/user-tmpl

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --request PUT \
       --data @payload_user.json \
       $VAULT_ADDR/v1/sys/policies/acl/user-tmpl

Create an API request payload containing the stringified policy for group-tmpl.

$ tee payload_group.json <<EOF
{
   "policy": "# Grant permissions on the group specific path\npath \"group-kv/data/education/{{identity.groups.names.education.metadata.region}}/*\" {\n    capabilities = [ \"create\", \"update\", \"read\", \"delete\", \"list\" ]\n}\n\n# Group member can update the group information\npath \"identity/group/id/{{identity.groups.names.education.id}}\" {\n  capabilities = [ \"update\", \"read\" ]\n}\n\n# For Web UI usage\npath \"group-kv/\" {\n  capabilities = [\"list\"]\n}\n\npath \"identity/group/id\" {\n  capabilities = [ \"list\" ]\n}"
}
EOF

$ tee payload_group.json <<EOF
{
   "policy": "# Grant permissions on the group specific path\npath \"group-kv/data/education/{{identity.groups.names.education.metadata.region}}/*\" {\n    capabilities = [ \"create\", \"update\", \"read\", \"delete\", \"list\" ]\n}\n\n# Group member can update the group information\npath \"identity/group/id/{{identity.groups.names.education.id}}\" {\n  capabilities = [ \"update\", \"read\" ]\n}\n\n# For Web UI usage\npath \"group-kv/\" {\n  capabilities = [\"list\"]\n}\n\npath \"identity/group/id\" {\n  capabilities = [ \"list\" ]\n}"
}
EOF

Create group-tmpl policy.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --request PUT \
       --data @payload_group.json \
       $VAULT_ADDR/v1/sys/policies/acl/group-tmpl

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --request PUT \
       --data @payload_group.json \
       $VAULT_ADDR/v1/sys/policies/acl/group-tmpl

Create an API request payload containing the stringified policy for user-tmpl.

$ tee payload_user.json <<EOF
{
  "policy": "# Grant permissions on user specific path\npath \"user-kv/data/{{identity.entity.name}}/*\" {\n    capabilities = [ \"create\", \"update\", \"read\", \"delete\", \"list\" ]\n}\n\n# For Web UI usage\npath \"user-kv/\" {\n  capabilities = [\"list\"]\n}"
}
EOF

$ tee payload_user.json <<EOF
{
  "policy": "# Grant permissions on user specific path\npath \"user-kv/data/{{identity.entity.name}}/*\" {\n    capabilities = [ \"create\", \"update\", \"read\", \"delete\", \"list\" ]\n}\n\n# For Web UI usage\npath \"user-kv/\" {\n  capabilities = [\"list\"]\n}"
}
EOF

Create user-tmpl policy.

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

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

Create an API request payload containing the stringified policy for group-tmpl.

$ tee payload_group.json <<EOF
{
   "policy": "# Grant permissions on the group specific path\npath \"group-kv/data/education/{{identity.groups.names.education.metadata.region}}/*\" {\n    capabilities = [ \"create\", \"update\", \"read\", \"delete\", \"list\" ]\n}\n\n# Group member can update the group information\npath \"identity/group/id/{{identity.groups.names.education.id}}\" {\n  capabilities = [ \"update\", \"read\" ]\n}\n\n# For Web UI usage\npath \"group-kv/\" {\n  capabilities = [\"list\"]\n}\n\npath \"identity/group/id\" {\n  capabilities = [ \"list\" ]\n}"
}
EOF

$ tee payload_group.json <<EOF
{
   "policy": "# Grant permissions on the group specific path\npath \"group-kv/data/education/{{identity.groups.names.education.metadata.region}}/*\" {\n    capabilities = [ \"create\", \"update\", \"read\", \"delete\", \"list\" ]\n}\n\n# Group member can update the group information\npath \"identity/group/id/{{identity.groups.names.education.id}}\" {\n  capabilities = [ \"update\", \"read\" ]\n}\n\n# For Web UI usage\npath \"group-kv/\" {\n  capabilities = [\"list\"]\n}\n\npath \"identity/group/id\" {\n  capabilities = [ \"list\" ]\n}"
}
EOF

Create group-tmpl policy.

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

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

Write user template policy file (user-tmpl.hcl) using the entity name.

$ tee user-tmpl.hcl <<EOF
# Grant permissions on user specific path
path "user-kv/data/{{identity.entity.name}}/*" {
    capabilities = [ "create", "update", "read", "delete", "list" ]
}

# For Web UI usage
path "user-kv/metadata" {
  capabilities = ["list"]
}
EOF

$ tee user-tmpl.hcl <<EOF
# Grant permissions on user specific path
path "user-kv/data/{{identity.entity.name}}/*" {
    capabilities = [ "create", "update", "read", "delete", "list" ]
}

# For Web UI usage
path "user-kv/metadata" {
  capabilities = ["list"]
}
EOF

Write group template policy file (group-tmpl.hcl) using the group name.

$ tee group-tmpl.hcl <<EOF
# Grant permissions on the group specific path
# The region is specified in the group metadata
path "group-kv/data/education/{{identity.groups.names.education.metadata.region}}/*" {
    capabilities = [ "create", "update", "read", "delete", "list" ]
}

# Group member can update the group information
path "identity/group/id/{{identity.groups.names.education.id}}" {
  capabilities = [ "update", "read" ]
}

# For Web UI usage
path "group-kv/metadata" {
  capabilities = ["list"]
}

path "identity/group/id" {
  capabilities = [ "list" ]
}
EOF

$ tee group-tmpl.hcl <<EOF
# Grant permissions on the group specific path
# The region is specified in the group metadata
path "group-kv/data/education/{{identity.groups.names.education.metadata.region}}/*" {
    capabilities = [ "create", "update", "read", "delete", "list" ]
}

# Group member can update the group information
path "identity/group/id/{{identity.groups.names.education.id}}" {
  capabilities = [ "update", "read" ]
}

# For Web UI usage
path "group-kv/metadata" {
  capabilities = ["list"]
}

path "identity/group/id" {
  capabilities = [ "list" ]
}
EOF

A good practice is to manage your Vault policies as code in a version control system such as Git.

Open a web browser and launch the Vault UI at http://127.0.0.1:8200/ui.
Log in with the root token.
Click the Policies tab, and select Create ACL policy.
Toggle Upload file, and click Choose a file to select the user-tmpl.hcl file. This loads the policy and sets the Name to user-tmpl.
Click the Create Policy button.
Repeat the steps to create the group-tmpl policy.

Set up an entity and a group

Now that you created a policy, create an entity - bob_smith with a user bob, as its entity alias, and a group, education with the bob_smith entity as its group member.

This workflow demonstrates CLI commands and Vault UI to create entities and groups. Refer to the Implement identity entities and groups tutorial if you are not familiar with identities.

Enable the userpass auth method.

$ vault auth enable userpass

$ vault auth enable userpass

Create a new user, bob with password, "training".

$ vault write auth/userpass/users/bob password="training"

$ vault write auth/userpass/users/bob password="training"

Retrieve the userpass mount accessor and save it in a file named accessor.txt.

$ vault auth list -format=json | jq -r '.["userpass/"].accessor' > accessor.txt

$ vault auth list -format=json | jq -r '.["userpass/"].accessor' > accessor.txt

Create a bob_smith entity and save the identity ID in the entity_id.txt.

$ vault write -format=json identity/entity name="bob_smith" \
        policies="user-tmpl" \
        metadata=team="Processor" \
        | jq -r ".data.id" > entity_id.txt

$ vault write -format=json identity/entity name="bob_smith" \
        policies="user-tmpl" \
        metadata=team="Processor" \
        | jq -r ".data.id" > entity_id.txt

Add an entity alias for the bob_smith entity.

$ vault write identity/entity-alias name="bob" \
      canonical_id=$(cat entity_id.txt) \
      mount_accessor=$(cat accessor.txt)

$ vault write identity/entity-alias name="bob" \
      canonical_id=$(cat entity_id.txt) \
      mount_accessor=$(cat accessor.txt)

Create education group and add bob_smith entity as a member. Save the generated group ID in the group_id.txt.

$ vault write -format=json identity/group name="education" \
        policies="group-tmpl" \
        metadata=region="us-west" \
        member_entity_ids=$(cat entity_id.txt)  \
        | jq -r ".data.id" > group_id.txt

$ vault write -format=json identity/group name="education" \
        policies="group-tmpl" \
        metadata=region="us-west" \
        member_entity_ids=$(cat entity_id.txt)  \
        | jq -r ".data.id" > group_id.txt

Click the Access tab, and select Enable new method.
Select Username & Password from the Type drop-down menu.
Click Enable Method.
Select < userpass to return to the userpass auth page, and click Create user.
Enter bob in the Username field, and training in the Password field.
Click Save.
From the Access tab, select Entities and then Create entity.
Enter bob_smith in the Name field and enter user-tmpl in the Policies filed.
Click Create.
Select Create alias. Enter bob in the Name field and select userpass/ (userpass) from the Auth Backend drop-down list.
Click Create.
Click Groups from the left navigation, and select Create group.
Enter education in the Name, and enter group-tmpl in the Policies fields.
Under Metadata, enter region as a key and us-west as the key value.
In the Member Entity IDs field, enter bob_smith.
Click Create.

Test the ACL templating

Enable key/value v2 secrets engine at user-kv.

$ vault secrets enable -path=user-kv kv-v2

$ vault secrets enable -path=user-kv kv-v2

Enable key/value v2 secrets engine at group-kv.

$ vault secrets enable -path=group-kv kv-v2

$ vault secrets enable -path=group-kv kv-v2

Unset the VAULT_TOKEN environment variable so you can log in as a different user.
```
$ unset VAULT_TOKEN
```
```
$ unset VAULT_TOKEN
```

$ vault login -method=userpass username="bob"
Password (will be hidden):

$ vault login -method=userpass username="bob"
Password (will be hidden):

Enter the password training when prompted, and press Return.

Example output:

Key                    Value
---                    -----
token                  5f2b2594-f0b4-0a7b-6f51-767345091dcc
token_accessor         78b652dd-4320-f18f-b882-0732b7ae9ac9
token_duration         768h
token_renewable        true
token_policies         ["default"]
identity_policies      ["group-tmpl" "user-tmpl"]
policies               ["default" "group-tmpl" "user-tmpl"]
token_meta_username    bob

Key                    Value
---                    -----
token                  5f2b2594-f0b4-0a7b-6f51-767345091dcc
token_accessor         78b652dd-4320-f18f-b882-0732b7ae9ac9
token_duration         768h
token_renewable        true
token_policies         ["default"]
identity_policies      ["group-tmpl" "user-tmpl"]
policies               ["default" "group-tmpl" "user-tmpl"]
token_meta_username    bob

Remember that bob is a member of the bob_smith entity; therefore, the "user-kv/data/{{identity.entity.name}}/*" expression in the user-tmpl policy translates to "user-kv/data/bob_smith/*". Let's test!

$ vault kv put user-kv/bob_smith/apikey webapp="12344567890"
Key              Value
---              -----
created_time     2018-08-30T18:28:30.845345444Z
deletion_time    n/a
destroyed        false
version          1

$ vault kv put user-kv/bob_smith/apikey webapp="12344567890"
Key              Value
---              -----
created_time     2018-08-30T18:28:30.845345444Z
deletion_time    n/a
destroyed        false
version          1

Note

Using control loops such as for loops for dynamic path templating may increase response times.

You set the region to us-west for the education group that the bob_smith belongs to. Therefore, the "group-kv/data/education/{{identity.groups.names.education.metadata.region}}/*" expression in the group-tmpl policy translates to "group-kv/data/education/us-west/*".

$ vault kv put group-kv/education/us-west/db_cred password="ABCDEFGHIJKLMN"
Key              Value
---              -----
created_time     2018-08-30T18:29:02.023749491Z
deletion_time    n/a
destroyed        false
version          1

$ vault kv put group-kv/education/us-west/db_cred password="ABCDEFGHIJKLMN"
Key              Value
---              -----
created_time     2018-08-30T18:29:02.023749491Z
deletion_time    n/a
destroyed        false
version          1

Verify that you can update the group information. The group-tmpl policy permits "update" and "read" on the "identity/group/id/{{identity.groups.names.education.id}}" path. In Step 2, you saved the education group ID in the group_id.txt file.

$ vault write identity/group/id/$(cat group_id.txt) \
        policies="group-tmpl" \
        metadata=region="us-west" \
        metadata=contact_email="james@example.com"

$ vault write identity/group/id/$(cat group_id.txt) \
        policies="group-tmpl" \
        metadata=region="us-west" \
        metadata=contact_email="james@example.com"

Read the group information to verify the updated data.

$ vault read identity/group/id/$(cat group_id.txt)

Key                  Value
---                  -----
alias                map[]
creation_time        2018-08-29T20:38:49.383960564Z
id                   d6ee454e-915a-4bef-9e43-4ffd7762cd4c
last_update_time     2018-08-29T22:52:42.005544616Z
member_entity_ids    [1a272450-d147-c3fd-63ae-f16b65b5ee02]
member_group_ids     <nil>
metadata             map[contact_email:james@example.com region:us-west]
modify_index         3
name                 education
parent_group_ids     <nil>
policies             [group-tmpl]
type                 internal

$ vault read identity/group/id/$(cat group_id.txt)

Key                  Value
---                  -----
alias                map[]
creation_time        2018-08-29T20:38:49.383960564Z
id                   d6ee454e-915a-4bef-9e43-4ffd7762cd4c
last_update_time     2018-08-29T22:52:42.005544616Z
member_entity_ids    [1a272450-d147-c3fd-63ae-f16b65b5ee02]
member_group_ids     <nil>
metadata             map[contact_email:james@example.com region:us-west]
modify_index         3
name                 education
parent_group_ids     <nil>
policies             [group-tmpl]
type                 internal

Create an API request payload containing the secrets engine type.

$ tee payload.json <<EOF
{
  "type": "kv",
  "options": {
    "version": "2"
  }
}
EOF

$ tee payload.json <<EOF
{
  "type": "kv",
  "options": {
    "version": "2"
  }
}
EOF

Enable key/value v2 secrets engine at user-kv.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --request POST \
   --data @payload.json \
   $VAULT_ADDR/v1/sys/mounts/user-kv

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --request POST \
   --data @payload.json \
   $VAULT_ADDR/v1/sys/mounts/user-kv

Enable key/value v2 secrets engine at group-kv.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --request POST \
   --data @payload.json \
   $VAULT_ADDR/v1/sys/mounts/group-kv

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --request POST \
   --data @payload.json \
   $VAULT_ADDR/v1/sys/mounts/group-kv

$ BOB_TOKEN=$(curl --request POST \
   --data '{"password": "training"}' \
   $VAULT_ADDR/v1/auth/userpass/login/bob | jq -r ".auth | .client_token")

$ BOB_TOKEN=$(curl --request POST \
   --data '{"password": "training"}' \
   $VAULT_ADDR/v1/auth/userpass/login/bob | jq -r ".auth | .client_token")

$ curl --header "X-Vault-Token: $BOB_TOKEN" \
   --request POST \
   --data '{ "data": {"webapp": "12344567890"} }' \
   $VAULT_ADDR/v1/user-kv/data/bob_smith/apikey | jq

$ curl --header "X-Vault-Token: $BOB_TOKEN" \
   --request POST \
   --data '{ "data": {"webapp": "12344567890"} }' \
   $VAULT_ADDR/v1/user-kv/data/bob_smith/apikey | jq

Example output:

{
  "request_id": "86f8eaa6-e651-b015-8a3a-c76ce6f23397",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "created_time": "2022-04-22T21:01:01.934079423Z",
    "custom_metadata": null,
    "deletion_time": "",
    "destroyed": false,
    "version": 2
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

{
  "request_id": "86f8eaa6-e651-b015-8a3a-c76ce6f23397",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "created_time": "2022-04-22T21:01:01.934079423Z",
    "custom_metadata": null,
    "deletion_time": "",
    "destroyed": false,
    "version": 2
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

$ curl --header "X-Vault-Token: $BOB_TOKEN" \
   --request POST \
   --data '{ "data": {"password": "ABCDEFGHIJKLMN"} }' \
   $VAULT_ADDR/v1/group-kv/data/education/us-west/db_cred | jq

$ curl --header "X-Vault-Token: $BOB_TOKEN" \
   --request POST \
   --data '{ "data": {"password": "ABCDEFGHIJKLMN"} }' \
   $VAULT_ADDR/v1/group-kv/data/education/us-west/db_cred | jq

Example output:

{
  "request_id": "0b19479c-9bf4-4386-45a9-9bd09b1b9424",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "created_time": "2022-04-22T21:05:31.296598836Z",
    "custom_metadata": null,
    "deletion_time": "",
    "destroyed": false,
    "version": 2
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

{
  "request_id": "0b19479c-9bf4-4386-45a9-9bd09b1b9424",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "created_time": "2022-04-22T21:05:31.296598836Z",
    "custom_metadata": null,
    "deletion_time": "",
    "destroyed": false,
    "version": 2
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Verify that you can update the group information. The group-tmpl policy permits "update" and "read" on the "identity/group/id/{{identity.groups.names.education.id}}" path.

First, create an API request payload containing the data you want to write.

$ tee group_info.json <<EOF
{
  "metadata": {
    "region": "us-west",
    "contact_email": "james@example.com"
  },
  "policies": "group-tmpl"
}
EOF

$ tee group_info.json <<EOF
{
  "metadata": {
    "region": "us-west",
    "contact_email": "james@example.com"
  },
  "policies": "group-tmpl"
}
EOF

Verify that you can update.

$ curl --header "X-Vault-Token: $BOB_TOKEN" \
   --request POST \
   --data @group_info.json \
   $VAULT_ADDR/v1/identity/group/id/$(cat group_id.txt)

$ curl --header "X-Vault-Token: $BOB_TOKEN" \
   --request POST \
   --data @group_info.json \
   $VAULT_ADDR/v1/identity/group/id/$(cat group_id.txt)

Read the group information to verify that the updated data.

$ curl --header "X-Vault-Token: $BOB_TOKEN" \
   $VAULT_ADDR/v1/identity/group/id/$(cat group_id.txt) | jq

$ curl --header "X-Vault-Token: $BOB_TOKEN" \
   $VAULT_ADDR/v1/identity/group/id/$(cat group_id.txt) | jq

Example output:

{
  "request_id": "cdbdc0d1-02e9-9e10-97ca-1dddbb66dc7a",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "alias": {},
    "creation_time": "2022-04-22T20:38:21.030628298Z",
    "id": "3bdea0a2-d5e9-a4c9-279d-f34f33def9b8",
    "last_update_time": "2022-04-22T21:09:05.249710904Z",
    "member_entity_ids": [
      "d32795fe-08bd-6792-84cb-a63492048ff7"
    ],
    "member_group_ids": null,
    "metadata": {
      "contact_email": "james@example.com",
      "region": "us-west"
    },
    "modify_index": 2,
    "name": "education",
    "namespace_id": "w6LcK",
    "parent_group_ids": null,
    "policies": [
      "group-tmpl"
    ],
    "type": "internal"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

{
  "request_id": "cdbdc0d1-02e9-9e10-97ca-1dddbb66dc7a",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "alias": {},
    "creation_time": "2022-04-22T20:38:21.030628298Z",
    "id": "3bdea0a2-d5e9-a4c9-279d-f34f33def9b8",
    "last_update_time": "2022-04-22T21:09:05.249710904Z",
    "member_entity_ids": [
      "d32795fe-08bd-6792-84cb-a63492048ff7"
    ],
    "member_group_ids": null,
    "metadata": {
      "contact_email": "james@example.com",
      "region": "us-west"
    },
    "modify_index": 2,
    "name": "education",
    "namespace_id": "w6LcK",
    "parent_group_ids": null,
    "policies": [
      "group-tmpl"
    ],
    "type": "internal"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Create an API request payload containing the secrets engine type.

$ tee payload.json <<EOF
{
  "type": "kv",
  "options": {
    "version": "2"
  }
}
EOF

$ tee payload.json <<EOF
{
  "type": "kv",
  "options": {
    "version": "2"
  }
}
EOF

Enable key/value v2 secrets engine at user-kv.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data @payload.json \
   $VAULT_ADDR/v1/sys/mounts/user-kv

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data @payload.json \
   $VAULT_ADDR/v1/sys/mounts/user-kv

Enable key/value v2 secrets engine at group-kv.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data @payload.json \
   $VAULT_ADDR/v1/sys/mounts/group-kv

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data @payload.json \
   $VAULT_ADDR/v1/sys/mounts/group-kv

$ BOB_TOKEN=$(curl --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{"password": "training"}' \
   $VAULT_ADDR/v1/auth/userpass/login/bob | jq -r ".auth | .client_token")

$ BOB_TOKEN=$(curl --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{"password": "training"}' \
   $VAULT_ADDR/v1/auth/userpass/login/bob | jq -r ".auth | .client_token")

$ curl --header "X-Vault-Token: $BOB_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{ "data": {"webapp": "12344567890"} }' \
   $VAULT_ADDR/v1/user-kv/data/bob_smith/apikey | jq

$ curl --header "X-Vault-Token: $BOB_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{ "data": {"webapp": "12344567890"} }' \
   $VAULT_ADDR/v1/user-kv/data/bob_smith/apikey | jq

Example output:

{
  "request_id": "86f8eaa6-e651-b015-8a3a-c76ce6f23397",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "created_time": "2022-04-22T21:01:01.934079423Z",
    "custom_metadata": null,
    "deletion_time": "",
    "destroyed": false,
    "version": 2
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

{
  "request_id": "86f8eaa6-e651-b015-8a3a-c76ce6f23397",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "created_time": "2022-04-22T21:01:01.934079423Z",
    "custom_metadata": null,
    "deletion_time": "",
    "destroyed": false,
    "version": 2
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

$ curl --header "X-Vault-Token: $BOB_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{ "data": {"password": "ABCDEFGHIJKLMN"} }' \
   $VAULT_ADDR/v1/group-kv/data/education/us-west/db_cred | jq

$ curl --header "X-Vault-Token: $BOB_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{ "data": {"password": "ABCDEFGHIJKLMN"} }' \
   $VAULT_ADDR/v1/group-kv/data/education/us-west/db_cred | jq

Example output:

{
  "request_id": "0b19479c-9bf4-4386-45a9-9bd09b1b9424",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "created_time": "2022-04-22T21:05:31.296598836Z",
    "custom_metadata": null,
    "deletion_time": "",
    "destroyed": false,
    "version": 2
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

{
  "request_id": "0b19479c-9bf4-4386-45a9-9bd09b1b9424",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "created_time": "2022-04-22T21:05:31.296598836Z",
    "custom_metadata": null,
    "deletion_time": "",
    "destroyed": false,
    "version": 2
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Verify that you can update the group information. The group-tmpl policy permits "update" and "read" on the "identity/group/id/{{identity.groups.names.education.id}}" path.

First, create an API request payload containing the data you want to write.

$ tee group_info.json <<EOF
{
  "metadata": {
    "region": "us-west",
    "contact_email": "james@example.com"
  },
  "policies": "group-tmpl"
}
EOF

$ tee group_info.json <<EOF
{
  "metadata": {
    "region": "us-west",
    "contact_email": "james@example.com"
  },
  "policies": "group-tmpl"
}
EOF

Verify that you can update.

$ curl --header "X-Vault-Token: $BOB_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data @group_info.json \
   $VAULT_ADDR/v1/identity/group/id/$(cat group_id.txt)

$ curl --header "X-Vault-Token: $BOB_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data @group_info.json \
   $VAULT_ADDR/v1/identity/group/id/$(cat group_id.txt)

Read the group information to verify that the updated data.

$ curl --header "X-Vault-Token: $BOB_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   $VAULT_ADDR/v1/identity/group/id/$(cat group_id.txt) | jq

$ curl --header "X-Vault-Token: $BOB_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   $VAULT_ADDR/v1/identity/group/id/$(cat group_id.txt) | jq

Example output:

{
  "request_id": "cdbdc0d1-02e9-9e10-97ca-1dddbb66dc7a",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "alias": {},
    "creation_time": "2022-04-22T20:38:21.030628298Z",
    "id": "3bdea0a2-d5e9-a4c9-279d-f34f33def9b8",
    "last_update_time": "2022-04-22T21:09:05.249710904Z",
    "member_entity_ids": [
      "d32795fe-08bd-6792-84cb-a63492048ff7"
    ],
    "member_group_ids": null,
    "metadata": {
      "contact_email": "james@example.com",
      "region": "us-west"
    },
    "modify_index": 2,
    "name": "education",
    "namespace_id": "w6LcK",
    "parent_group_ids": null,
    "policies": [
      "group-tmpl"
    ],
    "type": "internal"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

{
  "request_id": "cdbdc0d1-02e9-9e10-97ca-1dddbb66dc7a",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "alias": {},
    "creation_time": "2022-04-22T20:38:21.030628298Z",
    "id": "3bdea0a2-d5e9-a4c9-279d-f34f33def9b8",
    "last_update_time": "2022-04-22T21:09:05.249710904Z",
    "member_entity_ids": [
      "d32795fe-08bd-6792-84cb-a63492048ff7"
    ],
    "member_group_ids": null,
    "metadata": {
      "contact_email": "james@example.com",
      "region": "us-west"
    },
    "modify_index": 2,
    "name": "education",
    "namespace_id": "w6LcK",
    "parent_group_ids": null,
    "policies": [
      "group-tmpl"
    ],
    "type": "internal"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

In Secrets tab, select Enable new engine.
Select the radio-button for KV, and then click Next.
Enter user-kv in the path field, and then select 2 for KV version.
Click Enable Engine.
Return to Secrets and then select Enable new engine again.
Select the radio-button for KV, and then click Next.
Enter group-kv in the path field, and then select 2 for KV version.
Click Enable Engine.
Sign out as the current user so that you can log in as bob.

Sign off

In the Vault sign in page, select Username.
Enter bob in the Username field, and training in the Password field.
Click Sign in.
Remember that bob is a member of the bob_smith entity; therefore, the "user-kv/data/{{identity.entity.name}}/*" expression in the user-tmpl policy translates to "user-kv/data/bob_smith/*". Select user-kv secrets engine, and then select Create secret.
Enter bob_smith/apikey in the PATH FOR THIS SECRET field, webapp in the key field, and 12344567890 in its value field.
Click Save.
The region is now us-west for the education group that the bob_smith belongs to. Therefore, the "group-kv/data/education/{{identity.groups.names.education.metadata.region}}/*" expression in the group-tmpl policy translates to "group-kv/data/education/us-west/*". From the Secrets tab, select group-kv secrets engine, and then select Create secret.
Enter education/us-west/db_cred in the PATH FOR THIS SECRET field. Enter password in the key field, and ABCDEFGHIJKLMN in its value field.
Click Save.
To verify that you can update the group information, allowed by the "identity/group/id/{{identity.groups.names.education.id}}" expression in the group-tmpl policy, select the Access tab.
Select Groups, and then education.
Select Edit group. Add a new metadata where the key is contact_email and its value is james@example.com.
Click Save. You have updated the group metadata.

Help and Reference

Write a policy using audit logs

Simplify policy management for Kubernetes