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>

 <!-- 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-&gt;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>
	<?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>