QPID-6108: [Java Documentation] Refactor security/auth providers section into separate files to allow for convenient re-purposing of the document

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1635639 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 99 insertions, 0 deletions

diff --git a/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-LDAP.xml b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-LDAP.xml
new file mode 100644
index 0000000000..81b36f4692
--- /dev/null
+++ b/qpid/doc/book/src/java-broker/security/Java-Broker-Security-Authentication-Providers-LDAP.xml
@@ -0,0 +1,99 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+                    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+[
+<!ENTITY %  entities SYSTEM  "../commonEntities.xml">
+%entities;
+]>
+<!--
+
+ 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 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 <ulink
+                    url="&oracleJdkDocUrl;javax/naming/spi/InitialContextFactory.html"
+                    >InitialContextFactory</ulink> interface and produce instances of <ulink
+                        url="&oracleJdkDocUrl;javax/naming/directory/DirContext.html">DirContext</ulink>. 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, HTTP and JMX 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 <ulink
+            url="&oracleJdkDocUrl;javax/naming/Context.html#SECURITY_AUTHENTICATION">simple security
+            authentication</ulink> is used so the Directory receives the password in the clear. </para>
+</section>