From 019b63e5fb3117590bf1ba437241e590f8e43866 Mon Sep 17 00:00:00 2001
From: debadair <deb.adair@elasticsearch.com>
Date: Mon, 14 Sep 2015 12:30:00 -0700
Subject: [PATCH] Shield Docs: Adding information about how to run as another
 user.

Original commit: elastic/x-pack-elasticsearch@7cc8fb28adb63528993dbb9e2c3e925f9ae3a6b0
---
 shield/docs/public/configuring-rbac.asciidoc  |  4 ++-
 shield/docs/public/reference.asciidoc         | 10 ++++++
 .../public/setting-up-authentication.asciidoc |  4 +++
 ...bmitting-requests-for-other-users.asciidoc | 31 +++++++++++++++++++
 4 files changed, 48 insertions(+), 1 deletion(-)
 create mode 100644 shield/docs/public/submitting-requests-for-other-users.asciidoc

diff --git a/shield/docs/public/configuring-rbac.asciidoc b/shield/docs/public/configuring-rbac.asciidoc
index 0377a53fc9d..3991afc6941 100644
--- a/shield/docs/public/configuring-rbac.asciidoc
+++ b/shield/docs/public/configuring-rbac.asciidoc
@@ -150,4 +150,6 @@ include::granting-alias-privileges.asciidoc[]
 
 include::mapping-roles.asciidoc[]
 
-include::setting-up-field-and-document-level-security.asciidoc[]
\ No newline at end of file
+include::setting-up-field-and-document-level-security.asciidoc[]
+
+include::submitting-requests-for-other-users.asciidoc[]
\ No newline at end of file
diff --git a/shield/docs/public/reference.asciidoc b/shield/docs/public/reference.asciidoc
index 300d55cca4b..22e3c849ec6 100644
--- a/shield/docs/public/reference.asciidoc
+++ b/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]
diff --git a/shield/docs/public/setting-up-authentication.asciidoc b/shield/docs/public/setting-up-authentication.asciidoc
index a35d38fe709..ac29733f2df 100644
--- a/shield/docs/public/setting-up-authentication.asciidoc
+++ b/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:
 
diff --git a/shield/docs/public/submitting-requests-for-other-users.asciidoc b/shield/docs/public/submitting-requests-for-other-users.asciidoc
new file mode 100644
index 00000000000..1b3eda8922e
--- /dev/null
+++ b/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/'
+---------------------------------------------------
\ No newline at end of file