IDM 7.4.1

Direct audit information to a JMS broker

This sample shows how to configure a Java Message Service (JMS) audit event handler to direct audit information to a JMS broker.

JMS is an API that supports Java-based peer-to-peer messages between clients. The JMS API can create, send, receive, and read messages, reliably and asynchronously. You can set up a JMS audit event handler to publish messages that comply with the Java Message Service Specification Final Release 1.1.

This sample demonstrates the use of the JMS audit event handler. In the sample you will set up communication between IDM and an external JMS Message Broker, as well as Apache ActiveMQ Artemis as the JMS provider and message broker.

JMS topics are not related to ForgeRock audit event topics. The ForgeRock implementation of JMS topics uses the publish/subscribe messaging domain to direct messages to the JMS audit event handler. In contrast, ForgeRock audit event topics specify categories of events.

Dependencies for JMS messaging

The JMS audit event handler requires Apache ActiveMQ Artemis and additional dependencies bundled with the ActiveMQ Artemis delivery. This section lists the dependencies, and where they must be installed in the IDM instance. If you use a different ActiveMQ version, you may need to download the corresponding dependencies separately.

  1. Download the following files:

  2. Unpack the ActiveMQ Artemis archive. For example:

    tar -zxvf ~/Downloads/apache-artemis-2.20.0-bin.tar.gz

  3. Create a temporary directory, and then change to that directory:

    mkdir ~/Downloads/tmp
cd ~/Downloads/tmp/

  4. Move the ActiveMQ Artemis Client and bnd JAR files to the temporary directory.

    mv ~/Downloads/apache-artemis-2.20.0/lib/client/artemis-jms-client-all-2.20.0.jar ~/Downloads/tmp/
mv ~/Downloads/biz.aQute.bnd-version.jar ~/Downloads/tmp/

  5. Create an OSGi bundle:

    1. In a text editor, create a BND file named activemq.bnd with the following contents, and save it to the current directory:

      version=2.20.0
Export-Package: *;version=${version}
Import-Package: !org.apache.log4j.*,!org.apache.log.*,!org.apache.avalon.framework.logger.*,!org.apache.avalon.framework.logger.*,!org.glassfish.json.*,!org.conscrypt.*,!org.apache.logging.*,!org.bouncycastle.jsse.*,!org.eclipse.*,!sun.security.*,!reactor.*,!org.apache.activemq.artemis.shaded.*,!com.aayushatharva.*,!com.github.luben.zstd,!com.jcraft.jzlib,!com.ning.compress,!com.ning.compress.lzf,!com.ning.compress.lzf.util,!com.oracle.svm.core.annotate,!lzma.*,!net.jpountz.*,*
Bundle-Name: ActiveMQArtemis :: Client
Bundle-SymbolicName: org.apache.activemq
Bundle-Version: ${version}

      Your tmp/ directory should now contain the following files:

      ls -1 ~/Downloads/tmp/
activemq.bnd
artemis-jms-client-all-2.20.0.jar
biz.aQute.bnd-version.jar

    2. In the same directory, create the OSGi bundle archive file. For example:

      java -jar biz.aQute.bnd-version.jar wrap \
--properties activemq.bnd \
--output artemis-jms-client-all-2.20.0-osgi.jar \
artemis-jms-client-all-2.20.0.jar

  6. Copy the resulting artemis-jms-client-all-2.20.0-osgi.jar file to the openidm/bundle directory:

    cp artemis-jms-client-all-2.20.0-osgi.jar /path/to/openidm/bundle/

Configure SSL for Apache ActiveMQ Artemis

For information on configuring Apache ActiveMQ Artemis security features, including SSL, refer to the ActiveMQ Artemis Documentation:

Configure a secure port for JMS messages

If you configured SSL for ActiveMQ Artemis, edit /path/to/openidm/samples/audit-jms/conf/audit.json, and replace the java.naming.provider.url:

"java.naming.provider.url" : "ssl://localhost:61617?daemon=true"

Start the ActiveMQ Artemis broker and IDM

With the appropriate bundles in the /path/to/openidm/bundle/ directory, you can start the ActiveMQ Artemis message broker, and then start IDM with the configuration for this sample.

For a full list of ActiveMQ Artemis setup options, refer to Using the Server in the ActiveMQ Artemis Documentation.

  1. Navigate to the directory where you unpacked the ActiveMQ Artemis binary and run the following command to create the Artemis broker:

    cd ~/Downloads/apache-artemis-2.20.0/bin
./artemis create fr-audit
Creating ActiveMQ Artemis instance at: /path/to/Downloads/apache-artemis-2.20.0/bin/fr-audit
...

  2. Start the newly created ActiveMQ Artemis broker:

    ./fr-audit/bin/artemis run

  3. Start IDM with the sample configuration:

    cd /path/to/openidm/
./startup.sh -p samples/audit-jms

    If you see the following error in the OSGi console, make sure that you have installed all the required dependencies and that you have started the ActiveMQ Artemis broker.

    SEVERE: Unable to create JmsAuditEventHandler 'jms': null

Configure and use a JMS consumer application

To take advantage of the ActiveMQ Artemis event broker, the JMS audit sample includes a Java consumer in the following directory: /path/to/openidm/samples/audit-jms/consumer/

  1. Assuming you have Apache Maven installed on the local system, you can compile the sample consumer with the following commands:

    cd /path/to/openidm/samples/audit-jms/consumer/
mvn clean install

    When the build process is complete, you’ll see a BUILD SUCCESS message:

    [INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 22.852 s
[INFO] Finished at: 2017-02-17T17:21:35+02:00
[INFO] Final Memory: 18M/148M
[INFO] ------------------------------------------------------------------------

    You might see [WARNING] messages during the build. As long as the messages end with BUILD SUCCESS, you can proceed with the JMS consumer application.

  2. When the consumer is compiled, run one of the following commands in the same directory to output audit messages related to IDM actions:

    • If you haven’t configured ActiveMQ Artemis on a secure port:

      mvn \
exec:java \
-Dexec.mainClass="consumer.src.main.java.SimpleConsumer" \
-Dexec.args="org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory tcp://localhost:61616"

    • If you’ve configured ActiveMQ Artemis on a secure port:

      MAVEN_OPTS="-Djavax.net.ssl.trustStore=/path/to/openidm/security/truststore" \
mvn \
exec:java \
-Dexec.mainClass="consumer.src.main.java.SimpleConsumer" \
-Dexec.args="org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory ssl://localhost:61617?daemon=true"
    Look for the message READY, listening for messages.

  3. Try some actions on IDM, either in a different console or in the admin UI. Watch the output in the SimpleConsumer console. For example:

    --------Message Wed 2022.05.11 at 15:47:07.007 PDT--------
{"auditTopic":"authentication","event":{"_id":"1c25a7d3-e04b-4e4f-ba02-dfca7b2b0dbd-2883","timestamp":"2022-05-11T22:47:06.375Z","eventName":"SESSION","transactionId":"1c25a7d3-e04b-4e4f-ba02-dfca7b2b0dbd-2880","trackingIds":["d7cd0e66-4d48-4e71-90ec-357c93938c82","1cab8896-9af1-431a-aee8-45b5696e8e52"],"userId":"openidm-admin","principal":["openidm-admin"],"entries":[{"moduleId":"JwtSession","result":"SUCCESSFUL","info":{"org.forgerock.authentication.principal":"openidm-admin"}}],"result":"SUCCESSFUL","provider":null,"method":"JwtSession"},"_topic":"authentication"}
----------------------------------------------------------