doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml

<?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 &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>
  <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 &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>

  <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 &lt;external-auth-manager&gt; element to
      the &lt;security&gt; 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 &lt;security&gt; 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>