Shield Docs: Adding information about how to run as another user.

Original commit: elastic/x-pack-elasticsearch@7cc8fb28ad

shield/docs/public/configuring-rbac.asciidoc

@@ -151,3 +151,5 @@ include::granting-alias-privileges.asciidoc[]
 include::mapping-roles.asciidoc[]
 
 include::setting-up-field-and-document-level-security.asciidoc[]
+
+include::submitting-requests-for-other-users.asciidoc[]

shield/docs/public/reference.asciidoc

@@ -44,6 +44,16 @@ alias name
 `write`:: Privilege to index, update, delete, delete by query and bulk operations on documents, in addition to delete
 and put indexed scripts
 
+[float]
+==== Run As
+
+The `run_as` permission enables an authenticated user to submit requests on behalf of another 
+user. The value can be a user name or a comma-separated list of user names. (You can also specify 
+users as an array of strings or a YAML sequence.) For more information, 
+see <<submitting-requests-for-other-users, Submitting Requests on Behalf of Other Users>>.
+
+[horizontal]
+
 [[ref-actions-list]]
 
 [float]

shield/docs/public/setting-up-authentication.asciidoc

@@ -4,6 +4,10 @@
 Authentication identifies an individual. To gain access to restricted resources, a user must prove their identity, via
 passwords, credentials, or some other means (typically referred to as authentication tokens).
 
+NOTE: In Shield, an authenticated user can submit requests on behalf of other another user if they 
+have the appropriate `run_as` permission. For more information, see 
+<<submitting-requests-for-other-users, Submitting Requests on Behalf of Other Users>>.
+
 A _realm_ is an authentication mechanism, which Shield uses to resolve and authenticate users and their roles. Shield 
 currently provides four realm types:
 

shield/docs/public/submitting-requests-for-other-users.asciidoc

@@ -0,0 +1,31 @@
+[[submitting-requests-for-other-users]]
+=== Submitting Requests on Behalf of Other Users
+
+Shield supports a permission that enables an authenticated user to submit requests on behalf
+of other users. If your application already authenticates users, you can use this
+_run as_ mechanism to restrict data access according to Shield permissions without having
+to re-authenticate each user through Shield. 
+
+To run as another user, you must be able to retrieve the user from the realm you use
+to authenticate. The `esusers` realm supports this out of the box. To use `run_as` with 
+an LDAP realm, it must be configured to enable user search. For more information, 
+see <<ldap-user-search, Configuring an LDAP Realm with User Search>>.
+
+To submit requests on behalf of other users, you need to have the `run_as`
+permission. For example, the following `run_as_role` grants permision to submit request on
+behalf of `jacknich` or `redeniro`: 
+
+[source,yaml]
+---------------------------------------------------
+run_as_role: 
+    run_as: jacknich, rdeniro
+---------------------------------------------------
+
+For information about assigning roles, see <<mapping-roles, Mapping Users and Groups to Roles>>.
+
+To submit a request as another user, you specify the user in the request header. For example:
+
+[source,console]
+---------------------------------------------------
+curl -H "es-shield-runas-user: jacknich"  -u es_admin -XGET 'http://localhost:9200/'
+---------------------------------------------------