docs/topics/impala_ldap.xml

<?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>&#8209;&#8209;enable_ldap_auth</codeph>
          </dt>

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

        </dlentry>

        <dlentry>

          <dt>
            <codeph>&#8209;&#8209;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>
      </dl>

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

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

      <p>
        The above options are mutually exclusive, and Impala does not start if more than one of
        these options are 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>

      <dl>
        <dlentry>

          <dt>
            <codeph>&#8209;&#8209;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>&#8209;&#8209;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 user name from <cmdname>impala-shell</cmdname> automatically
              to the fully qualified name.
            </p>
          </dd>

        </dlentry>
      </dl>

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

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