JmsAuditEventHandler
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. For more information, see Basic JMS API Concepts.
The JMS audit event handler does not support queries. To support queries, also enable a second handler that supports queries.
The ForgeRock 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:
For IG in standalone mode, create the directory
$HOME/.openig/extra, where$HOME/.openigis the instance directory: and add .jar files to the directory.For IG in web container mode, add .jar files to the web container classpath. For example, in Jetty use
/path/to/jetty/webapps/ROOT/WEB-INF/lib.
JMS messages.
Destinations, maintained by a message broker. A destination can be a JMS topic, using publish/subscribe to take the ForgeRock 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.
Important
The example in this section is based on Apache ActiveMQ, but you can choose a different JMS message broker.
Declare the configuration in an audit service, as described in "AuditService".
Usage
{
"type": "AuditService",
"config": {
"config": {},
"eventHandlers": [
{
"class": "org.forgerock.audit.handlers.jms.JmsAuditEventHandler",
"config": {
"name": configuration expression<string>,
"topics": [ configuration expression<string>, ... ],
"deliveryMode": configuration expression<string>,
"sessionMode": configuration expression<string>,
"jndi": {
"contextProperties": map,
"topicName": configuration expression<string>,
"connectionFactoryName": configuration expression<string>
}
}
}]
}
}The values in this configuration object can use configuration expressions, as described in "Configuration and Runtime Expressions".
Configuration
For a full list of properties in the "config" object, see JMS Audit Event Handler in IDM's Integrator's Guide.
"name": configuration expression<string>, requiredThe name of the event handler.
"topics": array of configuration expression<string>, requiredAn array of one or more topics that this event handler intercepts. IG can record the following audit event topics:
access: Log access audit events. Access audit events occur at the system boundary, and include the arrival of the initial request and departure of the final response.To record
accessaudit events, configure 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 IG configuration.
To record custom audit events, configure AuditService in the heap, and refer to it from the route or subroutes.
For an example of how to set up custom audit events, see "Recording Custom Audit Events".
"deliveryMode": configuration expression<string>, requiredDelivery mode for messages from a JMS provider. Set to
PERSISTENTorNON_PERSISTENT."sessionMode": configuration expression<string>, requiredAcknowledgement mode in sessions without transactions. Set to
AUTO,CLIENT, orDUPS_OK."contextProperties": map, optionalSettings with which to populate the initial context.
The following properties are required when ActiveMQ is used as the message broker:
java.naming.factory.initialFor example,
"org.apache.activemq.jndi.ActiveMQInitialContextFactory".To substitute a different JNDI message broker, change the JNDI context properties.
java.naming.provider.urlFor 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.urlto: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.auditFor example,
"audit".
To use the JMS resources provided by your application server, leave this field empty. The values for
topicNameandconnectionFactoryNameare then JNDI names that depend on the configuration of your application server."topicName": configuration expression<string>, requiredJNDI lookup name for the JMS topic.
For ActiveMQ, this property must be consistent with the value of
topic.auditincontextProperties."connectionFactoryName": configuration expression<string>, requiredJNDI 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. For an example of setting up and testing this configuration, see "Recording Access Audit Events in JMS".
{
"name": "30-jms",
"MyCapture" : "all",
"baseURI": "http://app.example.com:8081",
"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://openam.example.com:61616",
"topic.audit" : "audit"
},
"topicName" : "audit",
"connectionFactoryName" : "ConnectionFactory"
}
}
}
],
"config" : { }
}
}
],
"auditService": "AuditService",
"handler" : {
"type" : "StaticResponseHandler",
"config" : {
"status" : 200,
"headers" : {
"Content-Type" : [ "text/plain" ]
},
"reason" : "found",
"entity" : "Message from audited route"
}
}
}