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.
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
-
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 };
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
, oroptional
. - 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
Example 5.3. artemis-roles.properties
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:
To allow users to… | Use this parameter… |
---|---|
Create addresses |
|
Delete addresses |
|
Create a durable queue under matching addresses |
|
Delete a durable queue under matching addresses |
|
Create a non-durable queue under matching addresses |
|
Delete a non-durable queue under matching addresses |
|
Send a message to matching addresses |
|
Consume a message from a queue bound to matching addresses |
|
Invoke management operations by sending management messages to the management address |
|
Browse a queue bound to the matching address |
|
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>
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>
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>
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 Management Console to run.
Procedure
-
Open the broker
BROKER_INSTANCE_DIR/etc/management.xml
configuration file. 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.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
-
On Linux:
5.4.2. Configuring Authentication Based on Roles
The role-access
element defines how roles are mapped to particular MBeans and their attributes and methods.
Procedure
-
Open the
BROKER_INSTANCE_DIR/etc/management.xml
configuration file. Search for the
role-access
element and edit the configuration:<role-access> <match domain="org.apache.activemq.artemis"> <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> </role-access>
-
In this case, a match is applied to any MBean attribute that has the domain name
org.apache.activemq.apache
. -
Access of the
view
,update
, oramq
role to a matching MBean attribute is controlled by which of thelist*
,get*
,set*
,is*
, and*
access methods that you add the role to. Themethod="*"
(wildcard) syntax is used as a catch-all way to specify every other method that is not listed in the configuration. Each of the access methods in the configuration is converted to an MBean method call. -
An invoked MBean method is matched against the methods listed in the configuration. For example, if you invoke a method called
listMessages
on an MBean with theorg.apache.activemq.artemis
domain, then the broker matches access back to the roles defined in the configuration for thelist
method. You can also configure access by using the full MBean method name. For example:
<access method="listMessages" roles="view,update,amq"/>
-
In this case, a match is applied to any MBean attribute that has the domain name
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
-
On Linux:
You can also match specific MBeans within a domain by adding a key
attribute that matches an MBean property. Shown below are some examples.
Mapping roles to all queues in a domain
This example shows how to use the key
attribute to map roles to all queues in a specified domain.
<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>
Mapping roles to a specific queue in a domain
This example shows how to use the key
attribute to map roles to a specific, named queue. In this example, the named queue is exampleQueue
.
<match domain="org.apache.activemq.artemis" key="queue=exampleQueue"> <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>
Mapping roles to all queue names that include a specified prefix
This example shows how to map roles to every queue whose name includes a specified prefix. In this example, a wildcard operator, *
, is used to match all queue names that start with the prefix example
.
<match domain="org.apache.activemq.artemis" key="queue=example*"> <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>
Mapping different roles to different sets of queues
You might want to map roles differently for different sets of the same attribute (for example, different sets of queues). To accomplish this, you can include multiple match
elements in your configuration file. In this case, however, it is possible to have multiple matches in the same domain.
For example, consider two <match>
elements configured as follows:
<match domain="org.apache.activemq.artemis" key="queue=example*">
and
<match domain="org.apache.activemq.artemis" key="queue=example.sub*">
Based on this configuration, a queue named example.sub.queue
in the org.apache.activemq.artemis
domain matches both wildcard key expressions. Therefore, the broker needs a prioritization scheme to decide which set of roles to map to the queue; the roles specified in the first match
element, or those specified in the second match
element.
When there are multiple matches in the same domain, the broker uses the following prioritization scheme when mapping roles:
- Exact matches are prioritized over wildcard matches
- Longer wildcard matches are prioritized over shorter wildcard matches
In this example, because the longer wildcard expression matches the queue name of example.sub.queue
most closely, the broker applies the role-mapping configured in the second <match>
element.
The default-access
element is a catch-all element for every method call that is not handled using the role-access
or whitelist
configurations. The default-access
and role-access
elements have the same match
element semantics.