Choose Audit Event Handlers

An audit event handler manages audit events, sends audit output to a defined location, and controls the output format. IDM provides a number of default audit event handlers, and audit event handlers for third-party log management tools.

Each audit event handler has a set of basic configuration properties. Specific audit event handlers have additional configuration properties.

The standard configuration for a new install includes the following handlers:

JsonAuditEventHandler

Default state: Enabled

Property: openidm.audit.handler.json.enabled

JsonStdoutAuditEventHandler

Default state: Disabled

Property: openidm.audit.handler.stdout.enabled

RepositoryAuditEventHandler

Default state: Disabled

Property: openidm.audit.handler.repo.enabled

Note

To change the enable state for any of these handlers, use property substitution.

Warning

ForgeRock recommends that you DO NOT configure an audit event handler that points to the same repo IDM uses (RepositoryAuditEventHandler), as this causes audit records to compete with IDM for resources on the database, which impacts performance.

List the Active Audit Event Handlers

This command returns the available audit event handlers, along with the audit configuration (in the conf/audit.json file):

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/audit?_action=availableHandlers"

The output includes the configured options for each audit event handler.

To view the audit configuration in the Admin UI, click Configure > System Preferences > Audit.

The following sections show how to configure the standard audit event handlers. For additional audit event handlers, see Audit Event Handler Configuration.

JSON Audit Event Handler

The JSON audit event handler logs events as JSON objects to a set of JSON files. This is the default handler for queries on the audit logs.

Note

Result paging can improve responsiveness when scanning large numbers of audit records through the IDM REST API. The default JSON audit handler does not support paging. If you need to page audit results, use a handler that does support paging, such as the "Repository Audit Event Handler".

The following excerpt of an audit.json file shows a sample JSON audit event handler configuration:

"eventHandlers" : [
    {
        "class" : "org.forgerock.audit.handlers.json.JsonAuditEventHandler",
        "config" : {
            "name" : "json",
            "enabled" : {
                "$bool" : "&{openidm.audit.handler.json.enabled|true}"
            },
            "logDirectory" : "&{idm.data.dir}/audit",
            "buffering" : {
                "maxSize" : 100000,
                "writeInterval" : "100 millis"
            },
            "topics" : [
                "access",
                "activity",
                "sync",
                "authentication",
                "config"
            ]
        }
    },

A JSON audit event handler configuration includes the following mandatory properties:

name

The audit event handler name (json).

logDirectory

The name of the directory in which the JSON log files should be written, relative to the working location. For more information on the working location, see "Specify the Startup Configuration".

You can use property value substitution to direct log files to another location on the filesystem. For more information, see "Property Value Substitution".

buffering - maxSize

The maximum number of events that can be buffered. The default (and minimum) number of buffered events is 100000.

buffering - writeInterval

The delay after which the file-writer thread is scheduled to run after encountering an empty event buffer. The default delay is 100 milliseconds.

topics

The list of topics for which audit events are logged.

One JSON file is created for each audit topic that is included in this list:

access.audit.json

activity.audit.json

authentication.audit.json

config.audit.json

sync.audit.json

Note

Reconciliations are available as an audit topic, but are not enabled by default. To enable auditing on reconciliations, add recon to the list of topics. This will add a recon.audit.json file to the audit directory.

If you want to get information about a reconciliation without enabling the audit topic, you can get similar details from the recon/assoc endpoint. For more information about recon association data, see "Viewing Reconciliation Association Details".

For a description of all the configurable properties of the JSON audit event handler, see "JSON Audit Event Handler Properties".

The following excerpt of an authentication.audit.json file shows the log message format for authentication events:

{
	"context": {
		"ipAddress": "0:0:0:0:0:0:0:1"
	},
	"entries": [{
		"moduleId": "JwtSession",
		"result": "FAILED",
		"reason": {},
		"info": {}
	},
 ...
	{
		"moduleId": "INTERNAL_USER",
		"result": "SUCCESSFUL",
		"info": {
			"org.forgerock.authentication.principal": "openidm-admin"
		}
	}],
	"principal": ["openidm-admin"],
	"result": "SUCCESSFUL",
	"userId": "openidm-admin",
	"transactionId": "94b9b85f-fbf1-4c4c-8198-ab1ff52ed0c3-24",
	"timestamp": "2016-10-11T12:12:03.115Z",
	"eventName": "authentication",
	"trackingIds": ["5855a363-a1e0-4894-a2dc-fd5270fb99d1"],
	"_id": "94b9b85f-fbf1-4c4c-8198-ab1ff52ed0c3-30"
} {
	"context": {
		"component": "internal/user",
		"roles": ["internal/role/openidm-admin", "internal/role/openidm-authorized"],
		"ipAddress": "0:0:0:0:0:0:0:1",
		"id": "openidm-admin",
		"moduleId": "INTERNAL_USER"
	}...

JSON Standard Output Audit Event Handler

Standard output is also known as stdout. A JSON stdout handler sends messages to standard output. The following code is an excerpt of the audit.json file, which depicts a sample JSON stdout audit event handler configuration:

{
    "class" : "org.forgerock.audit.handlers.json.stdout.JsonStdoutAuditEventHandler",
    "config" : {
        "name" : "stdout",
        "enabled" : {
            "$bool" : "&{openidm.audit.handler.stdout.enabled|false}"
        },
        "topics" : [
            "access",
            "activity",
            "sync",
            "authentication",
            "config"
        ]
    }
}...

CSV Audit Event Handler

The CSV audit event handler logs events to a comma-separated value (CSV) file.

Important

The CSV handler does not sanitize messages when writing to CSV log files.

Do not open CSV logs in spreadsheets and other applications that treat data as code.

The following excerpt of the audit.json file shows a sample CSV handler configuration:

"eventHandlers" : [
{
    "class" : "org.forgerock.audit.events.handlers.csv.CSVAuditEventHandler",
    "config" : {
        "name" : "csv",
        "logDirectory" : "&{idm.data.dir}/audit",
        "topics" : [ "access", "activity", "sync", "authentication", "config" ]
    }
}

The logDirectory indicates the name of the directory in which log files should be written, relative to the working location. For more information on the working location, see "Specify the Startup Configuration".

You can use property value substitution to direct logs to another location on the filesystem. For more information, see "Property Value Substitution".

If you set up a custom CSV handler, you may configure over 20 different properties, as described in "Common Audit Event Handler Properties".

Audit file names are fixed and correspond to the event being audited:

access.csv

activity.csv

authentication.csv

config.csv

recon.csv

sync.csv

Restrictions on Configuring the CSV Audit Handler in the UI

If you configure the CSV handler in the Admin UI, set at least the following properties:

The logDirectory, the full path to the directory with audit logs, such as /path/to/openidm/audit. You can substitute &{idm.install.dir} for /path/to/openidm.
Differing entries for the quote character, quoteChar and delimiter character, delimiterChar.
After you have set these options, do not change them in the Admin UI. Rather, rotate any CSV audit files and edit the configuration properties directly in conf/audit.json. Changing the properties in the Admin UI generates an error in the console.
If you enable the CSV tamper-evident configuration, include the keystoreHandlerName, or a filename and password. Do not include all three options.
Before including tamper-evident features in the audit configuration, set up the keys as described in Configure Keys to Protect Audit Logs.

Note

The signatureInterval property supports time settings in a human-readable format (default = 1 hour). Examples of allowable signatureInterval settings are:

3 days, 4 m
1 hour, 3 sec

Allowable time units include:

days, day, d
hours, hour, h
minutes, minute, min, m
seconds, second, sec, s

Configure Tamper Protection for CSV Audit Logs

Tamper protection can ensure the integrity of audit logs written to CSV files. You can activate tamper protection in the audit.json file directly, or by editing the CSV Audit Event Handler in the Admin UI.

Before you change the audit configuration for tamper protection, move or delete any current audit CSV files:

mv /path/to/openidm/audit/*.csv /tmp

Tamper protection requires keys in the default IDM keystore. If you have not already done so, import a certificate into the keystore, or create your own self-signed certificate:

Configure Keys to Protect Audit Logs

IDM includes a Java Cryptography Extension Keystore (JCEKS), keystore.jceks, in the /path/to/openidm/security directory.

Initialize a key pair using the RSA encryption algorithm, using the SHA256 hashing mechanism:

keytool \
 -genkeypair \
 -alias "Signature" \
 -dname CN=openidm \
 -keystore /path/to/openidm/security/keystore.jceks \
 -storepass changeit \
 -storetype JCEKS \
 -keypass changeit \
 -keyalg RSA \
 -sigalg SHA256withRSA

You can now set up a secret key, in Hash-based message authentication code, using the SHA256 hash function (HmacSHA256):

keytool \
 -genseckey \
 -alias "Password" \
 -keystore /path/to/openidm/security/keystore.jceks \
 -storepass changeit \
 -storetype JCEKS \
 -keypass changeit \
 -keyalg HmacSHA256 \
 -keysize 256

To configure tamper protection, add a security property to the CSV audit handler configuration in your conf/audit.conf file:

{
   "class" : "org.forgerock.audit.handlers.csv.CsvAuditEventHandler",
   "config" : {
   ...
      "security" : {
        "enabled" : true,
        "filename" : "",
        "password" : "",
        "keyStoreHandlerName" : "openidm",
        "signatureInterval" : "10 minutes"
      },
     ...

This excerpt shows a tamper-evident configuration where a signature is written to a new line in each CSV file, every 10 minutes. The signature uses the default keystore, configured in the install-dir/resolver/boot.properties file. The properties are described in "Common Audit Event Handler Properties".

To configure tamper protection in the Admin UI:

Select click Configure > System Preferences > Audit and select an existing CSV audit handler, or add a new one.
Scroll down to Security and set the keystore options.

When you have saved the configuration changes, you should see the following files in the /path/to/openidm/audit directory:

tamper-evident-access.csv
tamper-evident-access.csv.keystore
tamper-evident-activity.csv
tamper-evident-activity.csv.keystore
tamper-evident-authentication.csv
tamper-evident-authentication.csv.keystore
tamper-evident-config.csv
tamper-evident-config.csv.keystore
tamper-evident-recon.csv
tamper-evident-recon.csv.keystore
tamper-evident-sync.csv
tamper-evident-sync.csv.keystore

When you have configured tamper protection, you can periodically check the integrity of your log files:

Check Log File Integrity

The following command verifies audit files in the --archive directory (audit/), that belong to the access --topic, verified with the keystore.jceks keystore, using the CSV audit handler bundle, forgerock-audit-handler-csv-version.jar:

java -jar \
bundle/forgerock-audit-handler-csv-version.jar \
--archive audit/ \
--topic access \
--keystore security/keystore.jceks \
--password changeit

If there are changes to your tamper-evident-access.csv file, you'll see a message similar to:

      FAIL tamper-evident-access.csv-2016.05.10-11.05.43 The HMac at row 3 is not correct.

Note

Note the following restrictions on verifying CSV audit files:

You can only verify audit files that have already been rotated. You cannot verify an audit file that is currently being written to.

Verification of tampering is supported only for CSV audit files with the following format:

"formatting" : {
    "quoteChar" : "\"",
    "delimiterChar" : ",",
    "endOfLineSymbols" : "\n"
},

A tamper-evident audit configuration rotates files automatically and pairs the rotated file with the required keystore file. Files that are rotated manually cannot be verified, as the required keystore information is not appended.

Router Audit Event Handler

The router audit event handler logs events to any external or custom endpoint, such as system/scriptedsql or custom-endpoint/myhandler. It uses target-assigned values of _id.

A sample configuration for a router event handler is provided in the audit.json file in the openidm/samples/audit-jdbc/conf directory, and described in "About the Configuration Files". This sample directs log output to a JDBC repository. The audit configuration file (conf/audit.json) for the sample shows the following event handler configuration:

{
    "class": "org.forgerock.openidm.audit.impl.RouterAuditEventHandler",
    "config": {
        "name": "router",
        "topics" : [ "access", "activity", "sync", "authentication", "config" ],
        "resourcePath" : "system/auditdb"
    }
},

The resourcePath property in the configuration indicates that logs should be directed to the system/auditdb endpoint. This endpoint, and the JDBC connection properties, are defined in the connector configuration file (conf/provisioner.openicf-auditdb.json), as follows:

{
    "configurationProperties" : {
        "username" : "root",
        "password" : "password",
        "driverClassName" : "com.mysql.jdbc.Driver",
        "url" : "jdbc:mysql://&{openidm.repo.host}:&{openidm.repo.port}/audit",
        "autoCommit" : true,
        "jdbcDriver" : "com.mysql.jdbc.Driver",
        "scriptRoots" : ["&{idm.instance.dir}/tools"],
        "createScriptFileName" : "CreateScript.groovy",
        "testScriptFileName" : "TestScript.groovy",
        "searchScriptFileName" : "SearchScript.groovy"
    },
...

Include the correct URL or IP address of your remote JDBC repository in the boot.properties file for your project.

When JSON information is sent to the router audit event handler, the value of _id is replaced with eventId.

Repository Audit Event Handler

The repository audit event handler sends information to a JDBC repository. If you are using ForgeRock Directory Services (DS) as the repository, you cannot enable this audit event handler, because audit data cannot be stored in DS.

Warning

ForgeRock recommends that you DO NOT use the RepositoryAuditEventHandler, as this causes audit records to compete with IDM for resources on the database, which impacts performance.

Log entries are stored in the following tables of a JDBC repository:

auditaccess
auditactivity
auditauthentication
auditconfig
auditrecon
auditsync

You can use the repository audit event handler to generate reports that combine information from multiple tables.

Each of these JDBC tables maps to an object in the database table configuration file (repo.jdbc.json). The following excerpt of that file illustrates the mappings for the auditauthentication table:

"audit/authentication" : {
    "table" : "auditauthentication",
    "objectToColumn" : {
        "_id" : "objectid",
        "transactionId" : "transactionid",
        "timestamp" : "activitydate",
        "userId" : "userid",
        "eventName" : "eventname",
        "result" : "result",
        "principal" : {"column" : "principals", "type" : "JSON_LIST"},
        "context" : {"column" : "context", "type" : "JSON_MAP"},
        "entries" : {"column" : "entries", "type" : "JSON_LIST"},
        "trackingIds" : {"column" : "trackingids", "type" : "JSON_LIST"},
    }
},

The tables correspond to the topics listed in the audit.json file. For example:

{
    "class": "org.forgerock.openidm.audit.impl.RepositoryAuditEventHandler",
    "config": {
        "name": "repo",
        "topics" : [ "access", "activity", "sync", "authentication", "config" ]
    }
},

JMS Audit Event Handler

The Java Message Service (JMS) is a Java API for sending asynchronous messages between clients. IDM audit information can be handled by the JMS audit event handler, which sends information to message brokers. The message brokers can then forward that information to external log analysis systems.

The JMS audit event handler works with the following message brokers:

Apache ActiveMQ.
For a demonstration, see Direct Audit Information to a JMS Broker.
TIBCO Enterprise Message Service, as described in this chapter.

This implementation supports the publish/subscribe model. For more information, see Basic JMS API Concepts.

Important

The JMS audit event handler does not support queries. If you enable JMS, and need to query audit events, you must enable a second audit handler that supports queries. Specify that audit handler in the audit.json file with the handlerForQueries property, or in the Admin UI with the Use For Queries option.

The JMS audit event handler supports JMS communication, based on the following components:

A JMS message broker that provides clients with connectivity, along with message storage and message delivery functionality.
JMS messages that follow a specific format, described in "JMS Message Format".
Destinations external to IDM and the message broker. IDM (including the audit service) is a producer and not a destination. IDM sends messages to a topic in a message broker. Consumers (clients) subscribe to the message broker.
Note
JMS Topics are not the same as the ForgeRock audit event topics listed in your project's audit.json file. For more information about JMS topics, see the documentation on the publish/subscribe model. ForgeRock audit event topics specify categories of events (including access, activity, authentication, configuration, reconciliation, and synchronization). These event topics are published via the audit handler(s).

Dependencies for JMS Messaging

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

Download the following files:

ActiveMQ. This sample was tested with ActiveMQ Classic 5.16.1.
The most recent bnd JAR file from https://repo1.maven.org/maven2/biz/aQute/bnd/biz.aQute.bnd/. The bnd utility lets you create OSGi bundles for libraries that do not yet support OSGi.

Unpack the ActiveMQ archive. For example:

tar -zxvf ~/Downloads/apache-activemq-5.16.1-bin.tar

Create a temporary directory, move the ActiveMQ Client, and bnd JAR files to that directory, then change to that directory:

mkdir ~/Downloads/tmp
mv ~/Downloads/apache-activemq-5.16.1/lib/activemq-client-5.16.1.jar ~/Downloads/tmp/
mv biz.aQute.bnd-version.jar ~/Downloads/tmp/
cd ~/Downloads/tmp/

Create an OSGi bundle as follows:

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

version=5.16.1
Export-Package: *;version=${version}
Bundle-Name: ActiveMQ :: Client
Bundle-SymbolicName: org.apache.activemq
Bundle-Version: ${version}

Your tmp/ directory should now contain the following files:

ls ~/Downloads/tmp/
activemq-client-5.16.1.jar	activemq.bnd			biz.aQute.bnd-version.jar

In that same directory, create the OSGi bundle archive file as follows:

java -jar biz.aQute.bnd-version.jar \
wrap --properties activemq.bnd \
--output activemq-client-5.16.1-osgi.jar \
activemq-client-5.16.1.jar

Copy the resulting activemq-client-5.16.1-osgi.jar file to the openidm/bundle directory:
```
cp activemq-client-5.16.1-osgi.jar /path/to/openidm/bundle/
```

Copy the required dependencies from the extracted ActiveMQ archive to the openidm/bundle directory:

cp ~/Downloads/apache-activemq-5.16.1/lib/geronimo-j2ee-management_1.1_spec-1.0.1.jar /path/to/openidm/bundle/
cp ~/Downloads/apache-activemq-5.16.1/lib/hawtbuf-1.11.jar /path/to/openidm/bundle/
cp ~/Downloads/apache-activemq-5.16.1/lib/optional/jmdns-3.4.1.jar /path/to/openidm/bundle
cp ~/Downloads/apache-activemq-5.16.1/lib/optional/commons-net-3.7.2.jar /path/to/openidm/bundle

Configure the JMS Audit Event Handler

You can configure the JMS audit event handler in the Admin UI, or in your conf/audit.json file.

To configure the JMS audit event handler in the Admin UI:

Select Configure > System Preferences > Audit.
Under Event Handlers, select JmsAuditEventHandler > Add Event Handler.

The event handler configuration properties are discussed in this section. For a complete list of configuration options, see "JMS Audit Event Handler Properties".

To configure the audit event handler in the conf/audit.json file, see the sample configuration provided in /path/to/openidm/samples/audit-jms/conf/audit.json. The following excerpt of that file shows the JMS audit event handler configuration:

{
    "class" : "org.forgerock.audit.handlers.jms.JmsAuditEventHandler",
    "config" : {
        "name": "jms",
        "enabled" : true,
        "topics": [
            "access",
            "activity",
            "config",
            "authentication",
            "sync",
            "recon"
        ],
        "deliveryMode": "NON_PERSISTENT",
        "sessionMode": "AUTO",
        "batch": {
            "writeInterval": "1 second",
            "capacity": 1000,
            "maxBatchedEvents": 100
        },
        "jndi": {
            "contextProperties": {
                "java.naming.factory.initial" : "org.apache.activemq.jndi.ActiveMQInitialContextFactory",
                "java.naming.provider.url" : "tcp://127.0.0.1:61616?daemon=true",
                "topic.forgerock.idm.audit" : "forgerock.idm.audit"
            },
            "topicName": "forgerock.idm.audit",
            "connectionFactoryName": "ConnectionFactory"
        }
    }
}

In this sample configuration, the JMS audit event handler is enabled, with NON_PERSISTENT delivery of audit events in batches. The handler is configured to use the Apache ActiveMQ Java Naming and Directory Interface (JNDI) message broker, on port 61616.

For an example of how to configure Apache ActiveMQ, see Direct Audit Information to a JMS Broker.

If you substitute a different JNDI message broker, change the jndi.contextProperties accordingly. If you configure the JNDI message broker on a remote system, substitute the corresponding IP address.

Configure SSL for ActiveMQ

This configuration provides a connection to the ActiveMQ server instance with TLSv1.3.

In the directory where you unpacked ActiveMQ, edit the conf/activemq.xml file as follows:

In the <brokers> element, add an <sslContext>:

<broker xmlns="http://activemq.apache.org/schema/core" brokerName="localhost" dataDirectory="${activemq.data}">
    ...
    <sslContext>
        <sslContext keyStore="file:${activemq.conf}/broker.ks" keyStorePassword="password"/>
    </sslContext>
    ...
</broker>

In the <transportConnectors> element, add an ssl <transportConnector>:
```
<transportConnectors>
    ...
    <transportConnector name="ssl" uri="ssl://0.0.0.0:61617?transport.needClientAuth=false"/>
</transportConnectors>
```
Note
To enable mutual authentication, set transport.needClientAuth=true, and import the IDM server certificate into the ActiveMQ truststore (conf/broker.ts).

Delete the existing self-signed server certificate from the ActiveMQ keystore and truststore:

keytool \
-delete \
-keystore /path/to/activeMQ/conf/broker.ts \
-alias broker-localhost
Enter keystore password: password
keytool \
-delete \
-keystore /path/to/activeMQ/conf/broker.ks \
-alias broker-localhost
Enter keystore password: password

Generate a new self-signed server certificate for ActiveMQ:
```
keytool \
-genkey \
-keyalg RSA \
-alias broker-localhost \
-keystore /path/to/activeMQ/conf/broker.ks \
-storepass password \
-validity 360 \
-keysize 2048
```
Important
The CN in the generated self-signed certificate must match the hostname that you specify in the IDM JMS provider URL. If you are using localhost to connect to the broker, you must specify localhost when keytool prompts you for the first and last name. If the CN is not the same as the hostname, the server certificate validation will fail.

Export the ActiveMQ server certificate:

keytool \
-export \
-alias broker-localhost \
-file broker-localhost.key \
-keystore /path/to/activeMQ/conf/broker.ks
Enter keystore password: password
Certificate stored in file <broker-localhost.key>

Import the ActiveMQ server certificate into the IDM truststore:

keytool \
-import \
-alias activemq \
-keystore /path/to/openidm/security/truststore \
-file broker-localhost.key
Enter keystore password: changeit
Owner: CN=localhost, OU=Unknown, O=example.com, L=Unknown, ST=Unknown, C=Unknown
Issuer: CN=localhost, OU=Unknown, O=example.com, L=Unknown, ST=Unknown, C=Unknown
...
Trust this certificate? [no]: yes
Certificate was added to keystore

JMS Message Format

The following JMS message reflects the authentication of the openidm-admin user, logging into the Admin UI from a remote location, IP address 172.16.209.49.

{
  "event": {
    "_id": "134ee773-c081-436b-ae61-a41e8158c712-565",
    "trackingIds": [
      "4dd1f9de-69ac-4721-b01e-666df388fb17",
      "185b9120-406e-47fe-ba8f-e95fd5e0abd8"
    ],
  "context": {
    "id": "openidm-admin",
    "ipAddress": "172.16.209.49",
    "roles": [
      "internal/role/openidm-admin",
      "internal/role/openidm-authorized"
    ],
    "component": "internal/user"
  },
  "entries": [
    {
      "info": {
        "org.forgerock.authentication.principal": "openidm-admin"
      },
      "result": "SUCCESSFUL",
      "moduleId": "JwtSession"
    }
  ],
  "principal": [
    "openidm-admin"
  ],
    "result": "SUCCESSFUL",
    "userId": "openidm-admin",
    "transactionId": "134ee773-c081-436b-ae61-a41e8158c712-562",
    "timestamp": "2016-04-15T14:57:53.114Z",
    "eventName": "authentication"
  },
  "auditTopic": "authentication"
}

JMS, TIBCO, and SSL

You can integrate the JMS audit event handler with the TIBCO Enterprise Message Service.

You'll need to use two bundles from your TIBCO installation: tibjms.jar, and if you're setting up a secure connection, tibcrypt.jar. With the following procedure, you'll process tibjms.jar into an OSGi bundle:

Download the most recent bnd JAR file from https://repo1.maven.org/maven2/biz/aQute/bnd/biz.aQute.bnd/. The bnd utility lets you create OSGi bundles for libraries that do not yet support OSGi. If you have previously set up the ActiveMQ server, you may have already downloaded this file.

In the same directory, create a file named tibco.bnd, and add the following lines to that file:

version=8.3.0
Export-Package: *;version=${version}
Bundle-Name: TIBCO Enterprise Message Service
Bundle-SymbolicName: com/tibco/tibjms
Bundle-Version: ${version}

Add the tibco.jar file to the same directory.

Run the following command to create the bundle:

java \
-jar biz.aQute.bnd-version.jar wrap \
-properties tibco.bnd tibjms.jar

Rename the newly created tibjms.bar file to tibjms-osgi.jar, and copy it to the /path/to/openidm/bundle directory.
If you're configuring SSL, copy the tibcrypt.jar file from your TIBCO installation to the /path/to/openidm/bundle directory.

You also need to configure your project's audit.conf configuration file. The options are similar to those listed earlier in "Configure the JMS Audit Event Handler", except for the following jndi code block:

"jndi": {
   "contextProperties": {
      "java.naming.factory.initial" : "com.tibco.tibjms.naming.TibjmsInitialContextFactory",
      "java.naming.provider.url" : "tibjmsnaming://localhost:7222"
   },
   "topicName": "audit",
   "connectionFactoryName": "ConnectionFactory"
}

If your TIBCO server is on a remote system, substitute appropriately for localhost. If you're configuring a secure TIBCO installation, you'll want to configure a different code block:

"jndi": {
   "contextProperties": {
      "java.naming.factory.initial" : "com.tibco.tibjms.naming.TibjmsInitialContextFactory",
      "java.naming.provider.url" : "ssl://localhost:7243",
      "com.tibco.tibjms.naming.security_protocol" : "ssl",
      "com.tibco.tibjms.naming.ssl_trusted_certs" : "/path/to/tibco/server/certificate/cert.pem",
      "com.tibco.tibjms.naming.ssl_enable_verify_hostname" : "false"
   },
   "topicName": "audit",
   "connectionFactoryName": "SSLConnectionFactory"
}

Do not add the TIBCO certificate to the IDM truststore. The formats are not compatible.

When this configuration work is complete, don't forget to start your TIBCO server before starting IDM. For more information, see the TIBCO Enterprise Message Service Users's Guide.

Syslog Audit Event Handler

The Syslog audit event handler lets you log messages to a Syslog server, based on the Syslog Protocol.

You can configure the Syslog audit event handler in the Admin UI, or in your project's conf/audit.json file. The following excerpt from this file shows a possible Syslog configuration:

{
    "class" : "org.forgerock.audit.handlers.syslog.SyslogAuditEventHandler",
    "config" : {
        "protocol" : "UDP",
        "host" : "172.16.206.5",
        "port" : 514,
        "connectTimeout" : 5,
        "facility" : "KERN",
        "severityFieldMappings" : [
            {
                "topic" : "recon",
                "field" : "exception",
                "valueMappings" : {
                    "SEVERE" : "EMERGENCY",
                    "INFO" : "INFORMATIONAL"
                }
            }
        ],
        "buffering" : {
            "enabled" : false
        },
        "name" : "syslog1",
        "topics" : [
            "config",
            "activity",
            "authentication",
            "access",
            "recon",
            "sync"
        ],
        "enabled" : true
    }
}

The name, topics, and enabled options in the last part of the excerpt are common to all audit event handlers. For detailed information on the remaining properties, see "Syslog Audit Event Handler Properties".

Splunk Audit Event Handler

The Splunk audit event handler logs IDM events to a Splunk system.

Important

The Splunk audit event handler is deprecated in IDM 7.1. Support for its use will be removed in a future release.

Currently, the Splunk audit event handler can only be used to write events to Splunk. It cannot read or query audit events. You must therefore use the Splunk audit event handler in tandem with another event handler that is configured to handle queries.

Splunk enables you to define the structure of the incoming data. To use the event handler with IDM, create a new data Source Type in Splunk that will be associated with the incoming IDM log data. Because the audit event handler users the HTTP endpoints in Splunk, you must also enable a Splunk HTTP Event Collector. The HTTP Event Collector provides an authorization token that allows IDM to log events to Splunk.

The following procedure assumes a Splunk instance running on the same host as IDM. Adjust the instructions for your Splunk system:

Create a new source type:
1. In the Splunk UI, select Data > Source Types > New Source Type.
2. Provide a name for the source type, for example, openidm.
3. Under Event Breaks, specify how the incoming messages are split.
  The Splunk audit event handler supports bulk handing, so it passes multiple audit events to Splunk at a time, as a large JSON payload.
  Select Regex and enter ^{ to indicate how the bulk messages are separated.
4. Under Timestamp, click Auto to specify that Splunk should generate the timestamp, then click Save.
Create a new HTTP Event Collector.
1. Select Data Inputs > HTTP Event Collector > New Token.
2. Enter a Name that will be associated with this token, for example, openidm.
  Other fields are optional.
3. On the Input Settings screen, click Select under Source Type, then select Custom > openidm from the Select Source Type list.
4. Click Review, then Submit.
  Important
  Splunk provides the authorization token that you must add as the value of the authzToken property in the Splunk audit event handler configuration.
5. Make sure that the Global Settings for HTTP Event Collectors do not conflict with the settings you have configured for this IDM HTTP Event Collector.

To add the Splunk audit event handler to your IDM configuration, update your project's audit.json file or select Configure > System Preferences > Audit in the Admin UI, then select SplunkAuditEventHandler and click Add Event Handler.

The following excerpt of an audit.json file shows a sample Splunk audit event handler configuration. Adjust the connection settings and authzToken to match your Splunk system.

{
    "class" : "org.forgerock.audit.handlers.splunk.SplunkAuditEventHandler",
    "config" : {
        "connection" : {
            "useSSL" : false,
            "host" : "localhost",
            "port" : 8088
        },
        "buffering" : {
            "maxSize" : 10000,
            "writeInterval" : "100 ms",
            "maxBatchedEvents" : 500
        },
        "authzToken" : "87E9C00F-F5E6-47CF-B62F-E415A8142355",
        "name" : "Splunk",
        "topics" : [
            "config",
            "activity",
            "authentication",
            "access",
            "recon",
            "sync"
        ],
        "enabled" : true
    }
}

All properties are mandatory. For a complete list of the configurable properties for this audit event handler, see "Splunk Audit Event Handler Properties".