path: root/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE entities [
<!ENTITY %  entities SYSTEM  "commonEntities.xml">
%entities;
]>
<!--

 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 provider". Any number of Authentication Providers can be configured on
    the Broker at the same time. </para>

  <important>
    <para> Only unused Authentication Provider can be deleted. For delete requests attempting to
      delete Authentication Provider associated with the Ports, the errors will be returned and
      delete operations will be aborted. It is possible to change the Authentication Provider on
      Port at runtime. However, the Broker restart is required for changes on Port to take effect.
    </para>
  </important>

  <section id="Java-Broker-Security-LDAP-Provider">
    <title>Simple LDAP Authentication Provider</title>

    <para> SimpleLDAPAuthenticationProvider authenticates connections against a Directory (LDAP). </para>
    <para> To create a SimpleLDAPAuthenticationProvider the following mandatory fields are required: <itemizedlist>
        <listitem>
          <para><emphasis>LDAP server URL</emphasis> is the URL of the server, for example,
              <literal>ldaps://example.com:636</literal></para>
        </listitem>
        <listitem>
          <para><emphasis>Search context</emphasis> is the distinguished name of the search base
            object. It defines the location from which the search for users begins, for example,
              <literal>dc=users,dc=example,dc=com</literal></para>
        </listitem>
        <listitem>
          <para><emphasis>Search filter</emphasis> is a DN template to find an LDAP user entry by
            provided user name, for example, <literal>(uid={0})</literal></para>
        </listitem>
      </itemizedlist> Additionally, the following optional fields can be specified: <itemizedlist>
        <listitem>
          <para><emphasis>LDAP context factory</emphasis> is a fully qualified class name for the
            JNDI LDAP context factory. This class must implement the <ulink
              url="&oracleJdkDocUrl;javax/naming/spi/InitialContextFactory.html"
              >InitialContextFactory</ulink> interface and produce instances of <ulink
              url="&oracleJdkDocUrl;javax/naming/directory/DirContext.html">DirContext</ulink>. If
            not specified a default value of <literal>com.sun.jndi.ldap.LdapCtxFactory</literal> is
            used.</para>
        </listitem>
        <listitem>
          <para><emphasis>LDAP authentication URL</emphasis> is the URL of LDAP server for
            performing "ldap bind". If not specified, the <emphasis>LDAP server URL</emphasis> will
            be used for both searches and authentications.</para>
        </listitem>
        <listitem>
          <para><emphasis>Truststore name</emphasis> is a name of <link
              linkend="Java-Broker-Management-Managing-Truststores-Attributes">configured
              truststore</link>. Use this if connecting to a Directory over SSL (i.e. ldaps://)
            which is protected by a certificate signed by a private CA (or utilising a self-signed
            certificate).</para>
        </listitem>
      </itemizedlist>
    </para>

    <important>
      <para>In order to protect the security of the user's password, when using LDAP authentication,
        you must: </para>
      <itemizedlist>
        <listitem>
          <para>Use SSL on the broker's AMQP, HTTP and JMX ports to protect the password during
            transmission to the Broker. The Broker enforces this restriction automatically on AMQP
            and HTTP ports.</para>
        </listitem>
        <listitem>
          <para>Authenticate to the Directory using SSL (i.e. ldaps://) to protect the password
            during transmission from the Broker to the Directory.</para>
        </listitem>
      </itemizedlist>
    </important>

    <para> The LDAP Authentication Provider works in the following manner. If not in <literal>bind
        without search</literal> mode, it first connects to the Directory and searches for the ldap
      entity which is identified by the username. The search begins at the distinguished name
      identified by <literal>Search Context</literal> and uses the username as a filter. The search
      scope is sub-tree meaning the search will include the base object and the subtree extending
      beneath it. </para>

    <para> If the search returns a match, or is configured in <literal>bind without search</literal>
      mode, the Authentication Provider then attempts to bind to the LDAP server with the given name
      and the password. Note that <ulink
        url="&oracleJdkDocUrl;javax/naming/Context.html#SECURITY_AUTHENTICATION">simple security
        authentication</ulink> is used so the Directory receives the password in the clear. </para>
  </section>

  <section id="Java-Broker-Security-Kerberos-Provider">
    <title>Kerberos</title>

    <para> Kereberos Authentication Provider uses java GSS-API SASL mechanism to authenticate the
      connections. </para>

    <para> Configuration of kerberos is done through system properties (there doesn't seem to be a
      way around this unfortunately). </para>

    <programlisting>
    export JAVA_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>

    <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 Provider
      configuration, and use this for JMX and HTTP ports. </para>

  </section>

  <section id="Java-Broker-Security-External-Provider">
    <title>External (SSL Client Certificates)</title>

    <para> When <link linkend="Java-Broker-Management-Managing-Truststores"> requiring SSL Client
        Certificates</link> be presented the External Authentication Provider 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>
      <emphasis role="bold">Note:</emphasis> The External Authentication Provider should typically
      only be used on the AMQP/HTTP ports, in conjunction with <link
        linkend="Java-Broker-Management-Managing-Ports">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 successful with the given
      username. As such you should configure another Authentication Provider for use on JMX
      ports.</para>

    <para>On creation of External Provider the use of full DN or username CN as a principal name can
      be configured. If attribute "Use the full DN as the Username" is set to "true" the full DN is
      used as an authenticated principal name. If attribute "Use the full DN as the Username" is set
      to "false" the user name CN part is used as the authenticated principal name. Setting the
      field to "false" is particular useful when <link linkend="Java-Broker-Security-ACLs"
        >ACL</link> is required, as at the moment, ACL does not support commas in the user name.
    </para>
  </section>

  <section id="Java-Broker-Security-Anonymous-Provider">
    <title>Anonymous</title>

    <para> The Anonymous Authentication Provider will allow users to connect with or without
      credentials and result in their identification on the broker as the user ANONYMOUS. This
      Provider does not require specification of any additional attributes on creation. </para>
  </section>

  <section id="Java-Broker-Security-ScramSha-Providers">
    <title>SCRAM SHA Providers</title>
    <para>The SCRAM SHA Providers uses the Broker configuration itself to store the database of
      users. (Unlike the <link linkend="Java-Broker-Security-PlainPasswordFile-Provider"
        >Plain</link> and <link linkend="Java-Broker-Security-Base64MD5PasswordFile-Provider"
        >Base64MD5</link> providers that follow, there is no separate password file). The users'
      passwords are stored as salted SHA digested password. This can be further encrypted using the
      facilities described in <xref linkend="Java-Broker-Security-Configuration-Encryption"
      />.</para>
    <para>There are two variants of this provider, SHA1 and SHA256. SHA256 is recommended whenever
      possible. SHA1 is provided with compatibility with clients utilising JDK 1.6 (which does not
      support SHA256).</para>
    <para>For these providers user credentials can be added, removed or changed using
      Management.</para>
  </section>

  <section id="Java-Broker-Security-PlainPasswordFile-Provider">
    <title>Plain Password File</title>
    <para> The PlainPasswordFile Provider uses local file to store and manage user credentials. When
      creating an authentication provider the path to the file needs to be specified. If specified
      file does not exist an empty file is created automatically on Authentication Provider
      creation. On Provider deletion the password file is deleted as well.</para>
    <para>For these providers user credentials can be added, removed or changed using
      Management.</para>

    <section>
      <title>Plain Password File Format</title>
      <para> The user credentials are stored on the single file line as user name and user password
        pairs separated by colon character. This file must not be modified externally whilst the
        Broker is running.</para>
      <programlisting>
# password file format
# &lt;user name&gt;: &lt;user password&gt;
guest:guest
        </programlisting>
    </section>
  </section>

  <section id="Java-Broker-Security-Base64MD5PasswordFile-Provider">
    <title>Base64MD5 Password File</title>
    <para> Base64MD5PasswordFile Provider uses local file to store and manage user credentials
      similar to PlainPasswordFile but instead of storing a password the MD5 password digest encoded
      with Base64 encoding is stored in the file. When creating an authentication provider the path
      to the file needs to be specified. If specified file does not exist an empty file is created
      automatically on Authentication Provider creation. On Base64MD5PasswordFile Provider deletion
      the password file is deleted as well.</para>
    <section>
      <title>Base64MD5 File Format</title>
      <para> The user credentials are stored on the single file line as user name and user password
        pairs separated by colon character. The password is stored MD5 digest/Base64 encoded. This
        file must not be modified externally whilst the Broker is running.</para>
    </section>
  </section>
</section>