doc/java-broker/src/docbkx/security/Java-Broker-Security-Authentication-Providers-LDAP.xml

<?xml version="1.0"?>
<!--

 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.

-->

<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="Java-Broker-Security-LDAP-Provider">
    <title>Simple LDAP</title>

    <para> The Simple LDAP authenticates connections against a Directory (LDAP). </para>
    <para> To create a SimpleLDAPAuthenticationProvider the following mandatory fields are required: <itemizedlist>
        <listitem>
            <para><emphasis>LDAP server URL</emphasis> is the URL of the server, for example,
                <literal>ldaps://example.com:636</literal></para>
        </listitem>
        <listitem>
            <para><emphasis>Search context</emphasis> is the distinguished name of the search base
                object. It defines the location from which the search for users begins, for example,
                <literal>dc=users,dc=example,dc=com</literal></para>
        </listitem>
        <listitem>
            <para><emphasis>Search filter</emphasis> is a DN template to find an LDAP user entry by
                provided user name, for example, <literal>(uid={0})</literal></para>
        </listitem>
    </itemizedlist> Additionally, the following optional fields can be specified: <itemizedlist>
        <listitem>
            <para><emphasis>LDAP context factory</emphasis> is a fully qualified class name for the
                JNDI LDAP context factory. This class must implement the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJdkDocUrl}javax/naming/spi/InitialContextFactory.html">InitialContextFactory</link> interface and produce instances of <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJdkDocUrl}javax/naming/directory/DirContext.html">DirContext</link>. If
                not specified a default value of <literal>com.sun.jndi.ldap.LdapCtxFactory</literal> is
                used.</para>
        </listitem>
        <listitem>
            <para><emphasis>LDAP authentication URL</emphasis> is the URL of LDAP server for
                performing "ldap bind". If not specified, the <emphasis>LDAP server URL</emphasis> will
                be used for both searches and authentications.</para>
        </listitem>
        <listitem>
            <para><emphasis>Truststore name</emphasis> is a name of <link linkend="Java-Broker-Management-Managing-Truststores-Attributes">configured
                truststore</link>. Use this if connecting to a Directory over SSL (i.e. ldaps://)
                which is protected by a certificate signed by a private CA (or utilising a self-signed
                certificate).</para>
        </listitem>
    </itemizedlist>
    </para>

    <important>
        <para>In order to protect the security of the user's password, when using LDAP authentication,
            you must: </para>
        <itemizedlist>
            <listitem>
                <para>Use SSL on the broker's AMQP and HTTP ports to protect the password during
                    transmission to the Broker. The Broker enforces this restriction automatically on AMQP
                    and HTTP ports.</para>
            </listitem>
            <listitem>
                <para>Authenticate to the Directory using SSL (i.e. ldaps://) to protect the password
                    during transmission from the Broker to the Directory.</para>
            </listitem>
        </itemizedlist>
    </important>

    <para> The LDAP Authentication Provider works in the following manner. If not in <literal>bind
        without search</literal> mode, it first connects to the Directory and searches for the ldap
        entity which is identified by the username. The search begins at the distinguished name
        identified by <literal>Search Context</literal> and uses the username as a filter. The search
        scope is sub-tree meaning the search will include the base object and the subtree extending
        beneath it. </para>

    <para> If the search returns a match, or is configured in <literal>bind without search</literal>
        mode, the Authentication Provider then attempts to bind to the LDAP server with the given name
        and the password. Note that <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJdkDocUrl}javax/naming/Context.html#SECURITY_AUTHENTICATION">simple security
            authentication</link> is used so the Directory receives the password in the clear. </para>
</section>