Skip to content

Home

Introduction

Development

Overview

IDEs

Services

Service manager

API Explorer

Remote ActiveMQ authentication and authorization

Haven't set up your remote ActiveMQ instance yet?

Read TORO's page on configuring a remote ActiveMQ instance to see the step-by-step procedures required to successfully deploy a stand-alone version of ActiveMQ and connect it to TORO Integrate.

Oftentimes, access to the message broker and its destinations must be restricted in order to prevent unwarranted incidences like the unauthorized deletion of data. Luckily, ActiveMQ provides "flexible and customizable security models"1 which make integrating with existing environment security policies easier.

Security in ActiveMQ is pluggable and achieved through the use of plugins from providers; two of the most common of which are the JAAS plugin and the simple authentication plugin2. The simple authentication plugin, as its name implies, will help us fulfill our authentication requirements. The JAAS plugin, on the other hand, allows us to manage users and groups without having to modify the broker.xml file directly (which is required for the simple authentication plugin).

In this guide, we will see how to set-up a remote ActiveMQ instance's authentication and authorization mechanisms through the aforementioned plugins. There are many other plugins you can use to configure your ActiveMQ instance's security; but at the moment, this is what TORO recommends for those who want to use remote ActiveMQ with TORO Integrate.

Authentication and authorization

Authentication is the process by which the user or system proves its identity to the server or client. This is typically done through the use of username-password combinations and other similar methods like one-time passwords sent to verified devices. Authentication does not determine the capabilities of the user; it only identifies and verifies the user or system requesting access.

Authorization, on the other hand, is the process that determines the privileges of the user or system on a secured resource. It works hand in hand with authentication.

Configuring the ActiveMQ server

The security settings of your ActiveMQ instance should depend on how your organization uses the broker. The procedures below will help you create a simple security configuration for your server using the JAAS authentication plugin and the authorization plugin; modify settings as needed.

  1. Go to ActiveMQ's configuration directory.

    1
    cd $activemq_home/conf
    
  2. Open the activemq.xml file and declare the runtimeConfigurationPlugin and the jaasAuthenticationPlugin. The runtimeConfigurationPlugin will enable modified broker settings to be applied on-the-go while the jaasAuthenticationPlugin will allow log-ins based on JMS username-password credentials sent by clients.

    1
    2
    3
    4
    <plugins>
        <runtimeConfigurationPlugin checkPeriod="1000" />
        <jaasAuthenticationPlugin configuration="activemq-domain" />
    </plugins>
    

    You may add this bit just underneath the <managementContext> ... </managementContext> section. Save and close the file.

    runtimeConfigurationPlugin

    This plugin is in charge of monitoring and applying changes from the broker.xml file to the running broker.

  3. Define the JAAS realm.

    Simply put, a realm is a 'database' of credentials, identifying the valid users of an application and their roles.3 To define our realm, we will use the login.config file.

    In this example, our login.config file will contain the snippet above, which will enable us to make use of Java property files to define users and groups.

    Reload

    The reload attribute which is now set to true will work with the runtimeConfigurationPlugin set earlier to give the broker the privilege to update broker settings on the fly.

    Save your configuration once done.

  4. Create and populate the Java property files specified in the preceding step. In this case, these files are named users.properties and groups.properties.

    users.properties, as its name implies, will contain the list of users and their passwords, declared using the format:

    1
    username=password
    

    groups.properties, on the other hand, will contain the list of groups and the users belonging to them. Groups will be declared using the format:

    1
    groupname=user_one,user_two,...
    
  5. Configure authorizationPlugin and define access privileges.

    Use <authorizationEntry /> elements to specify access privileges of previously defined groups for every destination (queue or topic). By entering the name of a group in a read attribute, you allow this group to browse and consume from the destination; write allows the sending of messages; and admin for the ability to create non-existent destinations lazily.

    For example:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    <plugins>
        <!-- ... -->
        <authorizationPlugin>
        <map>
            <authorizationMap>
                <authorizationEntries>
                    <authorizationEntry topic="jmsPrefix.statistics.>" read="$yourGroup" write="$yourGroup" admin="$yourGroup" />
                    <authorizationEntry topic="jmsPrefix.io.toro.integrate.>" read="$yourGroup" write="$yourGroup" admin="$yourGroup" />
                    <authorizationEntry queue="jmsPrefix.io.toro.integrate.>" read="$yourGroup" write="$yourGroup" admin="$yourGroup" />
                    <authorizationEntry topic="ActiveMQ.Advisory.>" read="$yourGroup" write="$yourGroup" admin="$yourGroup" />
                </authorizationEntries>
            </authorizationMap>
        </map>
        </authorizationPlugin>
    </plugins>
    

    Wildcards

    Use . to separate names in a path and create destination hierarchies; * to match any name in a path; and > to select destinations that match the path defined before the symbol.

    Authorization entry that affects all destinations?

    To create an entry that applies to all topics, the application needs be to configured to have a unique identifier that is prefixed on all of its topics; thereby making it easier to create an entry that matches all destinations using wildcards.

    jmsPrefix?

    jms.prefix is a TORO Integrate-specific property that is used to prevent destination name collisions. This property is relevant especially when managing multiple TORO Integrate instances. The jmsPrefix path in the example authorizationEntrys above is a modifiable value set via your TORO Integrate instance's application properties.

  6. Restart ActiveMQ.

    1. Go to the $activemq_home/bin directory.
    2. Run ActiveMQ on a separate terminal, using either the start (for Windows) or console (for Unix) command. This will allow us to check through ActiveMQ's logs easily.

      1
      2
      $activemq_home/bin/activemq start
      $activemq_home/bin/activemq console
      
  7. Verify if your new security configurations were applied. Your activemq.xml file should now roughly look like:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    <broker>
       <!-- ... -->
       <managementContext>
           <managementContext createConnector="false"/>
       </managementContext>
    
       <plugins>
           <jaasAuthenticationPlugin configuration="activemq-domain" />
           <runtimeConfigurationPlugin checkPeriod="1000" />
       <authorizationPlugin>
       <map>
           <authorizationMap>
               <authorizationEntries>
                   <authorizationEntry topic="jmsPrefix.statistics.>" read="admins" write="admins" admin="admins" />
                   <authorizationEntry topic="jmsPrefix.io.toro.integrate.>" read="admins" write="admins" admin="admins" />
                   <authorizationEntry queue="jmsPrefix.io.toro.integrate.>" read="admins" write="admins" admin="admins" />
                   <authorizationEntry topic="ActiveMQ.Advisory.>" read="admins" write="admins" admin="admins" />
               </authorizationEntries>
           </authorizationMap>
       </map>
       </authorizationPlugin>
       </plugins>
       <!-- ... -->
    </broker>
    

Configuring TORO Integrate

To let TORO Integrate connect to the remote ActiveMQ instance after updating its security policies, we must now edit its application properties. If you're running on a Server Edition of TORO Integrate, you can use the Server Admin UI to edit your instance's application properties; else, you must edit the .properties file directly which requires access to the machine's file system.

Write your configurations in override.properties instead of toro-integrate.properties

The toro-integrate.properties file contains the default configuration settings of TORO Integrate. Instead of directly editing this file and overwriting the default configuration, TORO Integrate allows developers to create an override.properties file. This file takes priority over the toro-integrate.properties file, overriding properties already present there; effectively allowing you to retain the default configuration while being able to customize it using a different file.

The steps below describe how to edit the override.properties file directly.

  1. Go to TORO Integrate's data directly.

    1
    cd <toro-integrate-home>/data
    
  2. Open and edit the override.properties4 file.

    1. Set the activemq.username and activemq.password properties' values so that it contains the credentials necessary to connect to your remote ActiveMQ instance.

      1
      2
      activemq.username=admin
      activemq.password=admin
      
    2. Edit the required jms.* properties so that TORO Integrate knows the parameters required to connect to the ActiveMQ server.

      1
      2
      3
      4
      5
      # Use 'remote-activemq' instead of 'activemq-external' for versions below v3.1
      jms.file=activemq-external
      jms.clientId=toro-integrate
      jms.url=tcp://<activemq-ip-address>:61616?closeAsync=true
      jms.prefix=your-prefix
      

      Value for jms.prefix

      It is recommended that you make the prefix match the username entered earlier in the users.properties file to easily track and refer to the topics and resources that will be generated by ActiveMQ.

  3. Restart your TORO Integrate instance to reflect the changes you've made. Check logs if necessary.

  4. Login to ActiveMQ and check if the topics were digested by the broker.

    1. Access and login as the administrator to ActiveMQ's web console.
    2. Go to the Topic panel to check.

As mentioned beforehand, you can use the Server Admin UI to edit the application properties instead. To do so:

  1. First, you must access TORO Integrate using your browser.
  2. Sign in.
  3. Go to the Configuration menu > Integrate Properties.

    Opening the web UI for editing application properties

From hereon, the following steps should be similar to the steps described above. Editing application properties this way automatically pushes the changes to override.properties instead of toro-integrate.properties.


  1. Snyder, Bosanac, and Davies. (2011). ActiveMQ in Action. Retrieved from Safari Books Online database. 

  2. Apache ActiveMQ. (n.d.). Apache ActiveMQ ™ -- Security. Retrieved January 4, 2019, from http://activemq.apache.org/security.html 

  3. Apache Tomcat. (n.d.). Realm Configuration HOW-TO. Retrieved January 6, 2019, from https://tomcat.apache.org/tomcat-8.0-doc/realm-howto.html#What_is_a_Realm? 

  4. Instead of override.properties, you can use a .properties file whose name or location differs using the integrate.override.properties property.