From fcc3cbf4cad07e28d41b92c21f6f58b0c3d45f9a Mon Sep 17 00:00:00 2001
From: Robert Gemmell <robbie@apache.org>
Date: Wed, 28 Nov 2012 17:11:52 +0000
Subject: QPID-4462: add some documentation regarding the security provider
 workaround, until the issue can be fixed

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk/qpid@1414821 13f79535-47bb-0310-9956-ffa450edef68
---
 ...va-Broker-Security-Authentication-Providers.xml | 40 ++++++++++++++++++----
 1 file changed, 33 insertions(+), 7 deletions(-)

diff --git a/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml b/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml
index 96b6f99185..0974441ae5 100644
--- a/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml
+++ b/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml
@@ -38,18 +38,44 @@
 
   </section>
 
-  <section>
+  <section id="LDAPAuthManager">
   <title>LDAP</title>
+
+  <para>
+    LDAP authentication can be configured using the &lt;simple-ldap-auth-manager&gt; element
+    within the &lt;security&gt; section. An example of how to configure this is shown below.
+    Please note this example also configures an unused &lt;pd-auth-manager&gt; to use an empty
+    password file, this is a workaround for an issue relating to registration of security providers.
+  </para>
+
+  <para>
+    <emphasis>NOTE: When using LDAP authentication, you must also use SSL on the brokers AMQP messaging and
+    JMX/HTTP management ports in order to protect passwords during transmission to the broker.</emphasis>
+  </para>
   <example>
     <title>Configuring LDAP authentication</title>
     <programlisting><![CDATA[
 <security>
-    <simple-ldap-auth-manager>
-      <provider-url>ldaps://example.com:636/</provider-url>
-      <search-context>dc=example\,dc=com</search-context>
-      <search-filter>(uid={0})</search-filter>
-    </simple-ldap-auth-manager>
-    ...
+  <default-auth-manager>SimpleLDAPAuthenticationManager</default-auth-manager>
+  <simple-ldap-auth-manager>
+    <provider-url>ldaps://example.com:636/</provider-url>
+    <search-context>dc=example\,dc=com</search-context>
+    <search-filter>(uid={0})</search-filter>
+  </simple-ldap-auth-manager>
+
+  <!-- Unused pd-auth-manager, a workaround to register the necessary security providers -->
+  <pd-auth-manager>
+    <principal-database>
+      <class>org.apache.qpid.server.security.auth.database.PlainPasswordFilePrincipalDatabase</class>
+      <attributes>
+        <attribute>
+          <name>passwordFile</name>
+          <value>${conf}/emptyPasswdFile</value>
+        </attribute>
+      </attributes>
+    </principal-database>
+  <pd-auth-manager>
+  ...
 </security>]]></programlisting>
   </example>
 
-- 
cgit v1.2.1