• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Vault
  • Install
  • Tutorials
  • Documentation
  • API
  • Integrations
  • Try Cloud(opens in new tab)
  • Sign up
Vault Home

Documentation

Skip to main content
  • Documentation
  • What is Vault?
  • Use Cases

  • Browser Support
  • Installing Vault
    • Overview
    • 'Dev' Server
    • Seal/Unseal
    • Namespace API Lock
    • Lease, Renew, and Revoke
    • Authentication
    • Tokens
    • Identity
    • OIDC Provider
    • Response Wrapping
    • Policies
    • Password Policies
    • Username Templating
    • High Availability
    • Storage
    • PGP, GnuPG, and Keybase
    • Recovery Mode
    • Resource Quotas
    • Transform
    • Mount Migration
    • Duration String Format

  • Vault Integration Program
  • Vault Interoperability Matrix
  • Troubleshoot






  • Glossary


  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Vault
  3. Documentation
  4. Concepts
  5. Identity
  • Vault
  • v1.11.x
  • v1.10.x
  • v1.9.x
  • v1.8.x
  • v1.7.x
  • v1.6.x
  • v1.5.x
  • v1.4.x

ยปIdentity

This document contains conceptual information about Identity along with an overview of the various terminologies and their concepts. The idea of Identity is to maintain the clients who are recognized by Vault. As such, Vault provides an identity management solution through the Identity secrets engine. For more information about the Identity secrets engine and how it is used, refer to the Identity Secrets Engine documentation.

Entities and Aliases

Each user may have multiple accounts with various identity providers, and Vault supports many of those providers to authenticate with Vault. Vault Identity can tie authentications from various auth methods to a single representation. This representation of a consolidated identity is called an Entity and their corresponding accounts with authentication providers can be mapped as Aliases. In essence, each entity is made up of zero or more aliases. An entity cannot have more than one alias for a particular authentication backend.

For example, a user with accounts in both GitHub and LDAP can be mapped to a single entity in Vault with two aliases, one of type GitHub and one of type LDAP.

Entity  overview

However, if both aliases are created on the same auth mount, such as a Github mount, both aliases cannot be mapped to the same entity. The aliases can have the same auth type, as long as the auth mounts are different, and still be associated to the same entity. The diagrams below illustrate both valid and invalid scenarios.

Valid Alias Mapping Invalid Alias Mapping

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 entity identifier will be tied to the authenticated token. When such tokens are used, their entity identifiers are audit logged, marking a trail of actions performed by specific users.

Vault Entity is used to count the number of Vault clients. To learn more about client count, refer to the Client Count documentation.

Entity Management

Entities in Vault do not automatically pull identity information from anywhere. It needs to be explicitly managed by operators. This way, it is flexible in terms of administratively controlling the number of entities to be synced against Vault. In some sense, Vault will serve as a cache of identities and not as a source of identities.

Entity Policies

Vault policies can be assigned to entities which will grant additional permissions to the token on top of the existing policies on the token. If the token presented on the API request contains an identifier for the entity and if that entity has a set of policies on it, then the token will be capable of performing actions allowed by the policies on the entity as well.

Entity policies

This is a paradigm shift in terms of when the policies of the token get evaluated. Before identity, the policy names on the token were immutable (not the contents of those policies though). But with entity policies, along with the immutable set of policy names on the token, the evaluation of policies applicable to the token through its identity will happen at request time. This also adds enormous flexibility to control the behavior of already issued tokens.

It is important to note that the policies on the entity are only a means to grant additional capabilities and not a replacement for the policies on the token. To know the full set of capabilities of the token with an associated entity identifier, the policies on the token should be taken into account.

NOTE: Be careful in granting permissions to non-readonly identity endpoints. If a user can modify an entity, they can grant it additional privileges through policies. If a user can modify an alias they can login with, they can bind it to an entity with higher privileges. If a user can modify group membership, they can add their entity to a group with higher privileges.

Mount Bound Aliases

Vault supports multiple authentication backends and also allows enabling the same type of authentication backend on different mount paths. The alias name of the user will be unique within the backend's mount. But identity store needs to uniquely distinguish between conflicting alias names across different mounts of these identity providers. Hence, the alias name in combination with the authentication backend mount's accessor, serve as the unique identifier of an alias.

The table below shows what information each of the supported auth methods uses to form the alias name. This is the identifying information that is used to match or create an entity. If no entities are explicitly created or merged, then one entity will be implicitly created for each object on the right-hand side of the table, when it is used to authenticate on a particular auth mount point.

Auth methodName reported by auth method
AliCloudPrincipal ID
AppRoleRole ID
AWS IAMConfigurable via iam_alias to one of: Role ID (default), IAM unique ID, Full ARN
AWS EC2Configurable via ec2_alias to one of: Role ID (default), EC2 instance ID, AMI ID
AzureSubject (from JWT claim)
Cloud FoundryApp ID
GitHubUser login name associated with token
Google CloudConfigurable via iam_alias to one of: Role ID (default), Service account unique ID
JWT/OIDCConfigurable via user_claim to one of the presented claims (no default value)
KerberosUsername
KubernetesConfigurable via alias_name_source to one of: Service account UID (default), Service account name
LDAPUsername
OCIRole name
OktaUsername
RADIUSUsername
TLS CertificateSubject CommonName
Tokenentity_alias, if provided
Username (userpass)Username

Local Auth Methods

Vault Enterprise: All the auth methods will generate an entity by default when a token is being issued, with the exception of token store. This is applicable for both mounts that are shared between clusters and cluster local auth mounts (using local=true) when Vault replication is in use. If the goal of marking an auth method as local was to comply to GDPR guidelines, then care must be taken to not set the data pertaining to local auth mount or local auth mount aliases in the metadata of the associated entity.

Implicit Entities

Operators can create entities for all the users of an auth mount beforehand and assign policies to them, so that when users login, the desired capabilities to the tokens via entities are already assigned. But if that's not done, upon a successful user login from any of the authentication backends, Vault will create a new entity and assign an alias against the login that was successful.

Note that the tokens created using the token authentication backend will not normally have any associated identity information. An existing or new implicit entity can be assigned by using the entity_alias parameter, when creating a token using a token role with a configured list of allowed_entity_aliases.

Identity Auditing

If the token used to make API calls has an associated entity identifier, it will be audit logged as well. This leaves a trail of actions performed by specific users.

Identity Groups

Vault identity has support for groups. A group can contain multiple entities as its members. A group can also have subgroups. Policies set on the group are granted to all members of the group. During request time, when the token's entity ID is being evaluated for the policies that it has access to, policies that are inherited due to group memberships are granted along with the policies on the entity itself.

Identity overview

Group Hierarchical Permissions

Entities can be direct members of groups, in which case they inherit the policies of the groups they belong to. Entities can also be indirect members of groups. For example, if a GroupA has GroupB as subgroup, then members of GroupB are indirect members of GroupA. Hence, the members of GroupB will have access to policies on both GroupA and GroupB.

External vs Internal Groups

By default, the groups created in identity store are called the internal groups. The membership management of these groups should be carried out manually. A group can also be created as an external group. In this case, the entity membership in the group is managed semi-automatically. An external group serves as a mapping to a group that is outside of the identity store. External groups can have one (and only one) alias. This alias should map to a notion of a group that is outside of the identity store. For example, groups in LDAP and teams in GitHub. A username in LDAP belonging to a group in LDAP can get its entity ID added as a member of a group in Vault automatically during logins and token renewals. This works only if the group in Vault is an external group and has an alias that maps to the group in LDAP. If the user is removed from the group in LDAP, that change gets reflected in Vault only upon the subsequent login or renewal operation.

For information about Identity Secrets Engine, refer to Identity Secrets Engine.

Tutorial

Refer to the Identity: Entities and Groups tutorial to learn how Vault supports mutliple authentication methods and enables the same authentication method to be used with different mount paths.

Edit this page on GitHub

On this page

  1. Identity
  2. Entities and Aliases
  3. Entity Management
  4. Entity Policies
  5. Mount Bound Aliases
  6. Local Auth Methods
  7. Implicit Entities
  8. Identity Auditing
  9. Identity Groups
  10. Group Hierarchical Permissions
  11. External vs Internal Groups
  12. Tutorial
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)