diff --git a/website/source/docs/enterprise/identity/index.html.md b/website/source/docs/enterprise/identity/index.html.md deleted file mode 100644 index acfe1a5605b6..000000000000 --- a/website/source/docs/enterprise/identity/index.html.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -layout: "docs" -page_title: "Identity - Vault Enterprise" -sidebar_current: "docs-vault-enterprise-identity" -description: |- - Vault Enterprise has the foundations of the identity management system. ---- - -# Vault Enterprise Identity - -In version 0.8, Vault introduced the foundations of identity management system. -The goal of identity in Vault is to associate a notion of caller identity to -the tokens used in Vault. - -## Concepts - -### Entities and Aliases - -Each user will have multiple accounts with various identity providers. Users -can now 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. - -### 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. - -Its 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. - -### 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. - -### 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 -have an associated identity information. Logging in using the authentication -backends is the only way to create tokens that have a valid entity identifiers. - -### Identity Auditing - -If the token used to make API calls have an associated entity identifier, it -will be audit logged as well. This leaves a trail of actions performed by -specific users. - -### Identity Groups - -In version 0.9, 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 is 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; along with the policies on the entity itself, policies that are inherited -due to group memberships are also granted. - -### 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. 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 -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. - -### API - -Vault identity can be managed entirely over the HTTP API. Please see [Identity -API](/api/secret/identity/index.html) for more details. diff --git a/website/source/docs/secrets/identity/index.html.md b/website/source/docs/secrets/identity/index.html.md index 7671ff42e587..bcbc852c345d 100644 --- a/website/source/docs/secrets/identity/index.html.md +++ b/website/source/docs/secrets/identity/index.html.md @@ -34,6 +34,107 @@ controlling the access of tokens that are already issued. This secrets engine will be mounted by default. This secrets engine cannot be disabled or moved. +## Concepts + +### Entities and Aliases + +Each user will have multiple accounts with various identity providers. Users +can now 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. + +### 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. + +Its 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. + +### 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. + +### 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 +have an associated identity information. Logging in using the authentication +backends is the only way to create tokens that have a valid entity identifiers. + +### Identity Auditing + +If the token used to make API calls have an associated entity identifier, it +will be audit logged as well. This leaves a trail of actions performed by +specific users. + +### Identity Groups + +In version 0.9, 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 is 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; along with the policies on the entity itself, policies that are inherited +due to group memberships are also granted. + +### 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. 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 +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. + + + ## API The Identity secrets engine has a full HTTP API. Please see the diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 756d78e7bb8d..a3b6beb938ae 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -574,9 +574,6 @@ > UI (Web Interface) - > - Identity - > Control Groups