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

  <para>
    The Authentication Providers can be configured using <link linkend="Java-Broker-Configuring-And-Managing-REST-API">REST Management interfaces</link>
             and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>.
  </para>

  <para>The following Authentication Provider managing operations are available from Web Management Console:
    <itemizedlist>
        <listitem><para>A new Authentication Provider can be added by clicking onto "Add Provider" on the Broker tab.</para></listitem>
        <listitem><para>An Authentication Provider details can be viewed on the Authentication Provider tab.
        The tab is displayed after clicking onto Authentication Provider name in the Broker object tree or after clicking
        onto Authentication Provider row in Authentication Providers grid on the Broker tab.</para></listitem>
        <listitem><para>Editing of Authentication Provider can be performed by clicking on "Edit" button
        on Authentication Provider tab.</para></listitem>
        <listitem><para>An existing  Authentication Provider can be deleted by clicking on "Delete Provider" button
        on Broker tab or "Delete" button on the Authentication Provider tab.</para></listitem>
    </itemizedlist>
    The Authentication Provider type and name cannot be changed for existing providers as editing of name and type
    is unsupported at the moment. Only provider specific attributes can be modified in the editing dialog
    and stored in the broker configuration store.
  </para>

  <important>
  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.
  </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="SSL-Truststore-ClientCertificate">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>
    In order to protect the security of the user's password, when using LDAP authentication, you must:
    <itemizedlist>
      <listitem><para>Use SSL on the broker's AMQP, JMX, and HTTP ports to protect the password during
        transmission to the Broker.</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.  It first connects to the Directory anonymously
    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, 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="SSL-Truststore-ClientCertificate"> 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 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 successful with the given username. As such you should
      configure another Authentication Provider for use on non-AMQP ports. 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>

    <para>On creation of External Provider the use of full DN or username CN as a principal name can be configured.
    If field "Use the full DN as the Username" is set to "true" the full DN is used as an authenticated principal name.
    If field "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 fields on creation.
    </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. For this Provider
      user credentials can be added, removed or changed using REST management interfaces and web management console.
    </para>
    <para>
    On navigating to the Plain Password File Provider tab (by clicking onto provider name from Broker tree or provider
    row in providers grid on Broker tab) the list of existing credentials is displayed on the tab with the buttons "Add User"
    and "Delete Users" to add new user credentials and delete the existing user credentials respectively.
    On clicking into user name on Users grid the pop-up dialog to change the password is displayed.
    </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.
        </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 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. For this Provider
      user credentials can be added, removed or changed using REST management interfaces and web management console.
    </para>
    <para>
    On navigating to the Base64MD5PasswordFile Provider tab (by clicking onto provider name from Broker tree or provider
    row in providers grid on Broker tab) the list of existing credentials is displayed on the tab with the buttons "Add User"
    and "Delete Users" to add new user credentials and delete the existing user credentials respectively.
    On clicking into user name on Users grid the pop-up dialog to change the password is displayed.
    </para>
  </section>
</section>

