Chapter 9. Users and Roles

The broker supports a flexible role-based security model for applying security to queues based on their respective addresses. It is important to understand that queues are bound to addresses either one-to-one (for point-to-point style messaging) or many-to-one (for publish-subscribe style messaging). When a message is sent to an address the server looks up the set of queues that are bound to that address and routes the message to that set of queues.

In the default configuration (using PropertiesLoginModule), users and their assigned roles are defined in three configuration files:

login.conf
users.properties
roles.properties

Each of these files is discussed in more detail in the following sections.

The command-line interface allows users and roles to be added to these files via an interactive process.

Note

The users.properties file can contain hashed passwords for security.

9.1. Enabling Guest Access

A user who does not have login credentials, or whose credentials fail validation, can be granted limited access to the broker using a guest account.

A broker instance can be created with guest access enabled using the command-line switch; --allow-anonymous (the converse of which is --require-login).

The guest account is configured in the login.conf file.

Procedure

In the login.conf file, define a name and role for the guest account as follows:

activemq {
  org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule required
      org.apache.activemq.jaas.guest.user="guest" 1
      org.apache.activemq.jaas.guest.role="guest"; 2
};

1: Define the username assigned to anonymous users.
2: Define the role assigned to anonymous users.

The guest login module allows users without credentials (and, depending on how it is configured, possibly also users with invalid credentials) to access the broker. It is implemented by org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule.

It is common for the guest login module to be used in conjunction with another login module, such as a properties login module. Read more about that use-case in the Section 10.1.4, “Using Multiple Login Modules” section.

9.2. Adding Users

When basic username and password validation is required, use the Properties login module to define it. This login module checks the user’s credentials against a set of local property files.

Users and their corresponding passwords are listed in the users.properties file. The available roles and the users who are assigned those roles are defined in the roles.properties file.

Both of these files are referenced in the login.config file.

By default, the location and name of login.config is specified on the command line which is set by BROKER_INSTANCE_DIR/etc/artemis.profile on Red Hat Enterprise Linux and BROKER_INSTANCE_DIR\artemis.profile.cmd on Windows.

See Oracle’s tutorial for more information on how to use login.config.

Example 9.1. login.conf

activemq { 1
    org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule required 2 3
        org.apache.activemq.jaas.properties.user="users.properties"; 4
        org.apache.activemq.jaas.properties.role="roles.properties";
};

1: An alias for a configuration. In this section the alias used is activemq. Substitute another in your environment.
2: The implementation class (org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule).
3: A flag which indicates whether the success of the LoginModule is `required, requisite, sufficient, or optional.
4: A list of configuration options specific to the login module implementation.

Below is an explanation for each of the success states listed in the previous example:

Required: The LoginModule is required to succeed and authentication continues to proceed down the LoginModule list regardless of success or failure.
Requisite: The LoginModule is required to succeed. A failure immediately returns control to the application and authentication does not proceed down the LoginModule list.
Sufficient: The LoginModule is not required to succeed. If it is successful, control returns to the application and authentication does not proceed further. If it fails, the authentication attempt proceeds down the LoginModule list.
Optional: The LoginModule is not required to succeed. Authentication continues down the LoginModules list regardless of success or failure.

More information on these flags and the authentication process is available in the Oracle documentation.

Example 9.2. user.properties

user1=secret 1
user2=swordfish 2
user3=myPassword 3

1: User1 has a password of secret.
2: User2 has a password of swordfish.
3: User3 has a password of myPassword.

Example 9.3. roles.properties

admin=user1,user2 1
developer=user3 2

1: User1 and user2 belong to the admin role.
2: User3 belongs to the developer role.

Note

If necessary, add your security domain alias (in this instance, activemq) to the bootstrap.xml file as shown below:

<jaas-security domain="activemq"/>

9.3. Setting Permissions

Permissions are defined against the queues based on their address via the <security-setting> element in broker.xml. Multiple instances of <security-setting> can be defined in <security-settings>. An exact match on the address can be used or a wildcard match can be used using the wildcard characters # and *.

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

Table 9.1. Permissions
To allow users to…	Use this parameter…
Create addresses	`createAddress`
Delete addresses	`deleteAddress`
Create a durable queue under matching addresses	`createDurableQueue`
Delete a durable queue under matching addresses	`deleteDurableQueue`
Create a non-durable queue under matching addresses	`createNonDurableQueue`
Delete a non-durable queue under matching addresses	`deleteNonDurableQueue`
Send a message to matching addresses	`send`
Consume a message from a queue bound to matching addresses	`consume`
Invoke management operations by sending management messages to the management address	`manage`
Browse a queue bound to the matching address	`browse`

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

9.3.1. Configuring Message Production for a Single Address

To define sending permissions for a single address, a configuration similar to the example shown below is used:

<security-settings>
    <security-setting match="queue1"> 1
        <permission type="send" roles="producer"/> 2
    </security-setting>
</security-settings>

1: Messages sent to this queue get the nominated permissions.
2: The permissions applied to messages in the specified queue.

In the above example, members of the producer role have send permissions on queue1.

9.3.2. Configuring Message Consumption for a Single Address

To define consuming permissions for a single address, a configuration similar to the example shown below is used:

<security-settings>
    <security-setting match="queue1"> 1
        <permission type="consume" roles="consumer"/> 2
    </security-setting>
</security-settings>

1: Messages sent to this queue get the nominated permissions.
2: The permissions applied to messages in the specified queue.

In the above example, members of the consumer role have consume permissions on queue1.

9.3.3. Configuring Complete Access on All Addresses

To allow complete access to addresses and and queues, a configuration similar to the example shown below is used.

<security-settings>
    <security-setting match="#"> 1
        <permission type="createDurableQueue" roles="guest"/>
        <permission type="deleteDurableQueue" roles="guest"/>
        <permission type="createNonDurableQueue" roles="guest"/>
        <permission type="deleteNonDurableQueue" roles="guest"/>
        <permission type="createAddress" roles="guest"/>
        <permission type="deleteAddress" roles="guest"/>
        <permission type="send" roles="guest"/>
        <permission type="browse" roles="guest"/>
        <permission type="consume" roles="guest"/>
        <permission type="manage" roles="guest"/>
    </security-setting>
</security-settings>

1: A wildcard setting to apply to all queues.

In the above configuration, all permissions are granted to members of the guest role on all queues. This can be be useful in a development scenario where anonymous authentication was configured to assign the guest role to every user.

For information about more complex use cases see Configuring Multiple Permissions for Addresses.

Chapter 9. Users and Roles

9.1. Enabling Guest Access

9.2. Adding Users

9.3. Setting Permissions

9.3.1. Configuring Message Production for a Single Address

9.3.2. Configuring Message Consumption for a Single Address

9.3.3. Configuring Complete Access on All Addresses

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links