# Authentication Providers

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 using more than one at a time.

## Password File

TODO

## LDAP

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.

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.

Configuring LDAP authentication

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

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.

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.

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.

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.

## Kerberos

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.

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:

Configuring Kerberos authentication

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

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

        export QPID_OPTS=-Djavax.security.auth.useSubjectCredsOnly=false -Djava.security.auth.login.config=qpid.conf
        ${QPID_HOME}/bin/qpid-server

Where qpid.conf would look something like this:

    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>";
    };

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).

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.

## External (SSL Client Certificates)

When requiring SSL Client Certificates 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.

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.

Note: The ExternalAuthenticationManager should typically only be used on the AMQP ports, in conjunction with SSL client certificate authentication. 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 include another Authentication Manager for use on non-AMQP ports, 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.

Configuring external authentication (SSL client auth)

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

## Anonymous

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.

Configuring anonymous authentication

    <security>
      <anonymous-auth-manager/>
      ...
    </security>

When referencing it from the default-auth-manager or port-mapping sections, its name is AnonymousAuthenticationManager.

## Configuring multiple Authentication Providers

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.

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).

Configuring multiple (per-port) authentication schemes

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