<div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Chapter&#160;8.&#160;Security</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="Java-Broker-Management-Managing-Plugin-HTTP.html">Prev</a>&#160;</td><th align="center" width="60%">&#160;</th><td align="right" width="20%">&#160;<a accesskey="n" href="Java-Broker-Security-Group-Providers.html">Next</a></td></tr></table><hr /></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Java-Broker-Security"></a>Chapter&#160;8.&#160;Security</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="Java-Broker-Security.html#Java-Broker-Security-Authentication-Providers">8.1. Authentication Providers</a></span></dt><dd><dl><dt><span class="section"><a href="Java-Broker-Security.html#Java-Broker-Security-LDAP-Provider">8.1.1. Simple LDAP</a></span></dt><dt><span class="section"><a href="Java-Broker-Security.html#Java-Broker-Security-Kerberos-Provider">8.1.2. Kerberos</a></span></dt><dt><span class="section"><a href="Java-Broker-Security.html#Java-Broker-Security-OAuth2-Provider">8.1.3. OAuth2</a></span></dt><dt><span class="section"><a href="Java-Broker-Security.html#Java-Broker-Security-External-Provider">8.1.4. External (SSL Client Certificates)</a></span></dt><dt><span class="section"><a href="Java-Broker-Security.html#Java-Broker-Security-Anonymous-Provider">8.1.5. Anonymous</a></span></dt><dt><span class="section"><a href="Java-Broker-Security.html#Java-Broker-Security-ScramSha-Providers">8.1.6. SCRAM SHA</a></span></dt><dt><span class="section"><a href="Java-Broker-Security.html#Java-Broker-Security-Plain-Provider">8.1.7. Plain</a></span></dt><dt><span class="section"><a href="Java-Broker-Security.html#Java-Broker-Security-PlainPasswordFile-Provider">8.1.8. Plain Password File <span class="emphasis"><em>(Deprecated)</em></span></a></span></dt><dt><span class="section"><a href="Java-Broker-Security.html#Java-Broker-Security-MD5-Provider">8.1.9. MD5 Provider</a></span></dt><dt><span class="section"><a href="Java-Broker-Security.html#Java-Broker-Security-Base64MD5PasswordFile-Provider">8.1.10. Base64MD5 Password File <span class="emphasis"><em>(Deprecated)</em></span></a></span></dt></dl></dd><dt><span class="section"><a href="Java-Broker-Security-Group-Providers.html">8.2. Group Providers</a></span></dt><dd><dl><dt><span class="section"><a href="Java-Broker-Security-Group-Providers.html#File-Group-Manager">8.2.1. GroupFile Provider</a></span></dt><dt><span class="section"><a href="Java-Broker-Security-Group-Providers.html#Java-Broker-Security-Group-Providers-ManagedGroupProvider">8.2.2. ManagedGroupProvider</a></span></dt><dt><span class="section"><a href="Java-Broker-Security-Group-Providers.html#Java-Broker-Security-Group-Providers-CloudFoundry">8.2.3. CloudFoundryDashboardManagementGroupProvider</a></span></dt></dl></dd><dt><span class="section"><a href="Java-Broker-Security-AccessControlProviders.html">8.3. Access Control Providers</a></span></dt><dd><dl><dt><span class="section"><a href="Java-Broker-Security-AccessControlProviders.html#Java-Broker-Security-AccessControlProviders-Types">8.3.1. Types</a></span></dt><dt><span class="section"><a href="Java-Broker-Security-AccessControlProviders.html#Java-Broker-Security-AccessControlProviders-ACLRules">8.3.2. 
       ACL Rules
    </a></span></dt><dt><span class="section"><a href="Java-Broker-Security-AccessControlProviders.html#Java-Broker-Security-AccessControlProviders-Syntax">8.3.3. 
       Syntax
    </a></span></dt><dt><span class="section"><a href="Java-Broker-Security-AccessControlProviders.html#Java-Broker-Security-AccessControlProviders-WorkedExamples">8.3.4. 
      Worked Examples
    </a></span></dt></dl></dd><dt><span class="section"><a href="Java-Broker-Security-Configuration-Encryption.html">8.4. Configuration Encryption</a></span></dt><dd><dl><dt><span class="section"><a href="Java-Broker-Security-Configuration-Encryption.html#Java-Broker-Security-Configuration-Encryption-Configuration">8.4.1. Configuration</a></span></dt><dt><span class="section"><a href="Java-Broker-Security-Configuration-Encryption.html#Java-Broker-Security-Configuration-Encryption-Alternate-Implementations">8.4.2. Alternate Implementations</a></span></dt></dl></dd></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Java-Broker-Security-Authentication-Providers"></a>8.1.&#160;Authentication Providers</h2></div></div></div><p> In order to successfully establish a connection to the Broker, the connection must be
    authenticated. The 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. </p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p> 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.
    </p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
      Authentication Providers may choose to selectively disable certain authentication mechanisms
      depending on whether an encrypted transport is being used or not. This is to avoid insecure
      configurations. Notably, by default the PLAIN mechanism will be disabled on non-SSL
      connections. This security feature can be overwritten by setting
      </p><pre class="programlisting">secureOnlyMechanisms = []</pre><p> in the authentication provider
      section of the config.json.
      </p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>
          Changing the secureOnlyMechanism is a breach of security and might cause passwords to be
          transfered in the clear. Use at your own risk!
        </p></div><p>
    </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="Java-Broker-Security-LDAP-Provider"></a>8.1.1.&#160;Simple LDAP</h3></div></div></div><p> The Simple LDAP authenticates connections against a Directory (LDAP). </p><p> To create a SimpleLDAPAuthenticationProvider the following mandatory fields are required: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="emphasis"><em>LDAP server URL</em></span> is the URL of the server, for example,
                <code class="literal">ldaps://example.com:636</code></p></li><li class="listitem"><p><span class="emphasis"><em>Search context</em></span> is the distinguished name of the search base
                object. It defines the location from which the search for users begins, for example,
                <code class="literal">dc=users,dc=example,dc=com</code></p></li><li class="listitem"><p><span class="emphasis"><em>Search filter</em></span> is a DN template to find an LDAP user entry by
                provided user name, for example, <code class="literal">(uid={0})</code></p></li></ul></div><p> Additionally, the following optional fields can be specified: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="emphasis"><em>LDAP context factory</em></span> is a fully qualified class name for the
                JNDI LDAP context factory. This class must implement the <a class="link" href="http://docs.oracle.com/javase/7/docs/api/javax/naming/spi/InitialContextFactory.html" target="_top">InitialContextFactory</a> interface and produce instances of <a class="link" href="http://docs.oracle.com/javase/7/docs/api/javax/naming/directory/DirContext.html" target="_top">DirContext</a>. If
                not specified a default value of <code class="literal">com.sun.jndi.ldap.LdapCtxFactory</code> is
                used.</p></li><li class="listitem"><p><span class="emphasis"><em>LDAP authentication URL</em></span> is the URL of LDAP server for
                performing "ldap bind". If not specified, the <span class="emphasis"><em>LDAP server URL</em></span> will
                be used for both searches and authentications.</p></li><li class="listitem"><p><span class="emphasis"><em>Truststore name</em></span> is a name of <a class="link" href="Java-Broker-Management-Managing-Truststores.html#Java-Broker-Management-Managing-Truststores-Attributes" title="7.12.2.&#160;Attributes">configured
                truststore</a>. 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).</p></li><li class="listitem"><p>Additional group information can be obtained from LDAP.
                There are two common ways of representing group membership in LDAP.
                </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">
                        User entries can hold membership information as attribute.
                        To use this the <span class="emphasis"><em>attribute name</em></span> that holds the group information must be specified.
                    </li><li class="listitem">
                        Group entries can hold a list of their members as attribute.
                        This can be used by specifying a <span class="emphasis"><em>search context</em></span> and <span class="emphasis"><em>search filter</em></span> to find all groups that the user should be considered a member of.
                        Typically this involves filtering groups by looking for the user's DN on a group attribute.
                        The <span class="emphasis"><em>subtree search scope</em></span> determines whether the search should include the subtree extending from the <span class="emphasis"><em>search context</em></span>.
                    </li></ul></div><p>
            </p></li></ul></div><p>
    </p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>In order to protect the security of the user's password, when using LDAP authentication,
            you must: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Use SSL on the broker's AMQP and HTTP ports to protect the password during
                    transmission to the Broker. The Broker enforces this restriction automatically on AMQP
                    and HTTP ports.</p></li><li class="listitem"><p>Authenticate to the Directory using SSL (i.e. ldaps://) to protect the password
                    during transmission from the Broker to the Directory.</p></li></ul></div></div><p> The LDAP Authentication Provider works in the following manner. If not in <code class="literal">bind
        without search</code> 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 <code class="literal">Search Context</code> 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. </p><p> If the search returns a match, or is configured in <code class="literal">bind without search</code>
        mode, the Authentication Provider then attempts to bind to the LDAP server with the given name
        and the password. Note that <a class="link" href="http://docs.oracle.com/javase/7/docs/api/javax/naming/Context.html#SECURITY_AUTHENTICATION" target="_top">simple security
            authentication</a> is used so the Directory receives the password in the clear.
    </p><p>
        By default, this authentication provider caches the result of an authentication for a short period of time. This
        reduces the load on the Directory service if the same credentials are presented frequently within a short
        period of time.  The length of time a result will be cached is defined by context variable
        <code class="literal">qpid.auth.cache.expiration_time</code> (default to 600 seconds).  The cache can be disabled by
        setting the context variable <code class="literal">qpid.auth.cache.size</code> to 0.
    </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="Java-Broker-Security-Kerberos-Provider"></a>8.1.2.&#160;Kerberos</h3></div></div></div><p> Kereberos Authentication Provider uses java GSS-API SASL mechanism to authenticate the
        connections. </p><p> Configuration of kerberos is done through system properties (there doesn't seem to be a
        way around this unfortunately). </p><pre class="programlisting">
    export JAVA_OPTS=-Djavax.security.auth.useSubjectCredsOnly=false -Djava.security.auth.login.config=qpid.conf
    ${QPID_HOME}/bin/qpid-server
  </pre><p>Where qpid.conf would look something like this:</p><pre class="programlisting">
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="&lt;name&gt;/&lt;host&gt;";
};</pre><p> 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). </p><p> 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. </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="Java-Broker-Security-OAuth2-Provider"></a>8.1.3.&#160;OAuth2</h3></div></div></div><p> This authentication provider allows users to login to the broker using credentials from a different service supporting OAuth2.
        Unfortunately, the <a class="link" href="https://www.rfc-editor.org/rfc/rfc6749.txt" target="_top">OAuth2 specification</a> does not define a standard why to get the identity of a subject from an access token.
        However, most OAuth2 implementations provide such functionality, although in different ways. Qpid handles this by providing so called IdentityResolvers.
        Currently the following services are supported:
        </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>CloudFoundry</p></li><li class="listitem"><p>Facebook</p></li><li class="listitem"><p>GitHub</p></li><li class="listitem"><p>Google</p></li><li class="listitem"><p>Microsoft Live</p></li></ul></div><p>
        Since all of these, with the exception of CloudFoundry, are tied to a specific service they come with defaults for the Scope, Authorization-, Token-, and IdentityResolverEndpoint.
    </p><p>
        By default, this authentication provider caches the result of an authentication for a short period of time. This
        reduces the load on the OAuth2 service if the same token is presented frequently within a short
        period of time.  The length of time a result will be cached is defined by context variable
        <code class="literal">qpid.auth.cache.expiration_time</code> (default to 600 seconds).  The cache can be disabled by
        setting the context variable <code class="literal">qpid.auth.cache.size</code> to 0.
    </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="Java-Broker-Security-External-Provider"></a>8.1.4.&#160;External (SSL Client Certificates)</h3></div></div></div><p> When <a class="link" href="Java-Broker-Management-Managing-Truststores.html" title="7.12.&#160;Truststores"> requiring SSL Client
        Certificates</a> 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. </p><p>
        <span class="bold"><strong>Note:</strong></span> The External Authentication Provider should typically
        only be used on the AMQP/HTTP ports, in conjunction with <a class="link" href="Java-Broker-Management-Managing-Ports.html" title="7.9.&#160;Ports">SSL client certificate
            authentication</a>. It is not intended for other uses and
        will treat any non-sasl authentication processes on these ports as successful with the given
        username.</p><p>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 <a class="link" href="Java-Broker-Security-AccessControlProviders.html" title="8.3.&#160;Access Control Providers">ACL</a> is required, as at the moment, ACL does not support commas in the user name.
    </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="Java-Broker-Security-Anonymous-Provider"></a>8.1.5.&#160;Anonymous</h3></div></div></div><p> 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. </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="Java-Broker-Security-ScramSha-Providers"></a>8.1.6.&#160;SCRAM SHA</h3></div></div></div><p>The SCRAM SHA Providers uses the Broker configuration itself to store the database of
        users. The users'
        passwords are stored as salted SHA digested password. This can be further encrypted using the
        facilities described in <a class="xref" href="Java-Broker-Security-Configuration-Encryption.html" title="8.4.&#160;Configuration Encryption">Section&#160;8.4, &#8220;Configuration Encryption&#8221;</a>.</p><p>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).</p><p>For these providers user credentials can be added, removed or changed using
        Management.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="Java-Broker-Security-Plain-Provider"></a>8.1.7.&#160;Plain</h3></div></div></div><p>The Plain Provider uses the Broker configuration itself to store the database of users
        (unlike the <a class="link" href="Java-Broker-Security.html#Java-Broker-Security-PlainPasswordFile-Provider" title="8.1.8.&#160;Plain Password File (Deprecated)">PlainPasswordFile</a>, there is no separate password file). As the name suggests,
        the user data (including password) is not hashed in any way. In order to provide encryption,
        the facilities described in <a class="xref" href="Java-Broker-Security-Configuration-Encryption.html" title="8.4.&#160;Configuration Encryption">Section&#160;8.4, &#8220;Configuration Encryption&#8221;</a>
        must be used.</p><p>For this provider user credentials can be added, removed or changed using
        Management.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="Java-Broker-Security-PlainPasswordFile-Provider"></a>8.1.8.&#160;Plain Password File <span class="emphasis"><em>(Deprecated)</em></span></h3></div></div></div><p><span class="emphasis"><em>This provider is deprecated and will be removed in a future release. The <a class="link" href="Java-Broker-Security.html#Java-Broker-Security-Plain-Provider" title="8.1.7.&#160;Plain">Plain</a> provider should be used
            instead.</em></span></p><p> 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.</p><p>For this provider user credentials can be added, removed or changed using
        Management.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="d0e4440"></a>8.1.8.1.&#160;Plain Password File Format</h4></div></div></div><p> 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.</p><pre class="programlisting">
# password file format
# &lt;user name&gt;: &lt;user password&gt;
guest:guest
        </pre></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="Java-Broker-Security-MD5-Provider"></a>8.1.9.&#160;MD5 Provider</h3></div></div></div><p> MD5 Provider  uses the Broker configuration itself to store the database of
        users (unlike the <a class="link" href="Java-Broker-Security.html#Java-Broker-Security-Base64MD5PasswordFile-Provider" title="8.1.10.&#160;Base64MD5 Password File (Deprecated)">Base64MD5 Password File</a>, there is no separate password file). Rather than store the
        unencrypted user password (as the Plain provider does) it instead stores the MD5 password
        digest.  This can be further encrypted using the
        facilities described in <a class="xref" href="Java-Broker-Security-Configuration-Encryption.html" title="8.4.&#160;Configuration Encryption">Section&#160;8.4, &#8220;Configuration Encryption&#8221;</a>.</p><p>For this provider user credentials can be added, removed or changed using
        Management.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="Java-Broker-Security-Base64MD5PasswordFile-Provider"></a>8.1.10.&#160;Base64MD5 Password File <span class="emphasis"><em>(Deprecated)</em></span></h3></div></div></div><p><span class="emphasis"><em>This provider is deprecated and will be removed in a future release.  The
        <a class="link" href="Java-Broker-Security.html#Java-Broker-Security-MD5-Provider" title="8.1.9.&#160;MD5 Provider">MD5</a> provider should be used
        instead.</em></span></p><p> 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.</p><p>For this provider user credentials can be added, removed or changed using
        Management.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="d0e4476"></a>8.1.10.1.&#160;Base64MD5 File Format</h4></div></div></div><p> 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.</p></div></div></div></div><div class="navfooter"><hr /><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="Java-Broker-Management-Managing-Plugin-HTTP.html">Prev</a>&#160;</td><td align="center" width="20%">&#160;</td><td align="right" width="40%">&#160;<a accesskey="n" href="Java-Broker-Security-Group-Providers.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">7.15.&#160;HTTP Plugin&#160;</td><td align="center" width="20%"><a accesskey="h" href="Apache-Qpid-Broker-J-Book.html">Home</a></td><td align="right" valign="top" width="40%">&#160;8.2.&#160;Group Providers</td></tr></table></div></div>