You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by rg...@apache.org on 2012/08/28 12:02:21 UTC
svn commit: r1378051 - in /qpid/trunk/qpid/doc/book/src/java-broker:
AMQP-Messaging-Broker-Java-Book.xml Configure-AuthenticationProviders.xml
Author: rgodfrey
Date: Tue Aug 28 10:02:21 2012
New Revision: 1378051
URL: http://svn.apache.org/viewvc?rev=1378051&view=rev
Log:
QPID-4010 : [Java Broker] Add documentation on authentication managers from JIRA into docbook
Added:
qpid/trunk/qpid/doc/book/src/java-broker/Configure-AuthenticationProviders.xml
Modified:
qpid/trunk/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml
Modified: qpid/trunk/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml?rev=1378051&r1=1378050&r2=1378051&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml Tue Aug 28 10:02:21 2012
@@ -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"/>
Added: qpid/trunk/qpid/doc/book/src/java-broker/Configure-AuthenticationProviders.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Configure-AuthenticationProviders.xml?rev=1378051&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Configure-AuthenticationProviders.xml (added)
+++ qpid/trunk/qpid/doc/book/src/java-broker/Configure-AuthenticationProviders.xml Tue Aug 28 10:02:21 2012
@@ -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
+ <security> 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 <provider-auth-url> in addition to providing a
+ <provider-url>. 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 <ldap-context-factory> in the configuration.
+ </para>
+
+ </section>
+ <section><title>Kerberos</title>
+
+ <para>
+ Kereberos Authentication is configured using the <kerberos-auth-manager> element within
+ the <security> 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>
+
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org