Bridget's auth doc
Project: http://git-wip-us.apache.org/repos/asf/drill/repo Commit: http://git-wip-us.apache.org/repos/asf/drill/commit/3ababd8c Tree: http://git-wip-us.apache.org/repos/asf/drill/tree/3ababd8c Diff: http://git-wip-us.apache.org/repos/asf/drill/diff/3ababd8c Branch: refs/heads/gh-pages Commit: 3ababd8c408c683e27ec6318319559926094202e Parents: bca4701 Author: Kristine Hahn <kh...@maprtech.com> Authored: Thu May 7 11:10:22 2015 -0700 Committer: Kristine Hahn <kh...@maprtech.com> Committed: Thu May 7 11:10:22 2015 -0700 ---------------------------------------------------------------------- _data/docs.json | 73 +++++++-- .../075-configuring-user-authentication.md | 157 +++++++++++++++++++ _docs/img/UserAuthProcess.PNG | Bin 0 -> 30800 bytes _docs/img/UserAuth_ODBC_Driver.png | Bin 0 -> 83049 bytes 4 files changed, 219 insertions(+), 11 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/drill/blob/3ababd8c/_data/docs.json ---------------------------------------------------------------------- diff --git a/_data/docs.json b/_data/docs.json index 4aca3af..91d3fe5 100644 --- a/_data/docs.json +++ b/_data/docs.json @@ -783,8 +783,8 @@ "next_title": "Configuration Options Introduction", "next_url": "/docs/configuration-options-introduction/", "parent": "Configure Drill", - "previous_title": "Configuring User Impersonation", - "previous_url": "/docs/configuring-user-impersonation/", + "previous_title": "Configuring User Authentication", + "previous_url": "/docs/configuring-user-authentication/", "relative_path": "_docs/configure-drill/080-configuration-options.md", "title": "Configuration Options", "url": "/docs/configuration-options/" @@ -936,8 +936,8 @@ } ], "children": [], - "next_title": "Configuration Options", - "next_url": "/docs/configuration-options/", + "next_title": "Configuring User Authentication", + "next_url": "/docs/configuring-user-authentication/", "parent": "Configure Drill", "previous_title": "Configuring Resources for a Shared Drillbit", "previous_url": "/docs/configuring-resources-for-a-shared-drillbit/", @@ -952,6 +952,23 @@ "url": "/docs/configure-drill/" } ], + "children": [], + "next_title": "Configuration Options", + "next_url": "/docs/configuration-options/", + "parent": "Configure Drill", + "previous_title": "Configuring User Impersonation", + "previous_url": "/docs/configuring-user-impersonation/", + "relative_path": "_docs/configure-drill/075-configuring-user-authentication.md", + "title": "Configuring User Authentication", + "url": "/docs/configuring-user-authentication/" + }, + { + "breadcrumbs": [ + { + "title": "Configure Drill", + "url": "/docs/configure-drill/" + } + ], "children": [ { "breadcrumbs": [ @@ -1041,8 +1058,8 @@ "next_title": "Configuration Options Introduction", "next_url": "/docs/configuration-options-introduction/", "parent": "Configure Drill", - "previous_title": "Configuring User Impersonation", - "previous_url": "/docs/configuring-user-impersonation/", + "previous_title": "Configuring User Authentication", + "previous_url": "/docs/configuring-user-authentication/", "relative_path": "_docs/configure-drill/080-configuration-options.md", "title": "Configuration Options", "url": "/docs/configuration-options/" @@ -1209,7 +1226,7 @@ "title": "Configuring Resources for a Shared Drillbit", "url": "/docs/configuring-resources-for-a-shared-drillbit/" }, - "Configuring User Impersonation": { + "Configuring User Authentication": { "breadcrumbs": [ { "title": "Configure Drill", @@ -1220,6 +1237,23 @@ "next_title": "Configuration Options", "next_url": "/docs/configuration-options/", "parent": "Configure Drill", + "previous_title": "Configuring User Impersonation", + "previous_url": "/docs/configuring-user-impersonation/", + "relative_path": "_docs/configure-drill/075-configuring-user-authentication.md", + "title": "Configuring User Authentication", + "url": "/docs/configuring-user-authentication/" + }, + "Configuring User Impersonation": { + "breadcrumbs": [ + { + "title": "Configure Drill", + "url": "/docs/configure-drill/" + } + ], + "children": [], + "next_title": "Configuring User Authentication", + "next_url": "/docs/configuring-user-authentication/", + "parent": "Configure Drill", "previous_title": "Configuring Resources for a Shared Drillbit", "previous_url": "/docs/configuring-resources-for-a-shared-drillbit/", "relative_path": "_docs/configure-drill/070-configuring-user-impersonation.md", @@ -9388,8 +9422,8 @@ } ], "children": [], - "next_title": "Configuration Options", - "next_url": "/docs/configuration-options/", + "next_title": "Configuring User Authentication", + "next_url": "/docs/configuring-user-authentication/", "parent": "Configure Drill", "previous_title": "Configuring Resources for a Shared Drillbit", "previous_url": "/docs/configuring-resources-for-a-shared-drillbit/", @@ -9404,6 +9438,23 @@ "url": "/docs/configure-drill/" } ], + "children": [], + "next_title": "Configuration Options", + "next_url": "/docs/configuration-options/", + "parent": "Configure Drill", + "previous_title": "Configuring User Impersonation", + "previous_url": "/docs/configuring-user-impersonation/", + "relative_path": "_docs/configure-drill/075-configuring-user-authentication.md", + "title": "Configuring User Authentication", + "url": "/docs/configuring-user-authentication/" + }, + { + "breadcrumbs": [ + { + "title": "Configure Drill", + "url": "/docs/configure-drill/" + } + ], "children": [ { "breadcrumbs": [ @@ -9493,8 +9544,8 @@ "next_title": "Configuration Options Introduction", "next_url": "/docs/configuration-options-introduction/", "parent": "Configure Drill", - "previous_title": "Configuring User Impersonation", - "previous_url": "/docs/configuring-user-impersonation/", + "previous_title": "Configuring User Authentication", + "previous_url": "/docs/configuring-user-authentication/", "relative_path": "_docs/configure-drill/080-configuration-options.md", "title": "Configuration Options", "url": "/docs/configuration-options/" http://git-wip-us.apache.org/repos/asf/drill/blob/3ababd8c/_docs/configure-drill/075-configuring-user-authentication.md ---------------------------------------------------------------------- diff --git a/_docs/configure-drill/075-configuring-user-authentication.md b/_docs/configure-drill/075-configuring-user-authentication.md new file mode 100755 index 0000000..841d3e5 --- /dev/null +++ b/_docs/configure-drill/075-configuring-user-authentication.md @@ -0,0 +1,157 @@ +--- +title: "Configuring User Authentication" +parent: "Configure Drill" +--- +Authentication is the process of proving a userâs identity to access a process running on a system. Drill currently supports username/password based authentication through the use of the Linux Pluggable Authentication Module (PAM). The authentication option is available through JDBC and ODBC interfaces. Linux PAM provides authentication modules that interface with any installed PAM authentication entity, such as the local operating system password file (passwd or login) or LDAP. + +If user impersonation is enabled, Drill executes the client requests as the authenticated user. Otherwise, Drill executes client requests as the user that started the Drillbit process. You can enable both authorization and impersonation to improve Drill security. See [Configuring User Impersonation]({{site.baseurl}}/docs/configuring-user-impersonation/). + +When using PAM for authentication, each user that has permission to run Drill must exist in the list of users that resides on each Drill node in the cluster. The username (including uid) and password for each user must be identical across all of the Drill nodes. + +## User Authentication Process + +When user authentication is configured, each user that accesses the Drillbit process through a client, such as SQLLine, must provide their username and password for access. + +When launching SQLLine, a user must include the `ân` and `âp` parameters with their username and password in the SQLLine argument: + `sqlline âu jdbc:drill:zk=10.10.11.112:5181 ân bob âp bobdrill` + + +When a user connects to Drill from a BI tool, such as Tableau, the MapR Drill ODBC driver prompts the user for their username and password: + + + +The client passes the username and password to a Drillbit, which then passes the credentials to PAM. If PAM can verify that the user is authorized to access Drill, the user can connect to the Drillbit process from the client and issue queries against the file system or other storage plugins, such as Hive or HBase. However, if PAM cannot verify that the user is authorized to access Drill, the client returns an error. + +The following image illustrates the user authentication process in Drill: + + + +### Installing and Configuring PAM + +Install and configure the provided Drill PAM. Drill only supports the PAM provided here. + +Complete the following steps to install and configure PAM for Drill: + +1. Download the `tar.gz` file for the Linux platform: + [http://sourceforge.net/projects/jpam/files/jpam/jpam-1.1/](http://sourceforge.net/projects/jpam/files/jpam/jpam-1.1/) +2. Untar the file, and copy the `libjpam.so` file into a directory. + Example:` /opt/pam/` +3. Run the following command, and include the directory where you put the `libjpam.so` file: + `export DRILLBIT_JAVA_OPTS=" -Djava.library.path=<directory>"` + Example: `export DRILLBIT_JAVA_OPTS=" -Djava.library.path=/opt/pam/"` +4. Add the following block to `drill.exec` in the `drill-override.conf` file located in `<DRILLINSTALL_HOME>/conf/`: + + drill.exec { + security.user.auth { + enabled: true, + packages += "org.apache.drill.exec.rpc.user.security", + impl: "pam", + pam_profiles: [ "sudo", "login" ] + } + } + +5. (Optional) To add or remove different PAM profiles, add or delete the profile names in the `âpam_profilesâ` array. +6. Restart the Drillbit process on each Drill node. + * In a MapR cluster, run the following command: + + maprcli node services -name drill-bits -action restart -nodes <hostname> -f + * In a non-MapR environment, run the following command: + + <DRILLINSTALL_HOME>/bin/drillbit.sh restart + +### Implementing and Configuring a Custom Authenticator + +Administrators can use the template provided here to develop and implement a custom username/password based authenticator. + +Complete the following steps to build and implement a custom authenticator: + +1. Build the following Java file into a JAR file: + + MyCustomDrillUserAuthenticatorImpl.java + + package myorg.dept.drill.security; + + import org.apache.drill.common.config.DrillConfig; + import org.apache.drill.exec.exception.DrillbitStartupException; + + import java.io.IOException; + + /* + * Implement {@link org.apache.drill.exec.rpc.user.security.UserAuthenticator} for illustraing how to develop a custom authenticator and use it in Drill + */ + @UserAuthenticatorTemplate(type = âmyCustomAuthenticatorTypeâ) + public class MyCustomDrillUserAuthenticatorImpl implements UserAuthenticator { + + public static final String TEST_USER_1 = "testUser1"; + public static final String TEST_USER_2 = "testUser2"; + public static final String TEST_USER_1_PASSWORD = "testUser1Password"; + public static final String TEST_USER_2_PASSWORD = "testUser2Password"; + + /** + * Setup for authenticating user credentials. + */ + @Override + public void setup(DrillConfig drillConfig) throws DrillbitStartupException { + // If the authenticator has any setup such as making sure authenticator provider servers are up and running or + // needed libraries are available, it should be added here. + } + + /** + * Authenticate the given <i>user</i> and <i>password</i> combination. + * + * @param userName + * @param password + * @throws UserAuthenticationException if authentication fails for given user and password. + */ + @Override + public void authenticate(String userName, String password) throws UserAuthenticationException { + + if (!(TEST_USER_1.equals(user) && TEST_USER_1_PASSWORD.equals(password)) && + !(TEST_USER_2.equals(user) && TEST_USER_2_PASSWORD.equals(password))) { + throw new UserAuthenticationException(âcustom failure message if the admin wants to show it to userâ); + } + } + + /** + * Close the authenticator. Used to release resources. Ex. LDAP authenticator opens connections to LDAP server, + * such connections resources are released in a safe manner as part of close. + * + * @throws IOException + */ + @Override + public void close() throws IOException { + // Any clean up such as releasing files/network resources should be done here + } + } + + +2. Add the JAR file that you built to the following directory on each Drill node: + ` <DRILLINSTALL_HOME>/jars` +3. Add the following block to the `drill.exec` section in the `drill-override.conf` file located in `<DRILLINSTALL_HOME>/conf/`: + + drill.exec { + security.user.auth { + enabled: true, + packages += "myorg.dept.drill.security", + impl: "myCustomAuthenticatorType" + } + } +4. Restart the Drillbit process on each Drill node. + * In a MapR cluster, run the following command: + + maprcli node services -name drill-bits -action restart -nodes <hostname> -f + * In a non-MapR environment, run the following command: + + <DRILLINSTALL_HOME>/bin/drillbit.sh restart + + + + + + + + + + + + http://git-wip-us.apache.org/repos/asf/drill/blob/3ababd8c/_docs/img/UserAuthProcess.PNG ---------------------------------------------------------------------- diff --git a/_docs/img/UserAuthProcess.PNG b/_docs/img/UserAuthProcess.PNG new file mode 100755 index 0000000..4d9f626 Binary files /dev/null and b/_docs/img/UserAuthProcess.PNG differ http://git-wip-us.apache.org/repos/asf/drill/blob/3ababd8c/_docs/img/UserAuth_ODBC_Driver.png ---------------------------------------------------------------------- diff --git a/_docs/img/UserAuth_ODBC_Driver.png b/_docs/img/UserAuth_ODBC_Driver.png new file mode 100755 index 0000000..811652e Binary files /dev/null and b/_docs/img/UserAuth_ODBC_Driver.png differ
