Difficulty: beginner
Estimated Time: 10 minutes

Vault logo

This scenario supplements the Identity: Entities and Groups guide.

Identity secrets engine is the identity management solution for Vault. It internally maintains the clients who are recognized by HashiCorp Vault. Each client is internally termed as an Entity. An entity can have multiple Aliases. For example, a single user who has accounts in both Github and LDAP, can be mapped to a single entity in Vault that has 2 aliases, one of type Github and one of type LDAP. When a client authenticates via any of the credential backend (except the Token backend), Vault creates a new entity and attaches a new alias to it, if a corresponding entity doesn't already exist. 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.

In this lab, you are going to learn the API-based commands to create entities, entity aliases, and groups. For the purpose of the training, you are going to leverage the userpass auth method. The challenge exercise walks you through creating an external group by mapping a GitHub group to an identity group.

  1. Create an Entity with Alias
  2. Test the Entity
  3. Create an Internal Group
  4. Test the Internal Group

Vault Identity - Entities & Groups

Step 1 of 6

Create Users

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.


A user, Bob Smith at ACME Inc. happened to have two sets of credentials: bob and bsmith. To manage his accounts and link them to an identity Bob Smith, you are going to create an entity for Bob.


NOTE: For the purpose of training, you are going to work with the userpass auth method. But in reality, the user bob might be a username that exists in Active Directory, and bsmith might be Bob's username exists in GitHub, etc.

Login with root token.

Click on the command () will automatically copy it into the terminal and execute it.

vault login root

Execute the following command to enable the userpass auth method:

vault auth enable userpass

Next, create a new policy named, base:

vault policy write base base.hcl

To review the created policy:

vault policy read base

This policy grants CRUD operations on the path starting with secret/training.

Let's create two more policies: test and team-qa.

Execute the following command to create test policy.

vault policy write test test.hcl

Execute the following command to create team-qa policy.

vault policy write team-qa team-qa.hcl

At this point, you should have base, test, and team-qa policies:

vault policy list

Create Users

Create a new user in userpass backend:

  • username: bob
  • password: training
  • policy: test
vault write auth/userpass/users/bob password="training" \

Create another user in userpass backend:

  • username: bsmith
  • password: training
  • policy: team-qa
vault write auth/userpass/users/bsmith password="training" \