docs/topics/impala_ldap.xml - impala - Git at Google

 <?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>

     <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 outputclass="toc inpage"/>

     <p>
       An alternative form of authentication you can use is Kerberos, described in
       <xref href="impala_kerberos.xml#kerberos"/>.
     </p>

   </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>Consideration for Connections Between Impala Components</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>Enabling LDAP in Command Line Interface</title>

     <conbody>

       <p>
         To enable LDAP authentication, start the <cmdname>impalad</cmdname> with the following
         startup options for:
       </p>

       <dl>
         <dlentry>

           <dt>
             <codeph>--enable_ldap_auth</codeph>
           </dt>

           <dd>
             <p>
               Enables LDAP-based authentication between the client and Impala.
             </p>
           </dd>

         </dlentry>

         <dlentry>

           <dt>
             <codeph>--ldap_uri</codeph>
           </dt>

           <dd>
             <p>
               Sets the URI of the LDAP server to use. Typically, the URI is prefixed with
               <codeph>ldap://</codeph>. 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.)
             </p>
           </dd>

         </dlentry>

         <dlentry>

           <dt>
             <codeph>--ldap_search_bind_authentication</codeph>
           </dt>

           <dd>
             <p>
               Allows to switch between search and simple bind user lookup
               methods when authenticating, the default value is <codeph>false
               </codeph> which is simple bind.
             </p>
           </dd>

         </dlentry>
       </dl>

     </conbody>

   </concept>

   <concept id="ldap_bind_user">

     <title>Bind User Credentials</title>

     <conbody>

       <p>
         The bind user is used to run the user/group searches, the credentials
         can be configured with the following flags:
       </p>

       <dl>
         <dlentry>

           <dt>
             <codeph>--ldap_allow_anonymous_binds</codeph>
           </dt>

           <dd>
             <p>
               When true, LDAP authentication with a blank password (an
               'anonymous bind') is allowed by Impala. The default value is
               <codeph>false</codeph>.
             </p>
           </dd>

         </dlentry>

         <dlentry>

           <dt>
             <codeph>--ldap_bind_dn</codeph>
           </dt>

           <dd>
             <p>
               Distinguished name of the user to bind as when doing user or group
               searches. Only required if user or group filters are being used
               and the LDAP server is not configured to allow anonymous searches.
             </p>
           </dd>

         </dlentry>

         <dlentry>

           <dt>
             <codeph>--ldap_bind_password_cmd</codeph>
           </dt>

           <dd>
             <p>
               A Unix command whose output returns the password to use with
               <codeph>--ldap_bind_dn</codeph>. The output of the command will
               be truncated to 1024 bytes and trimmed of trailing whitespace.
             </p>
           </dd>

         </dlentry>
       </dl>

     </conbody>

   </concept>

   <concept id="ldap_simple_bind">

     <title>Simple Bind User Authentication</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 Ranger 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.
       </p>

       <note>
         The <codeph>--ldap_domain</codeph>, <codeph>--ldap_baseDN</codeph> and
         <codeph>--ldap_bind_pattern</codeph> options are mutually exclusive,
         and Impala does not start if more than one of these options are
         specified.
       </note>

       <dl>
         <dlentry>

           <dt>
             <codeph>--ldap_domain</codeph>
           </dt>

           <dd>
             <p>
               Replaces the username with a string
               <codeph><varname>username</varname>@<varname>ldap_domain</varname></codeph>.
             </p>
           </dd>

         </dlentry>

         <dlentry>

           <dt>
             <codeph>--ldap_baseDN</codeph>
           </dt>

           <dd>
             <p>
               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).
             </p>
           </dd>

         </dlentry>

         <dlentry>

           <dt>
             <codeph>--ldap_bind_pattern</codeph>
           </dt>

           <dd>
             <p>
               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>.
             </p>
           </dd>

         </dlentry>

         <dlentry>

           <dt>
             <codeph>--ldap_user_filter</codeph>
           </dt>

           <dd>
             <p>
               A comma separated list of usernames. If specified, users must be
               on this list for authentication to succeed
             </p>
           </dd>

         </dlentry>

         <dlentry>

           <dt>
             <codeph>--ldap_group_filter</codeph>
           </dt>

           <dd>
             <p>
               If specified, users must belong to one of these groups for
               authentication to succeed.
             </p>
           </dd>

         </dlentry>

         <dlentry>

           <dt>
             <codeph>--ldap_group_dn_pattern</codeph>
           </dt>

           <dd>
             <p>
               Colon separated list of patterns for the 'distinguished name' use
               to search for groups in the directory. Each pattern may contain a
               '%s' which will be substituted with each group name from
               <codeph>--ldap_group_filter</codeph> when doing group searches.
             </p>
           </dd>

         </dlentry>

         <dlentry>

           <dt>
             <codeph>--ldap_group_membership_key</codeph>
           </dt>

           <dd>
             <p>
               The LDAP attribute on group entries that indicates its members.
             </p>
           </dd>

         </dlentry>

         <dlentry>

           <dt>
             <codeph>--ldap_group_class_key</codeph>
           </dt>

           <dd>
             <p>
               The LDAP objectClass each of the groups in
               <codeph>--ldap_group_filter</codeph> implements in LDAP.
             </p>
           </dd>

         </dlentry>
       </dl>

     </conbody>

   </concept>

   <concept id="ldap_search_bind">

     <title>Search Bind User Authentication</title>

     <conbody>

       <p>
         When Search Bind authentication is enabled Impala first tries to bind
         with the configured bind user, then executes an LDAP Search operation
         to find if the user exists. Once the search succeeds the DN is
         retrieved from the LDAP search results and another LDAP bind request
         is executed, this time with the connecting user to verify the password.
       </p>

       <p>
         This authentication method allows to authenticate users existing in
         different LDAP subtrees when these users' parent tree is configured as
         base DN.
       </p>

       <dl>
       <dlentry>

         <dt>
           <codeph>--ldap_user_search_basedn</codeph>
         </dt>

         <dd>
           <p>
             The 'distinguished name' DN that will be used to search for the
             authenticating user, this field is required for search bind
             authentication.
           </p>
         </dd>

       </dlentry>

       <dlentry>

         <dt>
           <codeph>--ldap_group_search_basedn</codeph>
         </dt>

         <dd>
           <p>
             The 'distinguished name' DN that will be used to search for the
             authenticating group. If left empty, group checks will not be
             performed.
           </p>
         </dd>

       </dlentry>

       <dlentry>

         <dt>
           <codeph>--ldap_user_filter</codeph>
         </dt>

         <dd>
           <p>
             LDAP filter that will be used during LDAP search, it can contain
             <codeph>{0}</codeph> pattern which will be replaced with the
             username. The default value is <codeph>
             (&amp;(objectClass=user)(sAMAccountName={0}))</codeph>.
           </p>
         </dd>

       </dlentry>

       <dlentry>

         <dt>
           <codeph>--ldap_group_filter</codeph>
         </dt>

         <dd>
           <p>
             LDAP filter that will be used during LDAP group search, it can
             contain <codeph>{1}</codeph> pattern which will be replaced with
             the username and/or <codeph>{0}</codeph> which will be replaced
             with the user DN. The default value is <codeph>
             (&amp;(objectClass=group)(member={0})</codeph>.
           </p>
           <note>
             The behaviour of this flag has been changed between Impala 4.1 and Impala 4.2
             to comply with Spring LDAP. Previously <codeph>{0}</codeph> was for username
             and <codeph>{1}</codeph> for user dn, these paramters were swapped, now
             <codeph>{0}</codeph> is for user dn and <codeph>{1}</codeph> is for username.
           </note>
         </dd>

       </dlentry>
       </dl>

     </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>

       <dl>
         <dlentry>

           <dt>
             <codeph>--ldap_passwords_in_clear_ok</codeph>
           </dt>

           <dd>
             <p>
               Allows LDAP passwords to be sent in the clear (without TLS/SSL)
               over the network, when set to <codeph>true</codeph>. This option
               should not be used in production environments.
             </p>
           </dd>

         </dlentry>
       </dl>

       <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>

       <dl>
         <dlentry>

           <dt>
             <codeph>--ldap_tls</codeph>
           </dt>

           <dd>
             <p>
               Tells Impala to start a TLS connection to the LDAP server, and to fail
               authentication if it cannot be done.
             </p>
           </dd>

         </dlentry>

         <dlentry>

           <dt>
             <codeph>--ldap_ca_certificate</codeph>
           </dt>

           <dd>
             <p>
               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.
             </p>
           </dd>

         </dlentry>
       </dl>

     </conbody>

   </concept>

   <concept id="ldap_impala_shell">

     <title>LDAP Authentication for impala-shell</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>

       <dl>
         <dlentry>

           <dt>
             <codeph>-l</codeph>
           </dt>

           <dd>
             <p>
               Enables LDAP authentication.
             </p>
           </dd>

         </dlentry>

         <dlentry>

           <dt>
             <codeph>-u</codeph>
           </dt>

           <dd>
             <p>
               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 username from <cmdname>impala-shell</cmdname> automatically
               to the fully qualified name.
             </p>
           </dd>

         </dlentry>

         <dlentry>

           <dt>
             <codeph>--auth_creds_ok_in_clear</codeph>
           </dt>

           <dd>
             <p>
               If set, LDAP authentication may be used with an insecure
               connection to Impala. This flag is required when SSL between
               <codeph>impala-shell</codeph> and Impala Server is not configured.
               Authentication credentials will therefore be sent unencrypted, and
               may be vulnerable to attack.
             </p>
           </dd>

         </dlentry>
       </dl>

       <note>
         <cmdname>impala-shell</cmdname> automatically prompts for the password.
       </note>

       <p>
         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 in the Command Line Interface</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>.
           <dl>
             <dlentry>

               <dt>
                 <codeph>auth_username</codeph>
               </dt>

               <dd>
                 <p>
                   LDAP username of Hue user to be authenticated.
                 </p>
               </dd>

             </dlentry>

             <dlentry>

               <dt>
                 <codeph>auth_password</codeph>
               </dt>

               <dd>
                 <p>
                   LDAP password of Hue user to be authenticated.
                 </p>
               </dd>

             </dlentry>
           </dl>
           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>
	<?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>

	<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 outputclass="toc inpage"/>

	<p>
	An alternative form of authentication you can use is Kerberos, described in
	<xref href="impala_kerberos.xml#kerberos"/>.
	</p>

	</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>Consideration for Connections Between Impala Components</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>Enabling LDAP in Command Line Interface</title>

	<conbody>

	<p>
	To enable LDAP authentication, start the <cmdname>impalad</cmdname> with the following
	startup options for:
	</p>

	<dl>
	<dlentry>

	<dt>
	<codeph>--enable_ldap_auth</codeph>
	</dt>

	<dd>
	<p>
	Enables LDAP-based authentication between the client and Impala.
	</p>
	</dd>

	</dlentry>

	<dlentry>

	<dt>
	<codeph>--ldap_uri</codeph>
	</dt>

	<dd>
	<p>
	Sets the URI of the LDAP server to use. Typically, the URI is prefixed with
	<codeph>ldap://</codeph>. 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.)
	</p>
	</dd>

	</dlentry>

	<dlentry>

	<dt>
	<codeph>--ldap_search_bind_authentication</codeph>
	</dt>

	<dd>
	<p>
	Allows to switch between search and simple bind user lookup
	methods when authenticating, the default value is <codeph>false
	</codeph> which is simple bind.
	</p>
	</dd>

	</dlentry>
	</dl>

	</conbody>

	</concept>

	<concept id="ldap_bind_user">

	<title>Bind User Credentials</title>

	<conbody>

	<p>
	The bind user is used to run the user/group searches, the credentials
	can be configured with the following flags:
	</p>

	<dl>
	<dlentry>

	<dt>
	<codeph>--ldap_allow_anonymous_binds</codeph>
	</dt>

	<dd>
	<p>
	When true, LDAP authentication with a blank password (an
	'anonymous bind') is allowed by Impala. The default value is
	<codeph>false</codeph>.
	</p>
	</dd>

	</dlentry>

	<dlentry>

	<dt>
	<codeph>--ldap_bind_dn</codeph>
	</dt>

	<dd>
	<p>
	Distinguished name of the user to bind as when doing user or group
	searches. Only required if user or group filters are being used
	and the LDAP server is not configured to allow anonymous searches.
	</p>
	</dd>

	</dlentry>

	<dlentry>

	<dt>
	<codeph>--ldap_bind_password_cmd</codeph>
	</dt>

	<dd>
	<p>
	A Unix command whose output returns the password to use with
	<codeph>--ldap_bind_dn</codeph>. The output of the command will
	be truncated to 1024 bytes and trimmed of trailing whitespace.
	</p>
	</dd>

	</dlentry>
	</dl>

	</conbody>

	</concept>

	<concept id="ldap_simple_bind">

	<title>Simple Bind User Authentication</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 Ranger 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.
	</p>

	<note>
	The <codeph>--ldap_domain</codeph>, <codeph>--ldap_baseDN</codeph> and
	<codeph>--ldap_bind_pattern</codeph> options are mutually exclusive,
	and Impala does not start if more than one of these options are
	specified.
	</note>

	<dl>
	<dlentry>

	<dt>
	<codeph>--ldap_domain</codeph>
	</dt>

	<dd>
	<p>
	Replaces the username with a string
	<codeph><varname>username</varname>@<varname>ldap_domain</varname></codeph>.
	</p>
	</dd>

	</dlentry>

	<dlentry>

	<dt>
	<codeph>--ldap_baseDN</codeph>
	</dt>

	<dd>
	<p>
	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).
	</p>
	</dd>

	</dlentry>

	<dlentry>

	<dt>
	<codeph>--ldap_bind_pattern</codeph>
	</dt>

	<dd>
	<p>
	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>.
	</p>
	</dd>

	</dlentry>

	<dlentry>

	<dt>
	<codeph>--ldap_user_filter</codeph>
	</dt>

	<dd>
	<p>
	A comma separated list of usernames. If specified, users must be
	on this list for authentication to succeed
	</p>
	</dd>

	</dlentry>

	<dlentry>

	<dt>
	<codeph>--ldap_group_filter</codeph>
	</dt>

	<dd>
	<p>
	If specified, users must belong to one of these groups for
	authentication to succeed.
	</p>
	</dd>

	</dlentry>

	<dlentry>

	<dt>
	<codeph>--ldap_group_dn_pattern</codeph>
	</dt>

	<dd>
	<p>
	Colon separated list of patterns for the 'distinguished name' use
	to search for groups in the directory. Each pattern may contain a
	'%s' which will be substituted with each group name from
	<codeph>--ldap_group_filter</codeph> when doing group searches.
	</p>
	</dd>

	</dlentry>

	<dlentry>

	<dt>
	<codeph>--ldap_group_membership_key</codeph>
	</dt>

	<dd>
	<p>
	The LDAP attribute on group entries that indicates its members.
	</p>
	</dd>

	</dlentry>

	<dlentry>

	<dt>
	<codeph>--ldap_group_class_key</codeph>
	</dt>

	<dd>
	<p>
	The LDAP objectClass each of the groups in
	<codeph>--ldap_group_filter</codeph> implements in LDAP.
	</p>
	</dd>

	</dlentry>
	</dl>

	</conbody>

	</concept>

	<concept id="ldap_search_bind">

	<title>Search Bind User Authentication</title>

	<conbody>

	<p>
	When Search Bind authentication is enabled Impala first tries to bind
	with the configured bind user, then executes an LDAP Search operation
	to find if the user exists. Once the search succeeds the DN is
	retrieved from the LDAP search results and another LDAP bind request
	is executed, this time with the connecting user to verify the password.
	</p>

	<p>
	This authentication method allows to authenticate users existing in
	different LDAP subtrees when these users' parent tree is configured as
	base DN.
	</p>

	<dl>
	<dlentry>

	<dt>
	<codeph>--ldap_user_search_basedn</codeph>
	</dt>

	<dd>
	<p>
	The 'distinguished name' DN that will be used to search for the
	authenticating user, this field is required for search bind
	authentication.
	</p>
	</dd>

	</dlentry>

	<dlentry>

	<dt>
	<codeph>--ldap_group_search_basedn</codeph>
	</dt>

	<dd>
	<p>
	The 'distinguished name' DN that will be used to search for the
	authenticating group. If left empty, group checks will not be
	performed.
	</p>
	</dd>

	</dlentry>

	<dlentry>

	<dt>
	<codeph>--ldap_user_filter</codeph>
	</dt>

	<dd>
	<p>
	LDAP filter that will be used during LDAP search, it can contain
	<codeph>{0}</codeph> pattern which will be replaced with the
	username. The default value is <codeph>
	(&(objectClass=user)(sAMAccountName={0}))</codeph>.
	</p>
	</dd>

	</dlentry>

	<dlentry>

	<dt>
	<codeph>--ldap_group_filter</codeph>
	</dt>

	<dd>
	<p>
	LDAP filter that will be used during LDAP group search, it can
	contain <codeph>{1}</codeph> pattern which will be replaced with
	the username and/or <codeph>{0}</codeph> which will be replaced
	with the user DN. The default value is <codeph>
	(&(objectClass=group)(member={0})</codeph>.
	</p>
	<note>
	The behaviour of this flag has been changed between Impala 4.1 and Impala 4.2
	to comply with Spring LDAP. Previously <codeph>{0}</codeph> was for username
	and <codeph>{1}</codeph> for user dn, these paramters were swapped, now
	<codeph>{0}</codeph> is for user dn and <codeph>{1}</codeph> is for username.
	</note>
	</dd>

	</dlentry>
	</dl>

	</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>

	<dl>
	<dlentry>

	<dt>
	<codeph>--ldap_passwords_in_clear_ok</codeph>
	</dt>

	<dd>
	<p>
	Allows LDAP passwords to be sent in the clear (without TLS/SSL)
	over the network, when set to <codeph>true</codeph>. This option
	should not be used in production environments.
	</p>
	</dd>

	</dlentry>
	</dl>

	<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>

	<dl>
	<dlentry>

	<dt>
	<codeph>--ldap_tls</codeph>
	</dt>

	<dd>
	<p>
	Tells Impala to start a TLS connection to the LDAP server, and to fail
	authentication if it cannot be done.
	</p>
	</dd>

	</dlentry>

	<dlentry>

	<dt>
	<codeph>--ldap_ca_certificate</codeph>
	</dt>

	<dd>
	<p>
	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.
	</p>
	</dd>

	</dlentry>
	</dl>

	</conbody>

	</concept>

	<concept id="ldap_impala_shell">

	<title>LDAP Authentication for impala-shell</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>

	<dl>
	<dlentry>

	<dt>
	<codeph>-l</codeph>
	</dt>

	<dd>
	<p>
	Enables LDAP authentication.
	</p>
	</dd>

	</dlentry>

	<dlentry>

	<dt>
	<codeph>-u</codeph>
	</dt>

	<dd>
	<p>
	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 username from <cmdname>impala-shell</cmdname> automatically
	to the fully qualified name.
	</p>
	</dd>

	</dlentry>

	<dlentry>

	<dt>
	<codeph>--auth_creds_ok_in_clear</codeph>
	</dt>

	<dd>
	<p>
	If set, LDAP authentication may be used with an insecure
	connection to Impala. This flag is required when SSL between
	<codeph>impala-shell</codeph> and Impala Server is not configured.
	Authentication credentials will therefore be sent unencrypted, and
	may be vulnerable to attack.
	</p>
	</dd>

	</dlentry>
	</dl>

	<note>
	<cmdname>impala-shell</cmdname> automatically prompts for the password.
	</note>

	<p>
	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 in the Command Line Interface</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>.
	<dl>
	<dlentry>

	<dt>
	<codeph>auth_username</codeph>
	</dt>

	<dd>
	<p>
	LDAP username of Hue user to be authenticated.
	</p>
	</dd>

	</dlentry>

	<dlentry>

	<dt>
	<codeph>auth_password</codeph>
	</dt>

	<dd>
	<p>
	LDAP password of Hue user to be authenticated.
	</p>
	</dd>

	</dlentry>
	</dl>
	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>