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. Learn more in Basic JMS API Concepts.
The JMS audit event handler doesn’t 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:
-
Create the directory
$HOME/.openig/extra, where$HOME/.openigis 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 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.
|
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
{
"name": string,
"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
You can find a list of properties in the "config" object in
JMS Audit Event Handler
in the IDM documentation.
"name": configuration expression<string>, required-
The name of the event handler.
"topics": array of configuration expression<strings>, 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, 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 PingGateway 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, refer to Record custom audit events.
-
"deliveryMode": configuration expression<string>, required-
Delivery mode for messages from a JMS provider. Set to
PERSISTENTorNON_PERSISTENT. "sessionMode": configuration expression<string>, required-
Acknowledgement mode in sessions without transactions. Set to
AUTO,CLIENT, orDUPS_OK. "contextProperties":_map, optional_-
Settings with which to populate the initial context.
The map values are evaluated as configuration expression<strings>.
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>, required-
JNDI lookup name for the JMS topic.
For ActiveMQ, this property must be consistent with the value of
topic.auditincontextProperties. "connectionFactoryName": configuration expression<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 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://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"
}
}
}