| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
| <concept id="ldap"> |
| |
| <title>Enabling LDAP Authentication for Impala</title> |
| <prolog> |
| <metadata> |
| <data name="Category" value="Security"/> |
| <data name="Category" value="LDAP"/> |
| <data name="Category" value="Authentication"/> |
| <data name="Category" value="Impala"/> |
| <data name="Category" value="Configuring"/> |
| <data name="Category" value="Starting and Stopping"/> |
| <data name="Category" value="Administrators"/> |
| </metadata> |
| </prolog> |
| |
| <conbody> |
| |
| <!-- Similar discussion under 'Authentication' parent topic. Maybe do some conref'ing or linking upward. --> |
| |
| <p> Authentication is the process of allowing only specified named users to |
| access the server (in this case, the Impala server). This feature is |
| crucial for any production deployment, to prevent misuse, tampering, or |
| excessive load on the server. Impala uses LDAP for authentication, |
| verifying the credentials of each user who connects through |
| <cmdname>impala-shell</cmdname>, Hue, a Business Intelligence tool, JDBC |
| or ODBC application, and so on. </p> |
| |
| <note conref="../shared/impala_common.xml#common/authentication_vs_authorization"/> |
| |
| <p> |
| An alternative form of authentication you can use is Kerberos, described in |
| <xref href="impala_kerberos.xml#kerberos"/>. |
| </p> |
| |
| <p outputclass="toc inpage"/> |
| |
| </conbody> |
| |
| <concept id="ldap_prereqs"> |
| |
| <title>Requirements for Using Impala with LDAP</title> |
| <prolog> |
| <metadata> |
| <data name="Category" value="Requirements"/> |
| <data name="Category" value="Planning"/> |
| </metadata> |
| </prolog> |
| |
| <conbody> |
| |
| <p rev="1.4.0"> |
| Authentication against LDAP servers is available in Impala 1.2.2 and higher. Impala 1.4.0 adds support for |
| secure LDAP authentication through SSL and TLS. |
| </p> |
| |
| <p> |
| The Impala LDAP support lets you use Impala with systems such as Active Directory that use LDAP behind the |
| scenes. |
| </p> |
| </conbody> |
| </concept> |
| |
| <concept id="ldap_client_server"> |
| |
| <title>Client-Server Considerations for LDAP</title> |
| |
| <conbody> |
| |
| <p> |
| Only client->Impala connections can be authenticated by LDAP. |
| </p> |
| |
| <p> You must use the Kerberos authentication mechanism for connections |
| between internal Impala components, such as between the |
| <cmdname>impalad</cmdname>, <cmdname>statestored</cmdname>, and |
| <cmdname>catalogd</cmdname> daemons. See <xref |
| href="impala_kerberos.xml#kerberos" /> on how to set up Kerberos for |
| Impala. </p> |
| </conbody> |
| </concept> |
| |
| <concept id="ldap_config"> |
| |
| <title>Server-Side LDAP Setup</title> |
| |
| <conbody> |
| |
| <p> |
| These requirements apply on the server side when configuring and starting Impala: |
| </p> |
| |
| <p> |
| To enable LDAP authentication, set the following startup options for <cmdname>impalad</cmdname>: |
| </p> |
| |
| <ul> |
| <li> |
| <codeph>--enable_ldap_auth</codeph> enables LDAP-based authentication between the client and Impala. |
| </li> |
| |
| <li rev="1.4.0"> |
| <codeph>--ldap_uri</codeph> sets the URI of the LDAP server to use. Typically, the URI is prefixed with |
| <codeph>ldap://</codeph>. In Impala 1.4.0 and higher, you can specify secure SSL-based LDAP transport by |
| using the prefix <codeph>ldaps://</codeph>. The URI can optionally specify the port, for example: |
| <codeph>ldap://ldap_server.example.com:389</codeph> or |
| <codeph>ldaps://ldap_server.example.com:636</codeph>. (389 and 636 are the default ports for non-SSL and |
| SSL LDAP connections, respectively.) |
| </li> |
| |
| <!-- Some amount of this bullet could be conref'ed. Similar but not identical bullet occurs later under TLS. --> |
| |
| <li rev="1.4.0"> |
| For <codeph>ldaps://</codeph> connections secured by SSL, |
| <codeph>--ldap_ca_certificate="<varname>/path/to/certificate/pem</varname>"</codeph> specifies the |
| location of the certificate in standard <codeph>.PEM</codeph> format. Store this certificate on the local |
| filesystem, in a location that only the <codeph>impala</codeph> user and other trusted users can read. |
| </li> |
| |
| <!-- Per Henry: not for public consumption. |
| <li> |
| If you need to provide a custom SASL configuration, |
| set <codeph>- -ldap_manual_config</codeph> to bypass all the automatic configuration. |
| </li> |
| --> |
| </ul> |
| </conbody> |
| </concept> |
| |
| <concept id="ldap_bind_strings"> |
| |
| <title>Support for Custom Bind Strings</title> |
| |
| <conbody> |
| |
| <p> |
| When Impala connects to LDAP it issues a bind call to the LDAP server to authenticate as the connected |
| user. Impala clients, including the Impala shell, provide the short name of the user to Impala. This is |
| necessary so that Impala can use Sentry for role-based access, which uses short names. |
| </p> |
| |
| <p> |
| However, LDAP servers often require more complex, structured usernames for authentication. Impala supports |
| three ways of transforming the short name (for example, <codeph>'henry'</codeph>) to a more complicated |
| string. If necessary, specify one of the following configuration options |
| when starting the <cmdname>impalad</cmdname> daemon on each DataNode: |
| </p> |
| |
| <ul> |
| <li> |
| <codeph>--ldap_domain</codeph>: Replaces the username with a string |
| <codeph><varname>username</varname>@<varname>ldap_domain</varname></codeph>. |
| </li> |
| |
| <li> |
| <codeph>--ldap_baseDN</codeph>: Replaces the username with a <q>distinguished name</q> (DN) of the form: |
| <codeph>uid=<varname>userid</varname>,ldap_baseDN</codeph>. (This is equivalent to a Hive option). |
| </li> |
| |
| <li> |
| <codeph>--ldap_bind_pattern</codeph>: This is the most general option, and replaces the username with the |
| string <varname>ldap_bind_pattern</varname> where all instances of the string <codeph>#UID</codeph> are |
| replaced with <varname>userid</varname>. For example, an <codeph>ldap_bind_pattern</codeph> of |
| <codeph>"user=#UID,OU=foo,CN=bar"</codeph> with a username of <codeph>henry</codeph> will construct a |
| bind name of <codeph>"user=henry,OU=foo,CN=bar"</codeph>. |
| </li> |
| </ul> |
| |
| <p> |
| These options are mutually exclusive; Impala does not start if more than one of these options is specified. |
| </p> |
| </conbody> |
| </concept> |
| |
| <concept id="ldap_security"> |
| |
| <title>Secure LDAP Connections</title> |
| |
| <conbody> |
| |
| <p> |
| To avoid sending credentials over the wire in cleartext, you must configure a secure connection between |
| both the client and Impala, and between Impala and the LDAP server. The secure connection could use SSL or |
| TLS. |
| </p> |
| |
| <p> |
| <b>Secure LDAP connections through SSL:</b> |
| </p> |
| |
| <p> |
| For SSL-enabled LDAP connections, specify a prefix of <codeph>ldaps://</codeph> instead of |
| <codeph>ldap://</codeph>. Also, the default port for SSL-enabled LDAP connections is 636 instead of 389. |
| </p> |
| |
| <p rev="1.4.0"> |
| <b>Secure LDAP connections through TLS:</b> |
| </p> |
| |
| <p> |
| <xref href="http://en.wikipedia.org/wiki/Transport_Layer_Security" scope="external" format="html">TLS</xref>, |
| the successor to the SSL protocol, is supported by most modern LDAP servers. Unlike SSL connections, TLS |
| connections can be made on the same server port as non-TLS connections. To secure all connections using |
| TLS, specify the following flags as startup options to the <cmdname>impalad</cmdname> daemon: |
| </p> |
| |
| <ul> |
| <li> |
| <codeph>--ldap_tls</codeph> tells Impala to start a TLS connection to the LDAP server, and to fail |
| authentication if it cannot be done. |
| </li> |
| |
| <li rev="1.4.0"> |
| <codeph>--ldap_ca_certificate="<varname>/path/to/certificate/pem</varname>"</codeph> specifies the |
| location of the certificate in standard <codeph>.PEM</codeph> format. Store this certificate on the local |
| filesystem, in a location that only the <codeph>impala</codeph> user and other trusted users can read. |
| </li> |
| </ul> |
| </conbody> |
| </concept> |
| |
| <concept id="ldap_impala_shell"> |
| |
| <title>LDAP Authentication for impala-shell Interpreter</title> |
| |
| <conbody> |
| |
| <p> |
| To connect to Impala using LDAP authentication, you specify command-line options to the |
| <cmdname>impala-shell</cmdname> command interpreter and enter the password when prompted: |
| </p> |
| |
| <ul> |
| <li> |
| <codeph>-l</codeph> enables LDAP authentication. |
| </li> |
| |
| <li> |
| <codeph>-u</codeph> sets the user. Per Active Directory, the user is the short username, not the full |
| LDAP distinguished name. If your LDAP settings include a search base, use the |
| <codeph>--ldap_bind_pattern</codeph> on the <cmdname>impalad</cmdname> daemon to translate the short user |
| name from <cmdname>impala-shell</cmdname> automatically to the fully qualified name. |
| <!-- |
| include that as part of the |
| username, for example <codeph>username@example.com</codeph>. |
| --> |
| </li> |
| |
| <li> |
| <cmdname>impala-shell</cmdname> automatically prompts for the password. |
| </li> |
| </ul> |
| |
| <p> |
| For the full list of available <cmdname>impala-shell</cmdname> options, see |
| <xref href="impala_shell_options.xml#shell_options"/>. |
| </p> |
| |
| <p> |
| <b>LDAP authentication for JDBC applications:</b> See <xref href="impala_jdbc.xml#impala_jdbc"/> for the |
| format to use with the JDBC connection string for servers using LDAP authentication. |
| </p> |
| </conbody> |
| </concept> |
| <concept id="ldap_impala_hue"> |
| <title>Enabling LDAP for Impala in Hue</title> |
| <prolog> |
| <metadata> |
| <data name="Category" value="Hue"/> |
| </metadata> |
| </prolog> |
| <conbody> |
| <section id="ldap_impala_hue_cmdline"> |
| <title>Enabling LDAP for Impala in Hue Using the Command Line</title> |
| <p>LDAP authentication for the Impala app in Hue can be enabled by |
| setting the following properties under the <codeph>[impala]</codeph> |
| section in <codeph>hue.ini</codeph>. <table id="ldap_impala_hue_configs"> |
| <tgroup cols="2"> |
| <colspec colname="1" colwidth="1*" /> |
| <colspec colname="2" colwidth="2*" /> |
| <tbody> |
| <row> |
| <entry><codeph>auth_username</codeph></entry> |
| <entry>LDAP username of Hue user to be authenticated.</entry> |
| </row> |
| <row> |
| <entry><codeph>auth_password</codeph></entry> |
| <entry> |
| <p>LDAP password of Hue user to be authenticated.</p> |
| </entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table>These login details are only used by Impala to authenticate to |
| LDAP. The Impala service trusts Hue to have already validated the user |
| being impersonated, rather than simply passing on the credentials.</p> |
| </section> |
| </conbody> |
| </concept> |
| |
| <concept id="ldap_delegation"> |
| <title>Enabling Impala Delegation for LDAP Users</title> |
| <conbody> |
| <p> |
| See <xref href="impala_delegation.xml#delegation"/> for details about the delegation feature |
| that lets certain users submit queries using the credentials of other users. |
| </p> |
| </conbody> |
| </concept> |
| |
| <concept id="ldap_restrictions"> |
| |
| <title>LDAP Restrictions for Impala</title> |
| |
| <conbody> |
| |
| <p> |
| The LDAP support is preliminary. It currently has only been tested against Active Directory. |
| </p> |
| </conbody> |
| </concept> |
| </concept> |