drill git commit: Sudheesh's inbound impersonation feature doc: DRILL-4281

[br...@apache.org]

Repository: drill
Updated Branches:
  refs/heads/gh-pages e49d7577f -> e8715483e


Sudheesh's inbound impersonation feature doc: DRILL-4281


Project: http://git-wip-us.apache.org/repos/asf/drill/repo
Commit: http://git-wip-us.apache.org/repos/asf/drill/commit/e8715483
Tree: http://git-wip-us.apache.org/repos/asf/drill/tree/e8715483
Diff: http://git-wip-us.apache.org/repos/asf/drill/diff/e8715483

Branch: refs/heads/gh-pages
Commit: e8715483ef710ca655e3d867784d4431943a5910
Parents: e49d757
Author: Bridget Bevens <bb...@maprtech.com>
Authored: Tue Mar 15 16:24:48 2016 -0700
Committer: Bridget Bevens <bb...@maprtech.com>
Committed: Tue Mar 15 16:24:48 2016 -0700

----------------------------------------------------------------------
 .../071-configure-inbound-impersonation.md      | 50 ++++++++++++++++++++
 1 file changed, 50 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/drill/blob/e8715483/_docs/configure-drill/071-configure-inbound-impersonation.md
----------------------------------------------------------------------
diff --git a/_docs/configure-drill/071-configure-inbound-impersonation.md b/_docs/configure-drill/071-configure-inbound-impersonation.md
new file mode 100644
index 0000000..8a581ed
--- /dev/null
+++ b/_docs/configure-drill/071-configure-inbound-impersonation.md
@@ -0,0 +1,50 @@
+---
+title: "Configuring Inbound Impersonation"
+date:  
+parent: "Configure Drill"
+---  
+
+Drill supports [user impersonation]({{site.baseurl}}/docs/configuring-user-impersonation/)  where queries run as the user that created a connection. However, this user is not necessarily the end user who submits the queries. For example, in a classic three-tier architecture, the end user interacts with Tableau Desktop, which communicates with a Tableau Server, which in turn communicates with a Drill cluster. In this scenario, a proxy user creates a connection, and the queries are submitted to Drill by the proxy user on behalf of the end user, and not by the end user directly. In this particular case, the query runs as the end user.  
+
+![The picture shows how identity is propagated through various layers (with authentication enabled). The flow on the left is what Drill currently supports, and the flow on the right is the proposed change. t:euser is a property on the connection (u is username, p is password, t is impersonation_target).](http://i.imgur.com/R3b4fi0.png)  
+
+As of Drill 1.6, an administrator can define inbound impersonation policies to impersonate the end user. Impersonating the end user is a natural extension of Drill’s impersonation model and accounts for one more [user hop in the chain]({{site.baseurl}}/docs/configuring-user-impersonation/#chained-impersonation). This additional hop requires authorization, meaning that the proxy user needs to be authorized to submit queries on behalf of the specified end user. Otherwise, any user can impersonate another user. Then, the query runs as the end user, and data authorization is based on this user’s access permissions. Note that without [authentication]({{site.baseurl}}/docs/configuring-user-authentication/) enabled in both communication channels, a user can impersonate any other user.
+
+Drill trusts proxy users to provide the correct end user identity information. Drill does not authenticate the end user. The proxy user (application) is responsible for end user authentication, which is usually enabled.
+
+##Configuring Inbound Impersonation
+You must be an administrator to configure inbound impersonation. You can define administrative users through the `security.admin.user_groups` and `security.admin.users` options. See [Configuration Options]({{site.baseurl}}/docs/configuration-options-introduction/#system-options). 
+
+[User impersonation]({{site.baseurl}}/docs/configuring-user-impersonation/) must be enabled before you can configure inbound impersonation.
+
+Complete the following steps to enable inbound impersonation:  
+
+1. In `drill-override.conf`, set user impersonation to true:
+  
+              {
+              drill.exec.impersonation.enabled: true,
+              ...
+              }
+
+2. Define inbound impersonation policies. For example, the following ALTER SYSTEM statement authorizes:
+       * `puser1` to impersonate any user (*)
+       * `puser2` to impersonate `euser1` and all users in `egroup2` 
+       * all users in `pgroup3` to impersonate all users in `egroup3`  
+      
+              ALTER SYSTEM SET `exec.impersonation.inbound_policies`=‘[
+              { proxy_principals : { users: [“puser1”] },
+                target_principals: { users: [“*”] } },
+              { proxy_principals : { users: [“puser2”] }, 
+                target_principals: { users: [“euser1”], groups :  [“egroup2”] } },
+              { proxy_principals : { groups: [“pgroup3”] },
+                target_principals: { groups: [“egroup3”] } } ]’;  
+Policy format:
+
+              { proxy_principals : { users : [“...”], groups : [“...”] },
+                target_principals: { users : [“...”], groups : [“...”] } }
+
+3. Ensure that the proxy user (application) passes the username of the impersonation target user to Drill when creating a connection through the `impersonation_target` connection property. For example, through sqlline:  
+
+        bin/sqlline –u “jdbc:drill:schema=dfs;zk=myclusterzk;impersonation_target=euser1” -n puser1 -p ppass1  
+
+In this example, `puser1` is the user submitting the queries. This user is authenticated. Since this user is authorized to impersonate any user, queries through the established connection are run as `euser1`.