diff options
Diffstat (limited to 'doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml')
| -rw-r--r-- | doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml | 320 |
1 files changed, 320 insertions, 0 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 new file mode 100644 index 0000000000..0974441ae5 --- /dev/null +++ b/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml @@ -0,0 +1,320 @@ +<?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". Each of these are outlined below, along with details + of <link linkend="MultipleAuthProviders"> using more than one at a time</link>. + </para> + + <section> + <title>Password File</title> + <para> + TODO + </para> + + </section> + + <section id="LDAPAuthManager"> + <title>LDAP</title> + + <para> + LDAP authentication can be configured using the <simple-ldap-auth-manager> element + within the <security> section. An example of how to configure this is shown below. + Please note this example also configures an unused <pd-auth-manager> 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> + <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> + + <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 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/> + <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 id="ExternalAuthManager"> + <title>External (SSL Client Certificates)</title> + + <para> + When <link linkend="SSL-Truststore-ClientCertificate"> requiring SSL Client Certificates</link> be + presented the ExternalAuthenticationManager can be used, such that the user is authenticated based on + trust of their certificate alone, and the X500Principal from the SSL session is then used as the username + for the connection, instead of also requiring the user to present a valid username and password. + </para> + + <para> + The ExternalAuthenticationManager may be enabled by adding an empty <external-auth-manager> element to + the <security> section, as shown below. When referencing it from the default-auth-manager or port-mapping + sections, its name is ExternalAuthenticationManager. + </para> + + <para> + <emphasis role="bold">Note:</emphasis> The ExternalAuthenticationManager should typically only be used on the + AMQP ports, in conjunction with <link linkend="SSL-Truststore-ClientCertificate">SSL client certificate + authentication</link>. It is not intended for other uses such as the JMX management port and will treat any + non-sasl authentication processes on these ports as successfull with the given username. As such you should + <link linkend="MultipleAuthProviders">include another Authentication Manager for use on non-AMQP ports</link>, + as is done in the example below. Perhaps the only exception to this would be where the broker is embedded in a + container that is itself externally protecting the HTTP interface and then providing the remote users name. + </para> + + <example> + <title>Configuring external authentication (SSL client auth)</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> + <external-auth-manager/> + <default-auth-manager>PrincipalDatabaseAuthenticationManager</default-auth-manager> + <port-mappings> + <port-mapping> + <port>5672</port> + <auth-manager>ExternalAuthenticationManager</auth-manager> + </port-mapping> + </port-mappings> + ... +</security>]]></programlisting> + </example> + + </section> + + <section id="AnonymousAuthManager"> + <title>Anonymous</title> + + <para> + The AnonymousAuthenticationManager will allow users to connect with or without credentials and result + in their identification on the broker as the user ANONYMOUS. It may be enabled by adding an empty + anonymous-auth-manager element to the security configuration section, as shown below. + </para> + + <example> + <title>Configuring anonymous authentication</title> + + <programlisting><![CDATA[ +<security> + <anonymous-auth-manager/> + ... +</security>]]></programlisting> + </example> + + <para> + When referencing it from the default-auth-manager or port-mapping sections, its name is + AnonymousAuthenticationManager. + </para> + </section> + + <section id="MultipleAuthProviders"> + <title>Configuring multiple Authentication Providers</title> + <para> + 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, it will be used on all ports (including JMX + and HTTP). Where more than one authentication manager is configured the configuration must define + which 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 and HTTP ports), Kerberos on port 5672 (the regular AMQP port) and Anonymous + on port 5673 (e.g a second AMQP port the broker could have been configured with). + </para> + + <example> + <title>Configuring multiple (per-port) authentication schemes</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/> + <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> + +</section> + |