Virtual Event
Join us for the next HashiConf Digital October 12-15, 2020 Register for Free

Access Management

ACL Policy Path Templating

Vault operates on a secure by default standard, and as such, an empty policy grants no permissions in the system. Therefore, policies must be created to govern the behavior of clients and instrument Role-Based Access Control (RBAC) by specifying access privileges (authorization).

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

The Policies guide walks you through the creation of ACL policies in Vault.

»Challenge

The only way to specify non-static paths in ACL policies was to use globs (*) at the end of paths. Or, use plus-sign (+) for a single directory wildcard matching.

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

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

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

»Solution

As of Vault 0.11, ACL templating capability is available to allow a subset of user information to be used within ACL policy paths.

»Prerequisites

To perform the tasks described in this guide, you need to have an environment with Vault 0.11 or later. Refer to the Getting Started guide to install Vault.

NOTE: An interactive tutorial is also available if you do not have a Vault environment to perform the steps described in this guide. Click the Show Tutorial button to launch the tutorial.

»Policy requirements

Since this guide demonstrates the creation of an admin policy, log in with the root token if possible. Otherwise, refer to the policy requirement in the Policies guide.

»Scenario Introduction

Assume that the following policy requirements were given:

  • 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>)

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

  1. Write templated ACL policies
  2. Deploy your policy
  3. Setup an entity and a group
  4. Test the ACL templating

»Step 1: Write templated ACL policies

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

»Available Templating Parameters

NameDescription
identity.entity.idThe entity's ID
identity.entity.nameThe entity's name
identity.entity.metadata.<metadata key>Metadata associated with the entity for the given key
identity.entity.aliases.<mount accessor>.idEntity alias ID for the given mount
identity.entity.aliases.<mount accessor>.nameEntity 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.groups.ids.<group id>.nameThe group name for the given group ID
identity.groups.names.<group name>.idThe group ID for the given group name
identity.groups.names.<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:

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" = []
  }
}

»Write the following policies:

User template (user-tmpl.hcl)

# 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"]
}

Group template (group-tmpl.hcl)

# 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" ]
}

»Step 2: Deploy your policy

Create a new policy called user-tmpl.

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

Create a new policy called group-tmpl.

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

»Step 3: Setup an entity and a group

Let's create an entity, bob_smith with a user bob as its entity alias. Also, create a group, education and add the bob_smith entity as its group member.

Entity & Group

The following command uses jq tool to parse JSON output.

  1. Enable the userpass auth method.

    $ vault auth enable userpass
    
  2. Create a new user, bob with password, "training".

    $ vault write auth/userpass/users/bob password="training"
    
  3. 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
    
  4. 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
    
  5. 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)
    
  6. Finally, 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
    

»Step 4: Test the ACL templating

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

    $ vault secrets enable -path=user-kv kv-v2
    
  2. Enable key/value v2 secrets engine at group-kv.

    $ vault secrets enable -path=group-kv kv-v2
    
  3. Log in as bob.

    $ vault login -method=userpass username="bob" password="training"
    
    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
    
  4. 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
    
  5. The region was set 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/*". Let's verify.

    $ 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
    
  6. 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"
    
  7. Read the group information to verify that the data has been updated.

    $ 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
    

»Help and Reference