Difficulty: beginner
Estimated Time: 10 minutes


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

This scenario gave you a quick introduction to using key/value secret engine version 2.


Challenge: Create an External Group and Group Alias

The most common use case is to create external groups each of those groups maps to an external group defined in a third-party identity provider (e.g. Active Directory, OpenLDAP, etc.).

This challenge section requires a GitHub account with a team membership to perform.

Create an external group which maps to a GitHub team that your user account belongs to. For example, if your GitHub username, sammy22 which is a member of the training team in hashicorp organization. Then, create an external group named, education, and a group alias named, training pointing to the GitHub auth backend (via github auth mount accessor).

To find out which GitHub team you belong to:

$ curl -H "Authorization: token <your_token>" \

While <your_token> is your GitHub API token. If you do not have one, follow the GitHub documentation to create one.

The output should look like:

      "name": "Training",
      "id": 2074701,
      "slug": "training",
      "description": "Training stuff",
      "privacy": "closed",
      "url": "https://api.github.com/teams/2074701",

NOTE: You want to use the slugified team name.


Don’t stop now! The next scenario will only take about 10 minutes to complete.

Vault Identity - Entities & Groups

Step 1 of 6

Getting Started

Enter the following command to start the Vault server in development mode.

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

vault server -dev -dev-root-token-id="root"

Scroll up the Terminal to locate the following output:

==> Vault server configuration:

             Api Address:
                     Cgo: disabled
         Cluster Address:
              Listener 1: tcp (addr: "", cluster address: "", tls: "disabled")
               Log Level: info
                   Mlock: supported: true, enabled: false
                 Storage: inmem
                 Version: Vault v0.11.1
             Version Sha: 8575f8fedcf8f5a6eb2b4701cb527b99574b5286

WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
and starts unsealed with a single unseal key. The root token is already
authenticated to the CLI, so you can immediately begin using Vault.

When Vault is running in development mode, it runs entirely in-memory that the data does not get persisted. This build-in, pre-configured server is useful for local development, testing and exploration.

Login with root token

Click the + next to the opened Terminal, and select Open New Terminal.

New Terminal

In the Terminal 2, set the VAULT_ADDR environment variable:

export VAULT_ADDR=''

Login with the generated root token.

vault login root

Now, you are logged in as a root and ready to play!