How to Use Manually Created Entity When Logging into Vault – HashiCorp Help Center

Introduction

When a client authenticates via any credential backend (except the Token backend), Vault creates a new entity. It attaches a new alias to it if a corresponding entity does not already exist. The newly created entity will be have a unique generated name following the template entity_<random 8-character hex string>. If you would want a custom named entity to be used when logging in to vault, the entity with desired named with an alias mapped to it should be created before logging in to vault.

Expected Outcome

Logging into vault after setting up the entity and alias will use the entity created manually instead of creating the entity named as entity_<random 8-character hex string>.

Procedure

To provide example here, I have deployed a vault enterprise server and setup OIDC auth method using Auth0 as the IDP. After verifying that auth method is setup correctly, we setup the entity and alias.

Step 1: Create entity

Using CLI:

vault write identity/entity name=oidc policies="reader"
Key        Value
---        -----
aliases    <nil>
id         e4b0e488-de75-a860-d1b4-1b66e113d681
name       oidc

Using UI:

Go to Access > Entities > Create Entities
Give it a name, policies and metadata as required and create

Step 2: Create alias

Using CLI:

To correctly map the alias to the entity, we will need the following:

name: Name reported by auth method. Since, I am using OIDC which is configured with user_claim=sub, it maps to the User ID in Auth0. Different auth methods map different attribute to be alias name, refer to this documentation for detailed list.
canonical_id: Entity ID to which this alias belongs to. Entity ID is displayed when entity is created. You could list and read entities to find the correct entity.
mount_accessor: Accessor of the mount to which the alias should belong to. You can run vault auth list and get the accessor value of the mount.

vault write identity/entity-alias name="auth0|639bc56926682264cad4298d" canonical_id=e4b0e488-de75-a860-d1b4-1b66e113d681 mount_accessor=auth_oidc_42217f01

Using UI:

Go to Access > Entities > Choose the correct entity from the list
Click on Add alias
Give it a name that is reported by auth method and choose the correct auth mount. Refer to name parameter explained above.
Click on Create

Step 3: Login

Logging in after setting up the entity and alias, no new entity will be created automatically and the entity that was created manually will be used.
Vault audit log can be used to check which entity is used when logging since audit log records the entity_id of the entity used.

References:

Other Related KBs: