a9301012fc
* Update docs with new images * Update website/content/docs/concepts/identity.mdx Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * Remove extraneous Github mention Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com>
197 lines
11 KiB
Plaintext
197 lines
11 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: 'Identity'
|
|
description: >-
|
|
Vault provides an identify management solution to maintain clients who are recognized by Vault.
|
|
---
|
|
|
|
# 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 Identify secrets engine and how it is used, refer to
|
|
the [Identify Secrets Engine](/docs/secrets/identity) 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.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
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](/docs/concepts/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.
|
|
|
|
|
|
|
|
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](#implicit-entities)
|
|
for each object on the right-hand side of the table, when it is used to authenticate on
|
|
a particular auth mount point.
|
|
|
|
| Auth method | Name reported by auth method |
|
|
| ------------------- | ------------------------------------------------------------------------------------ |
|
|
| AliCloud | Principal ID |
|
|
| AppRole | Role ID |
|
|
| AWS IAM | Configurable via `iam_alias` to one of: Role ID (default), IAM unique ID, Full ARN |
|
|
| AWS EC2 | Configurable via `ec2_alias` to one of: Role ID (default), EC2 instance ID, AMI ID |
|
|
| Azure | Subject (from JWT claim) |
|
|
| Cloud Foundry | App ID |
|
|
| GitHub | User login name associated with token |
|
|
| Google Cloud | Configurable via `iam_alias` to one of: Role ID (default), Service account unique ID |
|
|
| JWT/OIDC | Configurable via `user_claim` to one of the presented claims (no default value) |
|
|
| Kerberos | Username |
|
|
| Kubernetes | Service account UID |
|
|
| LDAP | Username |
|
|
| OCI | Role name |
|
|
| Okta | Username |
|
|
| RADIUS | Username |
|
|
| TLS Certificate | Subject CommonName |
|
|
| Token | `entity_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.
|
|
|
|
|
|
|
|
## 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](/docs/secrets/identity).
|
|
|
|
|
|
## Learn
|
|
|
|
Refer to the [Identity: Entities and
|
|
Groups](https://learn.hashicorp.com/tutorials/vault/identity) tutorial for a
|
|
step-by-step tutorial. |