Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 4. Securing an Apache ActiveMQ Broker

Abstract

Apache ActiveMQ provides two layers of security: an SSL/TLS security layer, which can authenticate the broker to its clients, encrypt messages, and guarantee message integrity, and a JAAS security layer, which can authenticate clients to the broker. This chapter describes the approach you should take to enable both of these security layers, when the broker is deployed in the Red Hat JBoss Fuse OSGi container.

4.1. Tutorial I: SSL/TLS Security
Copy link

Overview
Copy link

The purpose of this tutorial is to show how you can deploy a secure Apache ActiveMQ broker in the OSGi container, where one or more of the broker's endpoints has SSL/TLS enabled. Unlike an insecure broker, you cannot deploy a secure broker simply by dropping its XML configuration file into the hot deploy directory, as described in section "Hot Deployment" in "Deploying into the Container". This is because a secure broker must be accompanied by X.509 certificates and their keys. It is necessary, therefore, to package the broker configuration file together with its certificates and keys in a single OSGi bundle.
This tutorial explains how to use the Maven build tool to create an OSGi bundle containing the secure broker's configuration and its accompanying certificates and keys. After deploying the broker into the OSGi container, you test it using the sample JMS clients from the standalone Apache ActiveMQ distribution (which you can obtain from the Red Hat JBoss Fuse download page).

Prerequisites
Copy link

The following prerequisites are needed for this tutorial:
  • Maven installation—Maven is a free, open source build tool from Apache. You can download the latest version from http://maven.apache.org/download.html (minimum is 2.2).
  • Internet connection—whilst performing a build, Maven dynamically searches external repositories and downloads the required artifacts on the fly. In order for this to work, your build machine must be connected to the Internet.
  • Apache ActiveMQ installation—the standalone installation of Apache ActiveMQ has some demonstration code that is not available in Red Hat JBoss Fuse. Download and install Apache ActiveMQ 5.8.0.redhat-60024 from fusesource.com.

Tutorial steps
Copy link

To configure SSL/TLS security for a broker deployed in the OSGi container, perform the following steps:
  1. the section called “Generate a Maven project”.
  2. the section called “Customize the POM file”.
  3. the section called “Install sample keystore files”.
  4. the section called “Configure the broker”.
  5. the section called “Build the broker bundle”.
  6. the section called “Deploy the broker bundle”.
  7. the section called “Configure the consumer and the producer clients”.
  8. the section called “Run the consumer with the SSL protocol”.
  9. the section called “Run the producer with the SSL protocol”.
  10. the section called “Uninstall the broker bundle”.

Generate a Maven project
Copy link

The maven-archetype-quickstart archetype creates a generic Maven project, which you can then customize for whatever purpose you like. To generate a Maven project with the coordinates, org.jbossfuse.example:esb-security, enter the following command: 
mvn archetype:create
-DarchetypeArtifactId=maven-archetype-quickstart
-DgroupId=org.jbossfuse.example
-DartifactId=esb-security
Copy to Clipboard Toggle word wrap
The result of this command is a directory, ProjectDir/esb-security, containing the files for the generated project.
Note
Be careful not to choose a group ID for your artifact that clashes with the group ID of an existing product! This could lead to clashes between your project's packages and the packages from the existing product (because the group ID is typically used as the root of a project's Java package names).

Customize the POM file
Copy link

You must customize the POM file in order to generate an OSGi bundle, as follows:
  1. Follow the POM customization steps described in section "Generating a Bundle Project" in "Deploying into the Container".
  2. In the configuration of the Maven bundle plug-in, modify the bundle instructions to import additional Java packages, as follows: 
    <project ... >
  ...
  <build>
    ...
      <plugin>
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-bundle-plugin</artifactId>
        <extensions>true</extensions>
        <configuration>
          <instructions>
            <Bundle-SymbolicName>
              ${project.artifactId}
            </Bundle-SymbolicName>
            <Import-Package>org.apache.activemq.xbean,
                            org.apache.activemq.spring,
                            org.apache.activemq.broker,
                            org.apache.activemq.security,
                            org.apache.activemq.jaas,
                            org.apache.activemq.pool,
                            org.apache.activemq.camel.component,
                            org.apache.camel.component.jms,
                            *</Import-Package>
          </instructions>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
</project>
    Copy to Clipboard Toggle word wrap
Note
Not all of these packages are required by the current tutorial. It is convenient, however, to add all of the packages required by the subsequent tutorials at this point.

Install sample keystore files
Copy link

The broker requires the following keystore files:
  • Key store containing broker's own certificate and private key—used to identify the broker during an SSL handshake.
  • Trust store containing CA certificate—used to verify that a received client certificate is correctly signed (strictly speaking, the trust store file is only needed by the broker, if the transport.needClientAuth options is set to true on the broker URI).
For this tutorial, you can use the demonstration certificates provided with the standalone version of Apache ActiveMQ. In the Maven project, create the following conf directory to store the broker's keystore files: 
ProjectDir/esb-security/src/main/resources/conf
Copy to Clipboard Toggle word wrap
Copy the broker.ks and broker.ts files from the Apache ActiveMQ standalone conf directory, ActiveMQInstallDir/conf, to the conf directory that you just created.
Warning
The demonstration broker key store and broker trust sture are provided for testing purposes only. Do not deploy these certificates in a production system. To set up a genuinely secure SSL/TLS system, you must generate custom certificates, as described in .

Configure the broker
Copy link

To configure the broker, create the following spring directory to store Spring XML files: 
ProjectDir/esb-security/src/main/resources/META-INF/spring
Copy to Clipboard Toggle word wrap
In the spring directory that you just created, use your favorite text editor to create the file, broker-spring.xml, containing the following XML configuration: 
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
       http://activemq.apache.org/schema/core http://activemq.apache.org/schema/core/activemq-core-5.4.0.xsd">

    <broker xmlns="http://activemq.apache.org/schema/core" brokerName="simple-spring">
        <sslContext>
            <sslContext
                keyStore="classpath:conf/broker.ks"
                keyStorePassword="password"
                trustStore="classpath:conf/broker.ts"
                trustStorePassword="password"
                />
        </sslContext>
        <transportConnectors>
            <transportConnector name="openwire" uri="ssl://localhost:61001"/>
        </transportConnectors>
    </broker>

</beans>
Copy to Clipboard Toggle word wrap
Note the following key aspects of the broker configuration:
  • The Openwire network connector is configured to use SSL, ssl://localhost:61001.
  • The key store and trust store file locations and passwords are specified by the broker's sslContext element.

Build the broker bundle
Copy link

Use Maven to build the broker bundle. Open a command prompt, switch the current directory to ProjectDir/esb-security, and enter the following command: 
mvn install
Copy to Clipboard Toggle word wrap
This command builds the broker bundle and installs it in your local Maven repository.

Deploy the broker bundle
Copy link

If you have not already done so, start up the Apache ServiceMix console (and container instance) by entering the following command in a new command prompt: 
servicemix
Copy to Clipboard Toggle word wrap
To deploy and activate the broker bundle, enter the following console command: 
JBossFuse:karaf@root> osgi:install -s mvn:org.jbossfuse.example/esb-security
Copy to Clipboard Toggle word wrap
The preceding command loads the broker bundle from your local Maven repository. You might need to configure the Mvn URL handler with the location of your local Maven repository, if the broker bundle cannot be found (see section "Mvn URL Handler" in "Deploying into the Container").

Configure the consumer and the producer clients
Copy link

To test the broker configured in the OSGi container, you are going to use the example consumer tool and producer tool supplied with the standalone version of Red Hat JBoss A-MQ.
Configure the consumer and the producer clients to pick up the client trust store. Edit the Ant build file, ActiveMQInstallDir/example/build.xml, and add the javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword JSSE system properties to the consumer target and the producer target as shown in the following example: 
<project ...>
    ...
        <target name="consumer" depends="compile" description="Runs a simple consumer">
        ...
                <java classname="ConsumerTool" fork="yes" maxmemory="100M">
                        <classpath refid="javac.classpath" />
                        <jvmarg value="-server" />
                    <sysproperty key="activemq.home" value="${activemq.home}"/>
                    <sysproperty key="javax.net.ssl.trustStore"
                                 value="${activemq.home}/conf/client.ts"/>
                    <sysproperty key="javax.net.ssl.trustStorePassword"
                                 value="password"/>
                        <arg value="--url=${url}" />
            ...                
                </java>
    </target>

        <target name="producer" depends="compile" description="Runs a simple producer">
        ...
                <java classname="ProducerTool" fork="yes" maxmemory="100M">
                        <classpath refid="javac.classpath" />
                        <jvmarg value="-server" />
                    <sysproperty key="activemq.home" value="${activemq.home}"/>
                    <sysproperty key="javax.net.ssl.trustStore"
                                 value="${activemq.home}/conf/client.ts"/>
                    <sysproperty key="javax.net.ssl.trustStorePassword"
                                 value="password"/>
                        <arg value="--url=${url}" />
            ...        
                </java>
        </target>
    ...
</project>
Copy to Clipboard Toggle word wrap
In the context of the Ant build tool, this is equivalent to adding the system properties to the command line.

Run the consumer with the SSL protocol
Copy link

To connect the consumer tool to the ssl://localhost:61001 endpoint (Openwire over SSL), change directory to ActiveMQInstallDir/example and enter the following command: 
ant consumer -Durl=ssl://localhost:61001 -Dmax=100
Copy to Clipboard Toggle word wrap
You should see some output like the following: 
Buildfile: build.xml
init:
compile:
consumer:
     [echo] Running consumer against server at $url = ssl://localhost:61001 for subject $subject = TEST.FOO
     [java] Connecting to URL: ssl://localhost:61001
     [java] Consuming queue: TEST.FOO
     [java] Using a non-durable subscription
     [java] We are about to wait until we consume: 100 message(s) then we will shutdown
Copy to Clipboard Toggle word wrap

Run the producer with the SSL protocol
Copy link

To connect the producer tool to the ssl://localhost:61001 endpoint, open a new command prompt, change directory to example and enter the following command: 
ant producer -Durl=ssl://localhost:61001 -Dmax=100
Copy to Clipboard Toggle word wrap
In the window where the consumer tool is running, you should see some output like the following: 
     [java] Received: Message: 0 sent at: Thu Feb 05 09:27:43 GMT 2009  ...
     [java] Received: Message: 1 sent at: Thu Feb 05 09:27:43 GMT 2009  ...
     [java] Received: Message: 2 sent at: Thu Feb 05 09:27:43 GMT 2009  ...
     [java] Received: Message: 3 sent at: Thu Feb 05 09:27:43 GMT 2009  ...
Copy to Clipboard Toggle word wrap

Uninstall the broker bundle
Copy link

To uninstall the broker bundle, you need to know its bundle ID, BundleID, in which case you can uninstall it by entering the following console command: 
JBossFuse:karaf@root> osgi:uninstall BundleID
Copy to Clipboard Toggle word wrap
If you are unsure of the broker's bundle ID, list the installed bundles using the osgi:list command, as follows: 
JBossFuse:karaf@root> osgi:list
Copy to Clipboard Toggle word wrap
Which should produce output like the following: 
...
[ 231] [Active     ] [            ] [       ] [   60] camel-jms (2.4.0.fuse-00-00)
[ 232] [Active     ] [            ] [       ] [   60] activemq-camel (5.4.0.fuse-00-00)
[ 245] [Installed  ] [            ] [       ] [   60] esb-security (1.0.0.SNAPSHOT)
Copy to Clipboard Toggle word wrap
From the preceding output, you can see that the esb-security bundle has the bundle ID, 245.
Back to top
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. Explore our recent updates.

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.

Theme

© 2025 Red Hat