docs: Added identity concepts

website/source/docs/vault-enterprise/identity/index.html.md

@@ -0,0 +1,85 @@
+---
+layout: "docs"
+page_title: "Vault Enterprise Identity"
+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 Personas
+
+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 `Personas`. In essence, each entity
+is made up of zero or more personas.
+
+### 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
+pulled in and pulled out of Vault, and in some sense Vault will serve as a
+_cache_ of identities and not as the _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). 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,
+and 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 Personas
+
+Vault supports multiple authentication backends and also allows enabling same
+authentication backend on different mounts. The persona name of the user with
+each identity provider will be unique within the provider. But Vault also needs
+to uniquely distinguish between conflicting persona names across different
+mounts of these identity providers. Hence the persona name, in combination with
+the authentication backend mount's accessor serve as the unique identifier of a
+persona.
+
+### 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 a persona against the login that was
+successful.
+
+Note that, 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.
+
+### API
+
+Vault identity can be managed entirely over the HTTP API. Please see [Identity
+API](/api/secrets/identity/index.html) for more details.

website/source/layouts/docs.erb

@@ -372,6 +372,9 @@
           <li<%= sidebar_current("docs-vault-enterprise-ui") %>>
             <a href="/docs/vault-enterprise/ui/index.html">UI (Web Interface)</a>
           </li>
+          <li<%= sidebar_current("docs-vault-enterprise-identity") %>>
+            <a href="/docs/vault-enterprise/identity/index.html">Identity</a>
+          </li>
           <li <%= sidebar_current("docs-vault-enterprise-mfa")%> >
             <a href="/docs/vault-enterprise/mfa/index.html">MFA</a>
             <ul class="nav">