Chapter 31. Security

This chapter describes how security works with HornetQ and how you can configure it. To disable security completely simply set the security-enabled property to false in the hornetq-configuration.xml file.

For performance reasons security is cached and invalidated every so long. To change this period set the property security-invalidation-interval, which is in milliseconds. The default is 10000 ms.

31.1. Role based security for addresses

HornetQ contains a flexible role-based security model for applying security to queues, based on their addresses.

As explained in Chapter 8, Using Core, HornetQ core consists mainly of sets of queues bound to addresses. A message is sent to an address and the server looks up the set of queues that are bound to that address, the server then routes the message to those set of queues.

HornetQ allows sets of permissions to be defined against the queues based on their address. An exact match on the address can be used or a wildcard match can be used using the wildcard characters '#' and '*'.

Seven different permissions can be given to the set of queues which match the address. Those permissions are:

  • createDurableQueue. This permission allows the user to create a durable queue under matching addresses.

  • deleteDurableQueue. This permission allows the user to delete a durable queue under matching addresses.

  • createNonDurableQueue. This permission allows the user to create a non-durable queue under matching addresses.

  • deleteNonDurableQueue. This permission allows the user to delete a non-durable queue under matching addresses.

  • send. This permission allows the user to send a message to matching addresses.

  • consume. This permission allows the user to consume a message from a queue bound to matching addresses.

  • manage. This permission allows the user to invoke management operations by sending management messages to the management address.

For each permission, a list of roles who are granted that permission is specified. If the user has any of those roles, he/she will be granted that permission for that set of addresses.

Let's take a simple example, here's a security block from hornetq-configuration.xml or hornetq-queues.xml file:

<security-setting match="globalqueues.europe.#">
    <permission type="createDurableQueue" roles="admin"/>
    <permission type="deleteDurableQueue" roles="admin"/>
    <permission type="createNonDurableQueue" roles="admin, guest, europe-users"/>
    <permission type="deleteNonDurableQueue" roles="admin, guest, europe-users"/>
    <permission type="send" roles="admin, europe-users"/>
    <permission type="consume" roles="admin, europe-users"/>

The '#' character signifies "any sequence of words". Words are delimited by the '.' character. For a full description of the wildcard syntax please see Chapter 13, Understanding the HornetQ Wildcard Syntax. The above security block applies to any address that starts with the string "globalqueues.europe.":

Only users who have the admin role can create or delete durable queues bound to an address that starts with the string "globalqueues.europe."

Any users with the roles admin, guest, or europe-users can create or delete temporary queues bound to an address that starts with the string "globalqueues.europe."

Any users with the roles admin or europe-users can send messages to these addresses or consume messages from queues bound to an address that starts with the string "globalqueues.europe."

The mapping between a user and what roles they have is handled by the security manager. HornetQ ships with a user manager that reads user credentials from a file on disk, and can also plug into JAAS or JBoss Application Server security.

For more information on configuring the security manager, please see Section 31.4, “Changing the security manager”.

There can be zero or more security-setting elements in each xml file. Where more than one match applies to a set of addresses the more specific match takes precedence.

Let's look at an example of that, here's another security-setting block:

<security-setting match="globalqueues.europe.orders.#">
    <permission type="send" roles="europe-users"/>
    <permission type="consume" roles="europe-users"/>

In this security-setting block the match 'globalqueues.europe.orders.#' is more specific than the previous match 'globalqueues.europe.#'. So any addresses which match 'globalqueues.europe.orders.#' will take their security settings only from the latter security-setting block.

Note that settings are not inherited from the former block. All the settings will be taken from the more specific matching block, so for the address 'globalqueues.europe.orders.plastics' the only permissions that exist are send and consume for the role europe-users. The permissions createDurableQueue, deleteDurableQueue, createNonDurableQueue, deleteNonDurableQueue are not inherited from the other security-setting block.

By not inheriting permissions, it allows you to effectively deny permissions in more specific security-setting blocks by simply not specifying them. Otherwise it would not be possible to deny permissions in sub-groups of addresses.

31.2. Secure Sockets Layer (SSL) Transport

When messaging clients are connected to servers, or servers are connected to other servers (e.g. via bridges) over an untrusted network then HornetQ allows that traffic to be encrypted using the Secure Sockets Layer (SSL) transport.

For more information on configuring the SSL transport, please see Chapter 16, Configuring the Transport.

31.3. Basic user credentials

HornetQ ships with a security manager implementation that reads user credentials, i.e. user names, passwords and role information from an xml file on the classpath called hornetq-users.xml. This is the default security manager.

If you wish to use this security manager, then users, passwords and roles can easily be added into this file.

Let's take a look at an example file:

<configuration xmlns="urn:hornetq" 
    xsi:schemaLocation="urn:hornetq ../schemas/hornetq-users.xsd ">
    <defaultuser name="guest" password="guest">
        <role name="guest"/>
    <user name="tim" password="marmite">
        <role name="admin"/>      
    <user name="andy" password="doner_kebab">
        <role name="admin"/>
        <role name="guest"/>
    <user name="jeff" password="camembert">
        <role name="europe-users"/>
        <role name="guest"/>

The first thing to note is the element defaultuser. This defines what user will be assumed when the client does not specify a username/password when creating a session. In this case they will be the user guest and have the role also called guest. Multiple roles can be specified for a default user.

We then have three more users, the user tim has the role admin. The user andy has the roles admin and guest, and the user jeff has the roles europe-users and guest.

31.4. Changing the security manager

If you do not want to use the default security manager then you can specify a different one by editing the file hornetq-beans.xml (or hornetq-jboss-beans.xml if you're running JBoss Application Server) and changing the class for the HornetQSecurityManager bean.

Let's take a look at a snippet from the default beans file:

<bean name="HornetQSecurityManager" 
    <start ignored="true"/>
    <stop ignored="true"/>

The class is the default security manager that is used by the standalone server.

HornetQ ships with two other security manager implementations you can use off-the-shelf; one a JAAS security manager and another for integrating with JBoss Application Sever security, alternatively you could write your own implementation by implementing the interface, and specifying the classname of your implementation in the file hornetq-beans.xml (or hornetq-jboss-beans.xml if you're running JBoss Application Server).

These two implementations are discussed in the next two sections.

31.5. JAAS Security Manager

JAAS stands for 'Java Authentication and Authorization Service' and is a standard part of the Java platform. It provides a common API for security authentication and authorization, allowing you to plugin your pre-built implementations.

To configure the JAAS security manager to work with your pre-built JAAS infrastructure you need to specify the security manager as a JAASSecurityManager in the beans file. Here's an example:

&lt;bean name="HornetQSecurityManager"
    &lt;start ignored="true"/&gt;
    &lt;stop ignored="true"/&gt;

    &lt;property name="ConfigurationName"&gt;org.hornetq.jms.example.ExampleLoginModule&lt;/property&gt;
    &lt;property name="Configuration"&gt;
       &lt;inject bean="ExampleConfiguration"/&gt;
    &lt;property name="CallbackHandler"&gt;
       &lt;inject bean="ExampleCallbackHandler"/&gt;

Note that you need to feed the JAAS security manager with three properties:

  • ConfigurationName: the name of the LoginModule implementation that JAAS must use

  • Configuration: the Configuration implementation used by JAAS

  • CallbackHandler: the CallbackHandler implementation to use if user interaction are required

31.5.1. Example

See Section 11.1.19, “JAAS” for an example which shows how HornetQ can be configured to use JAAS.

31.6. JBoss AS Security Manager

The JBoss AS security manager is used when running HornetQ inside the JBoss Application server. This allows tight integration with the JBoss Application Server's security model.

The class name of this security manager is

Take a look at one of the default hornetq-jboss-beans.xml files for JBoss Application Server that are bundled in the distribution for an example of how this is configured.

31.6.1. Configuring Client Login

JBoss can be configured to allow client login, basically this is when a JEE component such as a Servlet or EJB sets security credentials on the current security context and these are used throughout the call. If you would like these credentials to be used by HornetQ when sending or consuming messages then set allowClientLogin to true. This will bypass HornetQ authentication and propgate the provided Security Context. If you would like HornetQ to authenticate using the propogated security then set the authoriseOnClientLogin to true also.

There is more info on using the JBoss client login module here


If messages are sent non blocking then there is a chance that these could arrive on the server after the calling thread has completed meaning that the security context has been cleared. If this is the case then messages will need to be sent blocking

31.7. Changing the username/password for clustering

In order for cluster connections to work correctly, each node in the cluster must make connections to the other nodes. The username/password they use for this should always be changed from the installation default to prevent a security risk.

Please see Chapter 30, Management for instructions on how to do this.