Security

Identity: Entities and Groups

Vault supports multiple authentication methods and also allows enabling the same type of authentication method on different mount paths. Each Vault client may have multiple accounts with various identity providers that are enabled on the Vault server.

Vault clients can be mapped as entities and their corresponding accounts with authentication providers can be mapped as aliases. In essence, each entity is made up of zero or more aliases. Identity secrets engine internally maintains the clients who are recognized by Vault.

Personas

The steps described in this guide are typically performed by operations persona.

Challenge

Bob has accounts in both Github and LDAP. Both Github and LDAP auth methods are enabled on the Vault server that he can authenticate using either one of his accounts. Although both accounts belong to Bob, there is no association between the two accounts to set some common properties.

Solution

Create an entity representing Bob, and associate aliases representing each of his accounts as the entity member. You can set additional policies and metadata on the entity level so that both accounts can inherit.

When Bob authenticates using either one of his accounts, the entity identifier will be tied to the authenticated token. When such tokens are put to use, their entity identifiers are audit logged, marking a trail of actions performed by specific users.

Prerequisites

To perform the tasks described in this guide, you need to have a Vault environment. Refer to the Getting Started guide to install Vault. Make sure that your Vault server has been initialized and unsealed.

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

To perform all tasks demonstrated in this guide, your policy must include the following permissions:

# Configure auth methods
path "sys/auth" {
  capabilities = [ "read", "list" ]
}

# Configure auth methods
path "sys/auth/*" {
  capabilities = [ "create", "update", "read", "delete", "list", "sudo" ]
}

# Manage userpass auth methods
path "auth/userpass/*" {
  capabilities = [ "create", "read", "update", "delete" ]
}

# Manage github auth methods
path "auth/github/*" {
  capabilities = [ "create", "read", "update", "delete" ]
}

# Display the Policies tab in UI
path "sys/policies" {
  capabilities = [ "read", "list" ]
}

# Create and manage ACL policies from UI
path "sys/policies/acl/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

# Create and manage policies
path "sys/policies/acl" {
  capabilities = [ "read", "list" ]
}

# Create and manage policies
path "sys/policies/acl/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

# List available secrets engines to retrieve accessor ID
path "sys/mounts" {
  capabilities = [ "read" ]
}

# Create and manage entities and groups
path "identity/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

If you are not familiar with policies, complete the policies guide.

Step 1: Create an Entity with Alias

You are going to create a new entity with base policy assigned. The entity defines two entity aliases with each has a different policy assigned.

Scenario: A user, Bob Smith at ACME Inc. happened to have two sets of credentials: bob and bsmith. He can authenticate with Vault using either one of his accounts. To manage his accounts and link them to identity Bob Smith in QA team, you are going to create an entity for Bob.

Entity Bob Smith

Scenario Policies

base.hcl

path "secret/data/training_*" {
   capabilities = ["create", "read"]
}

test.hcl

path "secret/data/test" {
   capabilities = [ "create", "read", "update", "delete" ]
}

team-qa.hcl

path "secret/data/team-qa" {
   capabilities = [ "create", "read", "update", "delete" ]
}

Now, you are going to create bob and bsmith users with appropriate policies attached.

  1. Create base policy.

    $ vault policy write base base.hcl
    
  2. Create test policy.

    $ vault policy write test test.hcl
    
  3. Create team-qa policy.

    $ vault policy write team-qa team-qa.hcl
    
  4. List all policies to verify that 'base', 'test' and 'team-qa' policies exist.

    $ vault policy list
    base
    default
    team-qa
    test
    root
    
  5. Enable the userpass auth method.

    $ vault auth enable userpass
    
  6. Create a new user named bob in userpass where the password is training and test policy is attached.

    $ vault write auth/userpass/users/bob password="training" policies="test"
    
  7. Create a new user named bsmith in userpass where the password is training and team-qa policy is attached.

    $ vault write auth/userpass/users/bsmith password="training" policies="team-qa"
    
  8. Execute the following command to discover the mount accessor for the userpass auth method.

    $ vault auth list -detailed
    Path                  Type        Accessor                ...
    ----                  ----        --------                ...
    token/                token       auth_token_bec8530a     ...
    userpass/             userpass    auth_userpass_70eba76b  ...
    

    In the output, locate the Accessor value for userpass.

  9. Run the following command to store the userpass accessor value in a file named accessor.txt.

    $ vault auth list -format=json | jq -r '.["userpass/"].accessor' > accessor.txt
    
  10. Create an entity for bob-smith.

    $ vault write identity/entity name="bob-smith" policies="base" \
            metadata=organization="ACME Inc." \
            metadata=team="QA"
    
    Key        Value
    ---        -----
    aliases    <nil>
    id         631256b1-8523-9838-5501-d0a1e2cdad9c
    

    Make a note of the generated entity ID (id).

  11. Now, add the user bob to the bob-smith entity by creating an entity alias.

    $ vault write identity/entity-alias name="bob" \
            canonical_id=<entity_id> \
            mount_accessor=<userpass_accessor>
    

    The <userpass_accessor> value is stored in accessor.txt.

    Example:

    $ vault write identity/entity-alias name="bob" \
            canonical_id="631256b1-8523-9838-5501-d0a1e2cdad9c" \
            mount_accessor=$(cat accessor.txt)
    
    Key             Value
    ---             -----
    canonical_id    631256b1-8523-9838-5501-d0a1e2cdad9c
    id              873f7b12-dec8-c182-024e-e3f065d8a9f1
    
  12. Repeat the step to add user bsmith to the bob-smith entity.

    Example:

    $ vault write identity/entity-alias name="bsmith" \
            canonical_id="631256b1-8523-9838-5501-d0a1e2cdad9c" \
            mount_accessor=$(cat accessor.txt)
    
    Key             Value
    ---             -----
    canonical_id    631256b1-8523-9838-5501-d0a1e2cdad9c
    id              55d46747-b99e-6a82-05f5-61bb60fd7d15
    
  13. Review the entity details.

    $ vault read identity/entity/id/<entity_id>
    

    The output should include the entity aliases, metadata (organization, and team), and base policy.

  14. Since the policies were written against secret/ path, enable key/value secrets engine at secret/ if it's not already done so.

    $ vault secrets enable -path=secret/ kv-v2
    

Step 2: Test the Entity

To better understand how a token inherits the capabilities from the entity's policy, you are going to test it by logging in as bob.

  1. First, login as bob.

    $ vault login -method=userpass username=bob password=training
    
    Key                    Value
    ---                    -----
    token                  ac318416-0dc1-4311-67e4-b58381c86fde
    token_accessor         79cced7b-51df-9523-920f-a1579687516b
    token_duration         768h
    token_renewable        true
    token_policies         ["default" "test"]
    identity_policies      ["base"]
    policies               ["base" "default" "test"]
    token_meta_username    bob
    
  2. The test policy grants CRUD operations on the secret/test path. Test to make sure that you can write secrets in the path.

    $ vault kv put secret/test owner="bob"
    Success! Data written to: secret/test
    
  3. Although the username bob does not have base policy attached, the token inherits the capabilities granted in the base policy because bob is a member of the bob-smith entity, and the entity has base policy attached. Check to see that the bob's token inherited the capabilities.

    $ vault token capabilities secret/data/training_test
    create, read
    
  4. The base policy grants create and read capabilities on secret/training_* path; therefore bob is permitted to run create and read operations against any path starting with secret/training_*.

    What about the secret/team-qa path?

    $ vault token capabilities secret/data/team-qa
    deny
    

    The user bob only inherits capability from its associating entity's policy. The user can access the secret/team-qa path only if he logs in with bsmith credentials.

  5. Log back in with the token you used to configure the entity before proceed to Step 3.

Step 3: Create an Internal Group

Now, you are going to create an internal group named engineers. Its member is bob-smith entity that you created in Step 1.

Entity Bob Smith

The group policy, team-eng defines the following in the team-eng.hcl file.

path "secret/data/team/eng" {
  capabilities = [ "create", "read", "update", "delete"]
}

Create a new policy named team-eng.

$ vault policy write team-eng ./team-eng.hcl

Create an internal group named engineers and add bob-smith entity as a group member and attach team-eng.

$ vault write identity/group name="engineers" \
        policies="team-eng" \
        member_entity_ids=<entity_id> \
        metadata=team="Engineering" \
        metadata=region="North America"

Where <entity_id> is the value you copied at Step 1.

Example:

$ vault write identity/group name="engineers" \
        policies="team-eng" \
        member_entity_ids="631256b1-8523-9838-5501..."  \
        metadata=team="Engineering" \
        metadata=region="North America"

Key     Value
---     -----
id      81bdac90-284a-7b8c-6289-5fa7693bcb4a
name    engineers

Now, when you login as bob or bsmith, its generated token inherits the group-level policy, team-eng. You can perform similar tests demonstrated in Step 2 to verify that.

Summary

By default, Vault creates an internal group. When you create an internal group, you specify the group members rather than group alias. Group aliases are mapping between Vault and external identity providers (e.g. LDAP, GitHub, etc.). Therefore you define group aliases only when you create external groups. For internal groups, you specify member_entity_ids and/or member_group_ids.

Step 4: Create an External Group

It is common for organizations to enable auth methods such as LDAP, Okta and perhaps GitHub to handle the Vault user authentication, and individual user's group memberships are defined within those identity providers.

In order to manage the group-level authorization, you can create an external group to link Vault with the external identity provider (auth provider) and attach appropriate policies to the group.

Example Scenario

Any user who belongs to training team in GitHub organization, example-inc are permitted to perform all operations against the secret/education path.

Policy: education.hcl

path "secret/data/education" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}
  1. Create a new policy named education.

    $ vault policy write education education.hcl
    
  2. Enable GitHub auth method.

    $ vault auth enable github
    
  3. Retrieve the mount accessor for the GitHub auth method and save it in a file named accessor.txt.

    $ vault auth list -format=json | jq -r '.["github/"].accessor' > accessor.txt
    
  4. Configure to point to your GitHub organization (e.g. hashicorp).

    $ vault write auth/github/config organization=example-inc
    
  5. Create an external group named education. Be sure to copy the generated group ID.

    $ vault write identity/group name="education" \
            policies="education" \
            type="external" \
            metadata=organization="Product Education"
    
  6. Create a group alias where canonical_id is the group ID and the name is the actual GitHub team name. (NOTE: Use slugified team name.)

    $ vault write identity/group-alias name="training" \
            mount_accessor=$(cat accessor.txt) \
            canonical_id="<group_ID>"
    

Summary

At this point, any GitHub user who belongs to training team within the example-inc organization can authenticate with Vault. The generated token for the user has education policy attached.

Help and Reference