--- title: JmsAuditEventHandler description: The Java Message Service (JMS) is a Java API for sending asynchronous messages between clients. It wraps audit events in JMS messages and publishes them in a JMS broker, which then delivers the messages to the appropriate destination. component: pinggateway version: 2026 page_id: pinggateway:reference:JmsAuditEventHandler canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/JmsAuditEventHandler.html revdate: 2025-10-15T18:45:22Z section_ids: JmsAuditEventHandler-usage: Usage JmsAuditEventHandler-conf: Configuration jms-example: Example JmsAuditEventHandler-moreinfo: More information --- # JmsAuditEventHandler | | | | - | ------------------------------------------------------------------ | | | This object is deprecated. Use an alternative audit event handler. | The Java Message Service (JMS) is a Java API for sending asynchronous messages between clients. It wraps audit events in JMS messages and publishes them in a JMS broker, which then delivers the messages to the appropriate destination. The JMS API architecture includes a *JMS provider* and *JMS clients*, and supports the *publish/subscribe* messaging pattern. Learn more in [Basic JMS API Concepts](https://docs.oracle.com/javaee/6/tutorial/doc/bncdx.html). The JMS audit event handler doesn't support queries. To support queries, also enable a second handler that supports queries. The JMS audit event handler supports JMS communication, based on the following components: * JMS message broker .jar files, to provide clients with connectivity, message storage, and message delivery functionality. Add the .jar files to the configuration as follows: * Create the directory `$HOME/.openig/extra`, where `$HOME/.openig` is the instance directory, and add .jar files to the directory. * JMS messages. * Destinations, maintained by a message broker. A destination can be a JMS topic, using [publish/subscribe](https://docs.oracle.com/javaee/6/tutorial/doc/bncdx.html#bnced) to take the JSON for an audit event, wrap it into a JMS TextMessage, and send it to the broker. * JMS clients, to produce and/or receive JMS messages. Depending on the configuration, some or all of these components are included in JMS audit log messages. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------- | | | The example in this section is based on [Apache ActiveMQ](https://activemq.apache.org/), but you can choose a different JMS message broker. | Declare the configuration in an audit service, as described in [AuditService](AuditService.html). ## Usage ```json { "name": string, "type": "AuditService", "config": { "config": {}, "eventHandlers": [ { "class": "org.forgerock.audit.handlers.jms.JmsAuditEventHandler", "config": { "name": configuration expression, "topics": [ configuration expression, ... ], "deliveryMode": configuration expression, "sessionMode": configuration expression, "jndi": { "contextProperties": map, "topicName": configuration expression, "connectionFactoryName": configuration expression } } }] } } ``` The values in this configuration object can use configuration expressions, as described in [Configuration and Runtime Expressions](Expressions.html#expression-runtime-configtime). ## Configuration You can find a list of properties in the `"config"` object in [JMS Audit Event Handler](https://docs.pingidentity.com/pingidm/8.1/audit-guide/audit-config-prop-jms.html) in the IDM documentation. * `"name"`: *configuration expression<[string](preface.html#definition-string)>, required* The name of the event handler. - `"topics"`: *array of configuration expression<[strings](preface.html#definition-string)>, required* One or more topics that this event handler intercepts. PingGateway can record the following audit event topics: * `access`: Log access audit events. Access audit events occur at the system boundary. They include the arrival of the initial HTTP request and departure of the final HTTP response. To record `access` audit events, configure the AuditService inline in a route or in the heap. * `notifications`: Log AM WebSocket notifications. To record `notifications` audit events, configure the AuditService inline in a route or in the heap. * customTopic: Log custom audit events. To create a topic for a custom audit event, include a JSON schema for the topic in your PingGateway configuration. To record custom audit events, configure the AuditService in the heap and refer to it from the route or subroutes. For an example of how to set up custom audit events, refer to [Record custom audit events](../configure/extending.html#audit-custom). * `"deliveryMode"`: *configuration expression<[string](preface.html#definition-string)>, required* Delivery mode for messages from a JMS provider. Set to `PERSISTENT` or `NON_PERSISTENT`. * `"sessionMode"`: *configuration expression<[string](preface.html#definition-string)>, required* Acknowledgement mode in sessions without transactions. Set to `AUTO`, `CLIENT`, or `DUPS_OK`. * `"contextProperties"`:\_[map](preface.html#definition-map), optional\_ Settings with which to populate the initial context. The map values are evaluated as configuration expression<[strings](preface.html#definition-string)>. The following properties are required when ActiveMQ is used as the message broker: * `java.naming.factory.initial` For example, `"org.apache.activemq.jndi.ActiveMQInitialContextFactory"`. To substitute a different JNDI message broker, change the JNDI context properties. * `java.naming.provider.url` For example, `"tcp://127.0.0.1:61616"`. To configure the message broker on a remote system, substitute the associated IP address. To set up SSL, set up keystores and truststores, and change the value of the `java.naming.provider.url` to: ```none ssl://127.0.0.1:61617?daemon=true&socket.enabledCipherSuites=SSL_RSA_WITH_RC4_128_SHA,SSL_DH_anon_WITH_3DES_EDE_CBC_SHA ``` * `topic.audit` For example, `"audit"`. To use the JMS resources provided by your application server, leave this field empty. The values for `topicName` and `connectionFactoryName` are then JNDI names that depend on the configuration of your application server. * `"topicName"`: *configuration expression<[string](preface.html#definition-string)>, required* JNDI lookup name for the JMS topic. For ActiveMQ, this property must be consistent with the value of `topic.audit` in `contextProperties`. * `"connectionFactoryName"`: *configuration expression<[string](preface.html#definition-string)>, required* JNDI lookup name for the JMS connection factory. ## Example In the following example, a JMS audit event handler delivers audit events in batches. The handler is configured to use the ActiveMQ JNDI message broker, on port 61616. You can find an example of setting up and testing this configuration in [Record access audit events with a JMS audit event handler](../maintenance-guide/auditing.html#audit-jms). ```json { "name": "30-jms", "MyCapture" : "all", "condition" : "${request.uri.path == '/activemq_event_handler'}", "heap": [ { "name": "AuditService", "type": "AuditService", "config": { "eventHandlers" : [ { "class" : "org.forgerock.audit.handlers.jms.JmsAuditEventHandler", "config" : { "name" : "jms", "topics": [ "access" ], "deliveryMode" : "NON_PERSISTENT", "sessionMode" : "AUTO", "jndi" : { "contextProperties" : { "java.naming.factory.initial" : "org.apache.activemq.jndi.ActiveMQInitialContextFactory", "java.naming.provider.url" : "tcp://am.example.com:61616", "topic.audit" : "audit" }, "topicName" : "audit", "connectionFactoryName" : "ConnectionFactory" } } } ], "config" : { } } } ], "auditService": "AuditService", "handler" : { "type" : "StaticResponseHandler", "config" : { "status" : 200, "headers" : { "Content-Type" : [ "text/plain; charset=UTF-8" ] }, "entity" : "Message from audited route" } } } ``` Source: [30-jms.json](../_attachments/config/routes/30-jms.json) ## More information [org.forgerock.audit.handlers.jms.JmsAuditEventHandler](../_attachments/apidocs/org/forgerock/audit/handlers/jms/JmsAuditEventHandler.html)