April 6 & 7
Learn about Vault, Consul, & more at HashiDays Sydney in Australia Register Now

Access Management

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.

CLI command / API call using cURL / Web UI

CLI command

  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
    

API call using cURL

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>

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

  1. First, create the API request payload containing the base policy.

    $ tee payload-1.json <<EOF
    {
      "policy": "path \"secret/data/training_*\" {\n   capabilities = [\"create\", \"read\"]\n}"
    }
    EOF
    
  2. Create base policy.

    # Create base policy
    $ curl --header "X-Vault-Token: <TOKEN>" \
           --request PUT \
           --data @payload-1.json \
           http://127.0.0.1:8200/v1/sys/policies/acl/base
    
  3. Create the API request payload containing the test policy.

    $ tee payload-2.json <<EOF
    {
      "policy": "path \"secret/data/test\" {\n capabilities = [ \"create\", \"read\", \"update\", \"delete\" ]\n }"
    }
    EOF
    
  4. Create test policy.

    # Create base policy
    $ curl --header "X-Vault-Token: <TOKEN>" \
           --request PUT \
           --data @payload-2.json \
           http://127.0.0.1:8200/v1/sys/policies/acl/test
    
  5. Create the API request payload containing the team-qa policy.

    $ tee payload-3.json <<EOF
    {
      "policy": "path \"secret/data/team-qa\" {\n capabilities = [ \"create\", \"read\", \"update\", \"delete\" ]\n }"
    }
    EOF
    
  6. Create team-qa policy.

    $ curl --header "X-Vault-Token: <TOKEN>" \
           --request PUT \
           --data @payload-3.json \
           http://127.0.0.1:8200/v1/sys/policies/acl/team-qa
    
  7. List all policies to verify that 'base', 'test' and 'team-qa' policies exist.

    $ curl --header "X-Vault-Token: <TOKEN>" \
           http://127.0.0.1:8200/v1/sys/policies/acl | jq
    
  8. Enable the userpass auth method.

    $ curl --header "X-Vault-Token: <TOKEN>" \
           --request POST \
           --data '{"type": "userpass"}' \
           http://127.0.0.1:8200/v1/sys/auth/userpass
    
  9. Create a new user named bob in userpass where the password is training and test policy is attached.

    $ curl --header "X-Vault-Token: <TOKEN>" \
           --request POST \
           --data '{"password": "training", "policies": "test"}' \
           http://127.0.0.1:8200/v1/auth/userpass/users/bob
    
  10. Create a new user named bsmith in userpass where the password is training and team-qa policy is attached.

    $ curl --header "X-Vault-Token: <TOKEN>" \
           --request POST \
           --data '{"password": "training", "policies": "team-qa"}' \
           http://127.0.0.1:8200/v1/auth/userpass/users/bsmith
    
  11. Execute the following command to discover the mount accessor for the userpass auth method.

    $ curl --header "X-Vault-Token: <TOKEN>" \
           http://127.0.0.1:8200/v1/sys/auth | jq
     {
       ...
       "userpass/": {
         "accessor": "auth_userpass_9b6cd254",
        ...
       },
       ...
    

    Make a note of the userpass accessor value (auth_userpass_XXXXX).

  12. Create an API payload to create bob-smith entity.

    $ tee payload.json <<EOF
    {
      "name": "bob-smith",
      "metadata": {
        "organization": "ACME Inc.",
        "team": "QA"
      },
      "policies": ["base"]
    }
    EOF
    
  13. Create bob-smith entity.

    $ curl --header "X-Vault-Token: <TOKEN>" \
           --request POST \
           --data @payload.json \
           http://127.0.0.1:8200/v1/identity/entity
    {
      "request_id": "4d4d340f-f4c9-0201-c87e-42cc140a383a",
      "lease_id": "",
      "renewable": false,
      "lease_duration": 0,
      "data": {
        "aliases": null,
        "id": "6ded4d31-481f-040b-11ad-c6db0cb4d211"
      },
      ...
    

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

  14. Now, add the user bob to the bob-smith entity by creating an entity alias. In the request body, you need to pass the userpass name as name, the userpass accessor value as mount_accessor, and the entity id as canonical_id.

    Example:

    Create the API request payload.

    $ tee payload-bob.json <<EOF
    {
      "name": "bob",
      "canonical_id": "6ded4d31-481f-040b-11ad-c6db0cb4d211",
      "mount_accessor": "auth_userpass_9b6cd254"
    }
    EOF
    

    Use the identity/entity-alias endpoint to add an entity alias.

    $ curl --header "X-Vault-Token: <TOKEN>" \
           --request POST \
           --data @payload-bob.json \
           http://127.0.0.1:8200/v1/identity/entity-alias
    
  15. Repeat the step to add user bsmith to the bob-smith entity.

    Example:

    Create the API request payload.

    $ tee payload-bsmith.json <<EOF
    {
     "name": "bsmith",
     "canonical_id": "6ded4d31-481f-040b-11ad-c6db0cb4d211",
     "mount_accessor": "auth_userpass_9b6cd254"
    }
    EOF
    

    Use the identity/entity-alias endpoint to add an entity alias.

    $ curl --header "X-Vault-Token: <TOKEN>" \
           --request POST \
           --data @payload-bsmith.json \
           http://127.0.0.1:8200/v1/identity/entity-alias
    
  16. Review the entity details. (NOTE: Be sure to enter the entity ID matching your environment.)

    $ curl --header "X-Vault-Token: <TOKEN>" \
          http://127.0.0.1:8200/v1/identity/entity/id/<ENTITY_ID>
    {
      "request_id": "cc0793bf-fafe-4b2c-fd82-88855712845c",
      "lease_id": "",
      "renewable": false,
      "lease_duration": 0,
      "data": {
        "aliases": [
          {
            "canonical_id": "6ded4d31-481f-040b-11ad-c6db0cb4d211",
            ...
            "mount_type": "userpass",
            "name": "bob"
          },
          {
            "canonical_id": "6ded4d31-481f-040b-11ad-c6db0cb4d211",
            ...
            "mount_type": "userpass",
            "name": "bsmith"
          }
        ],
        ...
    

    The bob and bsmith users should appear in the entity alias list.

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

    Create an API request payload specifying the secrets engine type.

    # Specify the secrets engine type and its version in the API request payload
    $ tee payload.json <<EOF
    {
      "type": "kv",
      "options": {
        "version": "2"
      }
    }
    EOF
    

    Use the sys/mounts/ endpoint to enable the K/V v2 secrets engine at secret/

    $ curl --header "X-Vault-Token: <TOKEN>" \
           --request POST \
           --data @payload.json \
           https://127.0.0.1:8200/v1/sys/mounts/secret
    

Web UI

  1. Open a web browser and launch the Vault UI (e.g. http://127.0.0.1:8200/ui) and then login.

  2. Click the Policies tab, and then select Create ACL policy.

  3. Toggle Upload file sliding switch, and click Choose a file to select your base.hcl file you authored. This loads the policy and sets the Name to be base. Create Policy

  4. Click Create Policy to complete.

  5. Repeat the steps to create policies for test and team-qa as well.

    Create Policy

  6. Click the Access tab, and select Enable new method.

    Enable Auth Method

  7. Select the Username & Password radio button.

    Create Policy

  8. Click Next.

  9. Leave the path as default and click Enable Method.

  10. Click the Vault CLI shell icon (>_) to open a command shell. Execute vault write auth/userpass/users/bob password=training policies=test in the CLI shell to create a new user, bob:

    Create bob

  11. Execute vault write auth/userpass/users/bsmith password=training policies=team-qa to create another user, bsmith.

  12. Click the icon (>_) again to hide the shell.

  13. From the Access tab, select Entities and then Create entity to create a new entity, bob-smith. Populate the Name, Policies and Metadata fields as shown below:

    Create Policy

  14. Click Create.

  15. Select Add alias. Enter bob in the Name field and select userpass/ (userpass) from the Auth Backend drop-down list.

    Create Policy

  16. Click Create.

  17. Return to the Entities list. Select Add alias from the bob-smith entity menu, and then Add alias.

  18. Enter bsmith in the Name field and select userpass/ (userpass) from the Auth Backend drop-down list, and then click Create.

  19. Return to the Entities > bob-smith and select Aliases. Bothbob and bsmith should be listed.

    Create Policy

  20. Since the policies were written against secret/ path, enable key/value secrets engine at secret/ if it's not already enabled. Select Secrets and then Enable new engine.

  21. Select the KV radio button and then click Next.

  22. Enter secret in the Path field, and then click Enable Engine.

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.

CLI command / API call using cURL

CLI command

  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.

API call using cURL

  1. First, login as bob.

    $ curl --request POST \
           --data '{"password": "training"}' \
           http://127.0.0.1:8200/v1/auth/userpass/login/bob | jq
    {
     ...
     "auth": {
       "client_token": "b3c2ac10-9f8f-4e64-9a1c-337236ba20f6",
       "accessor": "92204429-6555-772e-cf51-52492d7f1686",
       "policies": [
         "base",
         "default",
         "test"
       ],
       "token_policies": [
          "default",
          "test"
        ],
        "identity_policies": [
          "base"
        ],
       ...
    
  2. The test policy grants CRUD operations on the secret/test path. Test to make sure that you can write secrets in the path.

    $ curl --header "X-Vault-Token: <TOKEN>" \
           --request POST \
           --data '{"data":{"owner": "bob"}}' \
           http://127.0.0.1:8200/v1/secret/data/test | jq
    
  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.

    $ curl --header "X-Vault-Token: <TOKEN>" \
           --request POST \
           --data '{"paths": ["secret/data/training_test"]}'
           http://127.0.0.1:8200/v1/sys/capabilities-self | jq
    {
     "secret/data/training_test": [
       "create",
       "read"
     ],
     ...snip...
    

    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_*.

  4. What about the secret/team-qa path?

    $ curl --header "X-Vault-Token: <TOKEN>" \
           --request POST \
           --data '{"paths": ["secret/data/team-qa"]}'
           http://127.0.0.1:8200/v1/sys/capabilities-self | jq
    {
     "secret/data/team-qa": [
       "deny"
     ],
     ...snip...
    

     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.

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

CLI command / API call using cURL / Web UI

CLI command

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.

API call using cURL

Create an API request payload containing the team-eng policy.

$ tee payload.json <<EOF
{
 "policy": "path \"secret/data/team/eng\" {\n capabilities = [\"create\", \"read\", ... }"
}
EOF

Create a new policy named team-eng.

$ curl --header "X-Vault-Token: <TOKEN>" \
       --request PUT \
       --data @payload-1.json \
       http://127.0.0.1:8200/v1/sys/policies/acl/team-eng

Create an API request payload to create an internal group named engineers. NOTE: Be sure to replace <ENTITY_ID> with correct value.

# API request msg payload.  Be sure to replace <ENTITY_ID> with correct value
$ tee payload-group.json <<EOF
{
  "name": "engineers",
  "policies": ["team-eng"],
  "member_entity_ids": ["<ENTITY_ID>"],
  "metadata": {
    "team": "Engineering",
    "region": "North America"
  }
}
EOF

Use the /identity/group endpoint to create an internal group named engineers and add bob-smith entity as a group member and attach team-eng.

$ curl --header "X-Vault-Token: <TOKEN>" \
       --request PUT \
       --data @payload-group.json \
       http://127.0.0.1:8200/v1/identity/group | jq
{
   "request_id": "2b6eefd6-67a6-31c7-dbc3-11c1c132e2cf",
   "lease_id": "",
   "renewable": false,
   "lease_duration": 0,
   "data": {
     "id": "d62157aa-b5f6-b6fe-aa40-0ffc54defc41",
     "name": "engineers"
   },
   ...snip...

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.

Web UI

  1. Click the Policies tab, and then select Create ACL policy.

  2. Toggle Upload file sliding switch, and click Choose a file to select your team-eng.hcl file you authored. This loads the policy and sets the Name to be team-eng.

  3. Click Create Policy to complete.

  4. Click the Access tab and select Entities .

  5. Click Groups from the left navigation, and select Create group.

  6. Enter the group information as shown below. Group

  7. Click Create.

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

CLI command / API call using cURL / Web UI

CLI command

  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>"
    

API call using cURL

  1. Create an API request payload containing stringfied education policy.

    $ tee payload-pol.json <<EOF
    {
      "policy": "path\n "secret/data/education" {\n capabilities = [ "create", "read", "update", "delete", "list" ]\n }"
    }
    EOF
    
  2. Create education policy.

    $ curl --header "X-Vault-Token: <TOKEN>" \
           --request PUT \
           --data @payload-pol.json \
           http://127.0.0.1:8200/v1/sys/policies/acl/education
    
  3. Enable GitHub Auth Method at github.

    $ curl --header "X-Vault-Token: <TOKEN>" \
           --request POST \
           --data '{"type": "github"}' \
           http://127.0.0.1:8200/v1/sys/auth/github
    
  4. Configure GitHub auth method by setting organization.

    $ curl --header "X-Vault-Token: <TOKEN>" \
           --request POST \
           --data '{"organization": "example-inc"}' \
           http://127.0.0.1:8200/v1/auth/github/config
    
  5. Get the github accessor value (auth_github_XXXXX).

    $ curl --header "X-Vault-Token: <TOKEN>" \
          http://127.0.0.1:8200/v1/sys/auth | jq
    {
      ...
      "userpass/": {
        "accessor": "auth_github_91010f60",
       ...
      },
      ...
    }
    
  6. Create an API request payload to create an external group.

    $ tee payload-edu.json <<EOF
    {
       "name": "education",
       "policies": ["education"],
       "type": "external",
       "metadata": {
         "organization": "Product Education"
       }
    }
    EOF
    
  7. Create an external group named education. Be sure to copy the group ID (id).

    $ curl --header "X-Vault-Token: <TOKEN>" \
           --request POST \
           --data @payload-edu.json \
           http://127.0.0.1:8200/v1/identity/group | jq
    {
       "request_id": "a8161086-13db-f982-4216-7d996eae3fd9",
       "lease_id": "",
       "renewable": false,
       "lease_duration": 0,
       "data": {
         "id": "ea18cb62-2478-d370-b726-a77d1700de80",
         "name": "education"
       },
      ...snip...
    
  8. Create an API request payload to create a group aliases named training.

    $ tee payload-training.json <<EOF
    {
      "canonical_id": "<GROUP_ID>",
      "mount_accessor": "auth_github_XXXXX",
      "name": "training"
    }
    EOF
    
  9. Create training group alias.

    $ curl --header "X-Vault-Token: <TOKEN>" \
           --request POST \
           --data @payload-training.json \
           http://127.0.0.1:8200/v1/identity/group-alias | jq
    

Web UI

  1. Click the Policies tab, and then select Create ACL policy.

  2. Toggle Upload file sliding switch, and click Choose a file to select your education.hcl file you authored. This loads the policy and sets the Name to be education.

  3. Click Create Policy to complete.

  4. Click the Access tab and select Auth Methods.

  5. Select Enable new method.

  6. Select the GitHub radio button and click Next.

  7. Leave the path as github and click Enable Method.

  8. Click the Access tab and select Groups.

  9. Select Create group. Enter the group information as shown below. Create Policy

  10. Click Create.

  11. Select Add alias and enter training in the Name field. Select github/ (github) from the Auth Backend drop-down list. Create Policy

  12. Click Create.

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