SupportConsoleDevelopersStart a trialContact

Chapter 5. 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.config
  • artemis-users.properties
  • artemis-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 artemis-users.properties file can contain hashed passwords for security.

5.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.config file.

Procedure

  1. In the login.config 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 6.2.5, “Using Multiple Login Modules” section.

5.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 BROKER_INSTANCE_DIR/etc/artemis-users.properties file. The available roles and the users who are assigned those roles are defined in the BROKER_INSTANCE_DIR/etc/artemis-roles.properties file.

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

See the documentation from your Java vendor for more information on JAAS. For example, Oracle has a tutorial on configuring login.config.

Example 5.1. login.config

activemq { 1
    org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule required 2 3
        org.apache.activemq.jaas.properties.user="artemis-users.properties"; 4
        org.apache.activemq.jaas.properties.role="artemis-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 5.2. artemis-users.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 5.3. artemis-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"/>

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

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

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

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

5.3.4. Configuring a Queue with a User

The queue is assigned the username of the connecting client when it is auto-created. This is exposed as metadata on the queue. It is exposed by JMX and in the consoleThe queue is assigned the username of the connecting client when it is auto-created. This is exposed as metadata on the queue. It is exposed by JMX and in the console

You can configure a user on a pre-defined queue in broker.xml

To define a user for a queue, use a configuration similar to the example shown below: 

<address name="ExempleQueue">
    <anycast>
       <queue name="ExampleQueue" user="admin" />
    </anycast>
</address>
Note

Configuring a user on a queue does not change any of the security semantics for that queue, it is only used for metadata on that queue.

5.4. Setting Role Based Access Control

Role-based access control (RBAC) is used to restrict access to the attributes and methods of MBeans. RBAC enables administrators to grant the correct level of access to all users like web console, management interface, core messages, and so on based on their role. RBAC is configured using the authorization element in the BROKER_INSTANCE_DIR/etc/management.xml configuration file. Within the authorization element, you can configure Whitelist, default-access, and role-access sub-elements.

Prerequisites

You must first set up roles and add users to configure RBAC.

5.4.1. Configuring Whitelist Element for Bypassing the Authentication

A whitelist is a set of pre-approved domains or MBeans that do not require user authentication. You can provide a whitelist of domains or list of MBeans or both that must bypass the authentication. For example, you can use whitelist element for any MBeans that are needed by the AMQ Console to run.

Procedure

  1. Open the broker BROKER_INSTANCE_DIR/etc/management.xml configuration file.

  2. Search for the whitelist element and edit the configuration: 

    <whitelist>
   <entry domain="hawtio"/> 1
</whitelist>
    1
    MBean of this domain will bypass the authentication.

    In this example, any MBean with the domain hawtio will be allowed access without authentication. You can also use wildcard entries like <entry domain="hawtio" key="type=*"/> for the MBean properties to match.

  3. Start or restart the broker by entering the following command:

    • On Linux: BROKER_INSTANCE_DIR/bin/artemis run
    • On Windows: BROKER_INSTANCE_DIR\bin\artemis-service.exe start

5.4.2. Configuring Authentication Based on Roles

The role-access method defines how roles are mapped to particular MBeans and their attributes and methods.

Procedure

  1. Open the BROKER_INSTANCE_DIR/etc/management.xml configuration file.

  2. Search for the role-access element and edit the configuration: 

    <role-access>
    <match domain="org.apache.activemq.artemis"> 1
       <access method="list*" roles="view,update,amq"/> 2
       <access method="get*" roles="view,update,amq"/>
       <access method="is*" roles="view,update,amq"/>
       <access method="set*" roles="update,amq"/>
       <access method="*" roles="amq"/>
    </match>
</role-access>
    1
    A match will be applied to any MBean attribute that has the domain name org.apache.activemq.apache.
    2
    Specified roles can invoke the listed methods.
    Important

    === You must ensure that the order of the individual lines in the configuration is as per the template. Any change in the line indentation leads to changes in the semantics of the assigned privileges. For example, if you move the line <access method="*" roles="amq,guest"/> inside the <role-access> tag from last position to the first, it changes the semantics of applied privileges. If used as the first line, it means grant access to everything to these roles with the exception of following specific cases. If used as the last line, it means grant access to everything to these roles (default). ===

    Here, the specific tasks like list*, get*, set*, is and * are specified using the access method. The invoked method is matched against the methods listed in the configuration. The user is assigned the roles given for the best matching method. For example, if you try the invoke a method called listMessages on an MBean with the org.apache.activemq.artemis domain, then it would match the access with the method of list. You can also explicitly configure this by using the full method name like the following:

    <access method="listMessages" roles="view,update,amq"/>.

  3. Start or restart the broker by entering the following command:

    • On Linux: BROKER_INSTANCE_DIR/bin/artemis run
    • On Windows: BROKER_INSTANCE_DIR\bin\artemis-service.exe start

You can also match specific MBeans within a domain by adding a key attribute that matches an MBean property. For example, 

<match domain="org.apache.activemq.artemis" key="subcomponent=queues">
   <access method="list*" roles="view,update,amq"/>
   <access method="get*" roles="view,update,amq"/>
   <access method="is*" roles="view,update,amq"/>
   <access method="set*" roles="update,amq"/>
   <access method="*" roles="amq"/>
</match>

Access to MBean attributes are converted to method calls, so these are controlled using the list*, set*, get*, and is* syntax. The * (wildcard) syntax is used as a catch-all for every other method that is not listed in the configuration.

Note

The default-access element is mainly the catch-all for every method call that is not handled using the role-access configuration. The default-access and role-access have the same match element semantics.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.