diff options
Diffstat (limited to 'qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml')
| -rw-r--r-- | qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml | 197 |
1 files changed, 197 insertions, 0 deletions
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml b/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml new file mode 100644 index 0000000000..58360dc722 --- /dev/null +++ b/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml @@ -0,0 +1,197 @@ +<?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 id="Java-Broker-Security-Authentication-Providers"> + <title>Authentication Providers</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 schemes, 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 provider. 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> + + <example> + <title>Configuring different authentication schemes on different ports</title> + <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> + </example> + + <section><title>Password File</title></section> + <section><title>LDAP</title> + <example> + <title>Configuring a 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> +</security>]]> + </programlisting> + </example> + + <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> + + <example> + <title>Configuring a Kerberos authentication</title> + <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></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> + </example> + + <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> + |