--- title: Direct audit information to a JMS broker description: This sample shows how to configure a Java Message Service (JMS) audit event handler to direct audit information to a JMS broker. component: pingidm version: 8.1 page_id: pingidm:samples-guide:audit-jms canonical_url: https://docs.pingidentity.com/pingidm/8.1/samples-guide/audit-jms.html keywords: ["Samples", "JMS", "Audit"] section_ids: dependencies_for_jms_messaging: Dependencies for JMS messaging configure_ssl_for_apache_activemq_artemis: Configure SSL for Apache ActiveMQ Artemis audit-jms-secure-secure: Configure a secure port for JMS messages jms-sample-start: Start the ActiveMQ Artemis broker and IDM jms-sample-consume: Configure and use a JMS consumer application --- # Direct audit information to a JMS broker | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The [JMS](../audit-guide/configuring-topic-handlers.html#audit-jms-handler), [Repository](../audit-guide/configuring-topic-handlers.html#audit-repo-handler), [Router](../audit-guide/configuring-topic-handlers.html#audit-router-handler), and [Syslog](../audit-guide/configuring-topic-handlers.html#audit-syslog-handler) audit event handlers are [deprecated](../release-notes/deprecated-functionality.html#deprecation-audit-event-handlers) and will be removed in a future release of IDM. Use the [JSON audit event handler](../audit-guide/configuring-topic-handlers.html#audit-json-handler) or similar to export your data to a third-party audit framework, such as [Elastic Stack](https://www.elastic.co/elastic-stack). | 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](https://download.oracle.com/otndocs/jcp/7195-jms-1.1-fr-spec-oth-JSpec/). 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](http://activemq.apache.org/) as the JMS provider and message broker. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | JMS topics are not related to Ping audit event topics. The Ping implementation of JMS topics uses the [publish/subscribe messaging domain](https://docs.oracle.com/javaee/6/tutorial/doc/bncdx.html#bnced) to direct messages to the JMS audit event handler. In contrast, Ping 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: * [Apache ActiveMQ Artemis](https://activemq.apache.org/components/artemis/download/). | | | | - | ------------------------------------------- | | | This sample was tested with version 2.20.0. | * The most recent `bnd` JAR file from . | | | | - | ----------------------------------------------------------------------------------------------------------------- | | | The [bnd](https://bnd.bndtools.org/) utility lets you create OSGi bundles for libraries that do not support OSGi. | 2. Unpack the ActiveMQ Artemis archive. For example: ``` tar -xvf ~/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, download [ActiveMQ Artemis 2.2.0](https://archive.apache.org/dist/activemq/activemq-artemis/2.2.0/) and view the included documentation. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can also view the [latest Apache Artemis documentation](https://artemis.apache.org/components/artemis/documentation/latest/index.html), but the features described might differ from the version tested with IDM. | ### 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`: ```json "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](https://activemq.apache.org/components/artemis/documentation/latest/using-server.html) 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. [Set up DS](start-here.html#ldap-server-config) without importing any LDIF file or [select another repository](../install-guide/chap-repository.html) for the sample. 4. 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 | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Starting with IDM 8.1, the [legacy admin UI is deprecated](../release-notes/deprecated-functionality.html#legacy-admin-ui-deprecated) and is no longer bundled with IDM. New deployments should use the [Platform admin UI](../setup-guide/platform-admin-ui.html), which is the replacement for the legacy admin UI.Both UIs are available as separate downloads from the [Backstage download site](https://backstage.forgerock.com/downloads):- To install the Platform admin UI, follow the steps in [Install the Platform admin UI for standalone IDM](../setup-guide/platform-admin-ui.html). - To continue using the legacy admin UI, follow the steps in [Install the legacy admin UI](../setup-guide/legacy-admin-ui.html). | 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: ```none [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: ```json --------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"} ---------------------------------------------------------- ```