QPID-4010 : [Java Broker] Add documentation on authentication managers from JIRA into docbook

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

2 files changed, 189 insertions, 0 deletions

diff --git a/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml b/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml
index 54c2984d0a..017604d910 100644
--- a/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml
+++ b/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml
@@ -56,6 +56,7 @@
         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Configure-Log4j-CompositeRolling-Appender.xml"/>
         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Configure-the-Broker-via-config.xml.xml"/>
         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Configure-the-Virtual-Hosts-via-virtualhosts.xml.xml"/>
+        <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Configure-AuthenticationProviders.xml"/>
         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Debug-using-log4j.xml"/>
         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="How-to-Tune-M3-Java-Broker-Performance.xml"/>
         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Qpid-Java-Build-How-To.xml"/>
diff --git a/qpid/doc/book/src/java-broker/Configure-AuthenticationProviders.xml b/qpid/doc/book/src/java-broker/Configure-AuthenticationProviders.xml
new file mode 100644
index 0000000000..a5a1cd7602
--- /dev/null
+++ b/qpid/doc/book/src/java-broker/Configure-AuthenticationProviders.xml
@@ -0,0 +1,188 @@
+<?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.
+ 
+-->
+
+<section>
+  <title>Configuring Authentication Mechanisms</title>
+  <para>
+    In order to successfully establish a connection to the Java Broker, the connection must be
+    authenticated. The Java Broker supports a number of different authentication schemesi, each
+    with its own "authentication manager". Different managers may be used on different ports.
+    Each manager has its own configuration element, the presence of which within the
+    &lt;security&gt; section denotes the use of that authentication mechanism. Where only one
+    such manager is configured, that manager will be used on all ports (including JMX). Where
+    more than one authentication manager is configured the configuration must define which 
+    manager is the "default", and (if required) the mapping of non-default authentication
+    managers to other ports.
+  </para>
+  <para>
+    The following configuration sets up three authentication managers, using a password file as
+    the default (e.g. for the JMX port), Kerberos on port 5672 and Anonymous on 5673.
+  </para>
+
+  <programlisting><![CDATA[
+    <security>
+        <pd-auth-manager>
+            <principal-database>
+                <class>org.apache.qpid.server.security.auth.database.PlainPasswordFilePrincipalDatabase</class>
+                <attributes>
+                    <attribute>
+                        <name>passwordFile</name>
+                        <value>${conf}/passwd</value>
+                    </attribute>
+                </attributes>
+            </principal-database>
+        </pd-auth-manager>
+        <kerberos-auth-manager><auth-name>sib</auth-name></kerberos-auth-manager>
+        <anonymous-auth-manager></anonymous-auth-manager>
+        <default-auth-manager>PrincipalDatabaseAuthenticationManager</default-auth-manager>
+        <port-mappings>
+            <port-mapping>
+                <port>5672</port>
+                <auth-manager>KerberosAuthenticationManager</auth-manager>
+            </port-mapping>
+            <port-mapping>
+                <port>5673</port>
+                <auth-manager>AnonymousAuthenticationManager</auth-manager>
+            </port-mapping>
+        </port-mappings>
+    </security>]]>
+  </programlisting>
+
+  <section><title>Password File</title></section>
+  <section><title>LDAP</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>
+    </security>]]>
+  </programlisting>  
+
+  <para>
+    The authentication manager first connects to the ldap server anonymously and searches for the
+    ldap entity which is identified by the username provided over SASL. Essentially the
+    authentication manager calls
+    DirContext.search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons)
+    with the values of search-context and search-filter as the first two arguments, and the username
+    as the only element in the array which is the third argument.
+  </para>
+
+  <para>
+    If the search returns a name from the LDAP server, the AuthenticationManager then attempts to
+    login to the ldap server with the given name and the password.
+  </para>
+
+  <para>
+    If the URL to open for authentication is different to that for the search, then the
+    authentication url can be overridden using &lt;provider-auth-url&gt; in addition to providing a
+    &lt;provider-url&gt;. Note that the URL used for authentication should use ldaps:// since
+    passwords will be being sent over it.
+  </para>
+
+  <para>
+    By default com.sun.jndi.ldap.LdapCtxFactory is used to create the context, however this can be
+    overridden by specifying &lt;ldap-context-factory&gt; in the configuration.
+  </para>
+
+  </section>
+  <section><title>Kerberos</title>
+
+  <para>
+    Kereberos Authentication is configured using the &lt;kerberos-auth-manager&gt; element within
+    the &lt;security&gt; section. When referencing from the default-auth-manager or port-mapping
+    sections, its name is KerberosAuthenticationManager.
+  </para>
+
+  <para>
+    Since Kerberos support only works where SASL authentication is available (e.g. not for JMX
+    authentication) you may wish to also include an alternative Authentication Manager
+    configuration, and use this for other ports:
+  </para>
+
+  <programlisting><![CDATA[
+    <security>
+        <pd-auth-manager>
+            <principal-database>
+                <class>org.apache.qpid.server.security.auth.database.PlainPasswordFilePrincipalDatabase</class>
+                <attributes>
+                    <attribute>
+                        <name>passwordFile</name>
+                        <value>${conf}/passwd</value>
+                    </attribute>
+                </attributes>
+            </principal-database>
+        </pd-auth-manager>
+        <kerberos-auth-manager><auth-name>sib</auth-name></kerberos-auth-manager>
+        <default-auth-manager>PrincipalDatabaseAuthenticationManager</default-auth-manager>
+        <port-mappings>
+            <port-mapping>
+                <port>5672</port>
+                <auth-manager>KerberosAuthenticationManager</auth-manager>
+            </port-mapping>
+        </port-mappings>
+    </security>]]>
+  </programlisting>
+
+  <para>
+    Configuration of kerberos is done through system properties (there doesn't seem to be a way
+    around this unfortunately).
+  </para>
+
+  <programlisting>
+    export QPID_OPTS=-Djavax.security.auth.useSubjectCredsOnly=false -Djava.security.auth.login.config=qpid.conf
+    ${QPID_HOME}/bin/qpid-server
+  </programlisting>
+
+  <para>Where qpid.conf would look something like this:</para>
+
+  <programlisting><![CDATA[
+com.sun.security.jgss.accept {
+    com.sun.security.auth.module.Krb5LoginModule required
+    useKeyTab=true
+    storeKey=true
+    doNotPrompt=true
+    realm="EXAMPLE.COM"
+    useSubjectCredsOnly=false
+    kdc="kerberos.example.com"
+    keyTab="/path/to/keytab-file"
+    principal="<name>/<host>";
+};]]>
+  </programlisting>
+
+  <para>
+    Where realm, kdc, keyTab and principal should obviously be set correctly for the environment
+    where you are running (see the existing documentation for the C++ broker about creating a keytab
+    file).
+  </para>
+
+  <para>
+    Note: You may need to install the "Java Cryptography Extension (JCE) Unlimited Strength
+    Jurisdiction Policy Files" appropriate for your JDK in order to get Kerberos support working.
+  </para>
+  </section>
+  <section><title>SSL Client Certificates</title></section>
+  <section><title>Anonymous</title></section>
+</section>
+