1--- 2layout: "docs" 3page_title: "Identity - Secrets Engines" 4sidebar_title: "Identity" 5sidebar_current: "docs-secrets-identity" 6description: |- 7 The Identity secrets engine for Vault manages client identities. 8--- 9 10# Identity Secrets Engine 11 12Name: `identity` 13 14The Identity secrets engine is the identity management solution for Vault. It 15internally maintains the clients who are recognized by Vault. Each client is 16internally termed as an `Entity`. An entity can have multiple `Aliases`. For 17example, a single user who has accounts in both GitHub and LDAP, can be mapped 18to a single entity in Vault that has 2 aliases, one of type GitHub and one of 19type LDAP. When a client authenticates via any of the credential backend 20(except the Token backend), Vault creates a new entity and attaches a new 21alias to it, if a corresponding entity doesn't already exist. The entity identifier will 22be tied to the authenticated token. When such tokens are put to use, their 23entity identifiers are audit logged, marking a trail of actions performed by 24specific users. 25 26Identity store allows operators to **manage** the entities in Vault. Entities 27can be created and aliases can be tied to entities, via the ACL'd API. There 28can be policies set on the entities which adds capabilities to the tokens that 29are tied to entity identifiers. The capabilities granted to tokens via the 30entities are **an addition** to the existing capabilities of the token and 31**not** a replacement. The capabilities of the token that get inherited from 32entities are computed dynamically at request time. This provides flexibility in 33controlling the access of tokens that are already issued. 34 35This secrets engine will be mounted by default. This secrets engine cannot be 36disabled or moved. 37 38## Concepts 39 40### Entities and Aliases 41 42Each user will have multiple accounts with various identity providers. Users 43can now be mapped as `Entities` and their corresponding accounts with 44authentication providers can be mapped as `Aliases`. In essence, each entity is 45made up of zero or more aliases. 46 47### Entity Management 48 49Entities in Vault **do not** automatically pull identity information from 50anywhere. It needs to be explicitly managed by operators. This way, it is 51flexible in terms of administratively controlling the number of entities to be 52synced against Vault. In some sense, Vault will serve as a _cache_ of 53identities and not as a _source_ of identities. 54 55### Entity Policies 56 57Vault policies can be assigned to entities which will grant _additional_ 58permissions to the token on top of the existing policies on the token. If the 59token presented on the API request contains an identifier for the entity and if 60that entity has a set of policies on it, then the token will be capable of 61performing actions allowed by the policies on the entity as well. 62 63This is a paradigm shift in terms of _when_ the policies of the token get 64evaluated. Before identity, the policy names on the token were immutable (not 65the contents of those policies though). But with entity policies, along with 66the immutable set of policy names on the token, the evaluation of policies 67applicable to the token through its identity will happen at request time. This 68also adds enormous flexibility to control the behavior of already issued 69tokens. 70 71Its important to note that the policies on the entity are only a means to grant 72_additional_ capabilities and not a replacement for the policies on the token. 73To know the full set of capabilities of the token with an associated entity 74identifier, the policies on the token should be taken into account. 75 76### Mount Bound Aliases 77 78Vault supports multiple authentication backends and also allows enabling the 79same type of authentication backend on different mount paths. The alias name of 80the user will be unique within the backend's mount. But identity store needs to 81uniquely distinguish between conflicting alias names across different mounts of 82these identity providers. Hence, the alias name in combination with the 83authentication backend mount's accessor, serve as the unique identifier of an 84alias. 85 86### Implicit Entities 87 88Operators can create entities for all the users of an auth mount beforehand and 89assign policies to them, so that when users login, the desired capabilities to 90the tokens via entities are already assigned. But if that's not done, upon a 91successful user login from any of the authentication backends, Vault will 92create a new entity and assign an alias against the login that was successful. 93 94Note that the tokens created using the token authentication backend will not 95have an associated identity information. Logging in using the authentication 96backends is the only way to create tokens that have a valid entity identifiers. 97 98### Identity Auditing 99 100If the token used to make API calls have an associated entity identifier, it 101will be audit logged as well. This leaves a trail of actions performed by 102specific users. 103 104### Identity Groups 105 106In version 0.9, Vault identity has support for groups. A group can contain 107multiple entities as its members. A group can also have subgroups. Policies set 108on the group is granted to all members of the group. During request time, when 109the token's entity ID is being evaluated for the policies that it has access 110to; along with the policies on the entity itself, policies that are inherited 111due to group memberships are also granted. 112 113### Group Hierarchical Permissions 114 115Entities can be direct members of groups, in which case they inherit the 116policies of the groups they belong to. Entities can also be indirect members of 117groups. For example, if a GroupA has GroupB as subgroup, then members of GroupB 118are indirect members of GroupA. Hence, the members of GroupB will have access 119to policies on both GroupA and GroupB. 120 121### External vs Internal Groups 122 123By default, the groups created in identity store are called the internal 124groups. The membership management of these groups should be carried out 125manually. A group can also be created as an external group. In this case, the 126entity membership in the group is managed semi-automatically. External group 127serves as a mapping to a group that is outside of the identity store. External 128groups can have one (and only one) alias. This alias should map to a notion of 129group that is outside of the identity store. For example, groups in LDAP, and 130teams in GitHub. A username in LDAP, belonging to a group in LDAP, can get its 131entity ID added as a member of a group in Vault automatically during *logins* 132and *token renewals*. This works only if the group in Vault is an external 133group and has an alias that maps to the group in LDAP. If the user is removed 134from the group in LDAP, that change gets reflected in Vault only upon the 135subsequent login or renewal operation. 136 137## Identity Tokens 138 139Identity information is used throughout Vault, but it can also be exported for 140use by other applications. An authorized user/application can request a token 141that encapsulates identity information for their associated entity. These 142tokens are signed JWTs following the [OIDC ID 143token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) structure. 144The public keys used to authenticate the tokens are published by Vault on an 145unauthenticated endpoint following OIDC discovery and JWKS conventions, which 146should be a directly usable by JWT/OIDC libraries. An introspection endpoint is 147also provided by Vault for token verification. 148 149### Roles and Keys 150 151OIDC-compliant ID tokens are generated against a role which allows configuration 152of token claims via a templating system, token ttl, and a way to specify which 153"key" will be used to sign the token. The role template is an optional parameter 154to customize the token contents and is described in the next section. Token TTL 155controls the expiration time of the token, after which verification library will 156consider the token invalid. All roles have a Vault-generated `client_id` 157attribute that is returned when the role is read. This value cannot be changed 158and will be added to the token's `aud` parameter. JWT/OIDC libraries will often 159require this value. 160 161A role's `key` parameter links a role to an existing named key (multiple roles 162may refer to the same key). It is not possible to generate an unsigned ID token. 163 164A named key is a public/private key pair generated by Vault. The private key is 165used to sign the identity tokens, and the public key is used by clients to 166verify the signature. Key are regularly rotated, whereby a new key pair is 167generated and the previous _public_ key is retained for a limited time for 168verification purposes. 169 170A named key's configuration specifies a rotation period, a verification ttl, and 171signing algorithm. Rotation period specifies the frequency at which a new 172signing key is generated and the private portion of the previous signing key is 173deleted. Verification ttl is the time a public key is retained for verification, 174after being rotated. By default, keys are rotated every 24 hours, and continue 175to be available for verification for 24 hours after their rotation. 176 177 178### Token Contents and Templates 179 180Identity tokens will always contain, at a minimum, the claims required by OIDC: 181 182* `iss` - Issuer URL 183* `sub` - Requester's entity ID 184* `aud` - `client_id` for the role 185* `iss` - Time of issue 186* `exp` - Expiration time for the token 187 188In addition, the operator may configure per-role templates that allow a variety 189of other entity information to be added to the token. The templates are 190structured as JSON with replaceable parameters. The parameter syntax is the same 191as that used for [ACL Path Templating](/docs/concepts/policies.html). 192 193For example: 194 195```json 196{ 197 "color": {{identity.entity.metadata.color}}, 198 "userinfo": { 199 "username": {{identity.entity.aliases.usermap_123.metadata.username}}, 200 "groups": {{identity.entity.group_names}} 201 202 "nbf": {{time.now}}, 203} 204``` 205 206When a token is requested, the resulting template might be populated as: 207 208```json 209{ 210 "color": "green", 211 "userinfo": { 212 "username": "bob", 213 "groups": ["web", "engr", "default] 214 215 "nbf": 1561411915, 216} 217``` 218 219which would be merged with the base OIDC claims into the final token: 220 221```json 222{ 223 "iss": "https://10.1.1.45:8200/v1/identity/oidc", 224 "sub": "a2cd63d3-5364-406f-980e-8d71bb0692f5", 225 "aud": "SxSouteCYPBoaTFy94hFghmekos", 226 "iss": 1561411915, 227 "exp": 1561412215, 228 "color": "green", 229 "userinfo": { 230 "username": "bob", 231 "groups": ["web", "engr", "default] 232 }, 233 "nbf": 1561411915, 234} 235``` 236 237Note how the template is merged, with top level template keys becoming top level 238token keys. For this reason, templates may not contain top level keys that 239overwrite the standard OIDC claims. 240 241Template parameters that are not present for an entity, such as a metadata that 242isn't present, or an alias accessor which doesn't exist, are simply empty 243strings or objects, depending on the data type. 244 245Templates are configured on the role and may be optionally encoded as base64. 246 247The full list of template parameters is shown below: 248 249| Name | Description | 250| :--------------------------------------------------------------------- | :-------------------------------------------------------------------------------------- | 251| `identity.entity.id` | The entity's ID | 252| `identity.entity.name` | The entity's name | 253| `identity.entity.groups.ids` | The IDs of the groups the entity is a member of | 254| `identity.entity.groups.names` | The names of the groups the entity is a member of | 255| `identity.entity.metadata` | Metadata associated with the entity | 256| `identity.entity.metadata.<<metadata key>>` | Metadata associated with the entity for the given key | 257| `identity.entity.aliases.<<mount accessor>>.id` | Entity alias ID for the given mount | 258| `identity.entity.aliases.<<mount accessor>>.name` | Entity alias name for the given mount | 259| `identity.entity.aliases.<<mount accessor>>.metadata` | Metadata associated with the alias for the given mount | 260| `identity.entity.aliases.<<mount accessor>>.metadata.<<metadata key>>` | Metadata associated with the alias for the given mount and metadata key | 261| `time.now` | Current time as integral seconds since the Epoch | 262| `time.now.plus.<<duration>>` | Current time plus a Go-parsable [duration](https://golang.org/pkg/time/#ParseDuration) | | 263| `time.now.minus.<<duration>>` | Current time minus a Go-parsable [duration](https://golang.org/pkg/time/#ParseDuration) | | 264 265### Token Generation 266 267An authenticated client may request a token using the [token generation 268endpoint](api/secret/identity/tokens.html#generate-a-signed-id-token). The token 269will be generated per the requested role's specifications, for the requester's 270entity. It is not possible to generate tokens for an arbitrary entity. 271 272### Verifying Authenticity of ID Tokens Generated by Vault 273 274An identity token may be verified by the client party using the public keys 275published by Vault, or via a Vault-provided introspection endpoint. 276 277Vault will serve standard "[.well-known](https://tools.ietf.org/html/rfc5785)" 278endpoints that allow easy integration with OIDC verification libraries. 279Configuring the libraries will typically involve providing an issuer URL and 280client ID. The library will then handle key requests and can validate the 281signature and claims requirements on tokens. This approach has the advantage of 282only requiring _access_ to Vault, not _authorization_, as the .well-known 283endpoints are unauthenticated. 284 285Alternatively, the token may be sent to Vault for verification via an 286[introspection endpoint](api/secret/identity/tokens.html#introspect-a-signed-id-token). 287The response will indicate whether the token is "active" or not, as well as any 288errors that occurred during validation. Beyond simply allowing the client to 289delegate verification to Vault, using this endpoint incorporates the additional 290check of whether the entity is still active or not, which is something that 291cannot be determined from the token alone. Unlike the .well-known endpoint, accessing the 292introspection endpoint does require a valid Vault token and sufficient 293authorization. 294 295 296### Issuer Considerations 297 298The identity token system has one configurable parameter: issuer. The issuer 299`iss` claim is particularly important for proper validation of the token by 300clients, and special consideration should be given when using Identity Tokens 301with [performance replication](docs/enterprise/replication/index.html). 302Consumers of the token will request public keys from Vault using the issuer URL, 303so it must be network reachable. Furthermore, the returned set of keys will include 304an issuer that must match the request. 305 306By default Vault will set the issuer to the Vault instance's 307[`api_addr`](docs/configuration/index.html#api_addr). This means that tokens 308issued in a given cluster should be validated within that same cluster. 309Alternatively, the [`issuer`](api/secret/identity/tokens.html#issuer) parameter 310may be configured explicitly. This address must point to the identity/oidc path 311for the Vault instance (e.g. 312`https://vault-1.example.com:8200/v1/identity/oidc`) and should be 313reachable by any client trying to validate identity tokens. 314 315 316## API 317 318The Identity secrets engine has a full HTTP API. Please see the 319[Identity secrets engine API](/api/secret/identity/index.html) for more 320details. 321