Log to a Service

The Common Audit framework supports logging access events to an external service:

Elasticsearch

An Elasticsearch audit event handler sends messages to an Elasticsearch server.

This audit handler is deprecated.

Before you enable the Elasticsearch handler, create a mapping in the Elasticsearch server index for the messages. For a sample index definition, see opendj/config/audit-handlers/elasticsearch-index-setup-example.json.

To enable the Elasticsearch handler, see Configure a Custom Access Log. The JSON configuration file for the Elasticsearch handler has the following format:

{
  "class": "org.forgerock.audit.handlers.elasticsearch.ElasticsearchAuditEventHandler",
  "config": {
    "name": string,               // Handler name, such as "elasticsearch".
    "topics": [ string, ...],     // LDAP: "ldap-access"; HTTP: "http-access".
    "enabled": boolean,           // Is the handler enabled?
    "connection": {               // (Optional) Connect using default settings.
      "host": string,             // Elasticsearch host. Default: localhost.
      "port": number,             // Elasticsearch host. Default: 9200.
      "useSSL": boolean,          // Connect to Elasticsearch over HTTPS? Default: false.
      "username": string,         // (Optional) User name for HTTP Basic auth.
      "password": string          // (Optional) Password for HTTP Basic auth.
    },
    "indexMapping": {             // (Optional) No mapping specified.
      "indexName": string         // Name of the Elasticsearch index.
    },
    "buffering": {                // (Optional) Default: write each message separately,
                                  // no buffering.
      "enabled": boolean,         // Buffer messages to be sent? Default: false.
      "maxSize": number,          // Maximum number of buffered events.
      "writeInterval": duration,  // Interval between sending batch of events.
      "maxBatchedEvents": number  // Number of events to send per interval.
    }
  }
}

For a sample log configuration, see opendj/config/audit-handlers/elasticsearch-config.json-example.

The writeInterval takes a duration, which is a lapse of time expressed in English, such as 23 hours 59 minutes and 59 seconds. Durations are not case sensitive. Negative durations are not supported. Durations use these units:

indefinite, infinity, undefined, unlimited: unlimited duration
zero, disabled: zero-length duration
days, day, d: days
hours, hour, h: hours
minutes, minute, min, m: minutes
seconds, second, sec, s: seconds
milliseconds, millisecond, millisec, millis, milli, ms: milliseconds
microseconds, microsecond, microsec, micros, micro, us: microseconds
nanoseconds, nanosecond, nanosec, nanos, nano, ns: nanoseconds

These steps demonstrate logging HTTP access messages to a local Elasticsearch server:

Install and run an Elasticsearch server on localhost:9200.

Create an audit index in the Elasticsearch server for HTTP audit event messages.

The following command uses the example index configuration file:

$ curl \
 --request POST \
 --header "Content-Type: application/json" \
 --data @/path/to/opendj/config/audit-handlers/elasticsearch-index-setup-example.json \
 http://localhost:9200/audit

{"acknowledged":true}

Configure DS servers to enable HTTP access.

For details, see Configure HTTP User APIs.

Add a JSON configuration file for the handler:

$ cat /path/to/opendj/config/audit-handlers/elasticsearch-handler.json

{
  "class": "org.forgerock.audit.handlers.elasticsearch.ElasticsearchAuditEventHandler",
  "config": {
    "name": "elasticsearch",
    "topics": ["http-access"],
    "connection": {
      "useSSL": false,
      "host": "localhost",
      "port": 9200
    },
    "indexMapping": {
      "indexName": "audit"
    },
    "buffering": {
      "enabled": true,
      "maxSize": 10000,
      "writeInterval": "100 ms",
      "maxBatchedEvents": 500
    }
  }
}

Configure the server to use the Elasticsearch audit handler:

$ dsconfig \
 create-log-publisher \
 --publisher-name "Elasticsearch HTTP Access Log Publisher" \
 --type external-http-access \
 --set enabled:true \
 --set config-file:config/audit-handlers/elasticsearch-handler.json \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

With Elasticsearch and the DS server running, DS sends access event messages to Elasticsearch.

Read a resource:

$ curl --user bjensen:hifalutin --cacert ca-cert.pem https://localhost:8443/api/users/bjensen

Show the resulting audit event content:
```
$ curl 'localhost:9200/audit/_search?q=*&pretty'
```
See the Elasticsearch documentation for details on searching and search results.

JDBC

A JDBC handler sends messages to an appropriately configured relational database table.

Before you enable the JDBC handler, create the necessary schema and tables in the target database. See the following example files:

/path/to/opendj/config/audit-handlers/mysql_tables-example.sql
/path/to/opendj/config/audit-handlers/oracle_tables-example.sql
/path/to/opendj/config/audit-handlers/postgres_tables-example.sql

The JDBC handler depends on the JDBC driver for the database, and on HirakiCP. Copy the JDBC driver .jar file for your database, the HirakiCP .jar file for your Java version, and any other dependent libraries required to the opendj/extlib/ directory.

To enable the JDBC handler, see Configure a Custom Access Log. The JSON configuration file for the JDBC handler has the following format:

{
    "class": "org.forgerock.audit.handlers.jdbc.JdbcAuditEventHandler",
    "config": {
        "name": string,                    // Handler name, such as "jdbc".
        "topics": array,                   // LDAP: "ldap-access"; HTTP: "http-access".
        "databaseType": string,            // Supported by default: "h2", "mysql",
                                           // "oracle", "postgres".
        "enabled": boolean,                // Is the handler enabled?
        "buffering": {                     // (Optional) Default: write each message separately,
                                           // no buffering.
            "enabled": boolean,            // Buffer messages to be sent? Default: false.
            "writeInterval": duration,     // Duration; must be > 0 if buffering is enabled.
            "autoFlush": boolean,          // Flush messages automatically? Default: true.
            "maxBatchedEvents": number,    // Maximum messages in prepared statement. Default: 100.
            "maxSize": number,             // Maximum number of buffered messages. Default: 5000.
            "writerThreads": number        // Threads to write buffered messages: Default: 1.
        },
        "connectionPool": {
            "dataSourceClassName": string, // Either set this to the class name of the data source...
            "jdbcUrl": string,             // ...or set this to the JDBC URL to
                                           // connect to the database.
            "username": string,            // Username to connect to the database.
            "password": string,            // Password to connect to the database.
            "autoCommit": boolean,         // (Optional) Commit transactions automatically?
                                           // Default: true.
            "connectionTimeout": number,   // (Optional) Milliseconds to wait before timing out.
                                           // Default: 30,000.
            "idleTimeout": number,         // (Optional) Milliseconds to wait before timing out.
                                           // Default: 600,000.
            "maxLifetime": number,         // (Optional) Milliseconds thread remains in pool.
                                           // Default: 1,800,000.
            "minIdle": number,             // (Optional) Minimum connections in pool.
                                           // Default: 10.
            "maxPoolSize": number,         // (Optional) Maximum number of connections in pool.
                                           // Default: 10.
            "poolName": string,            // (Optional) Name of connection pool.
                                           // Default: audit.
            "driverClassName": string      // (Optional) Class name of database driver.
                                           // Default: null.
        },
        "tableMappings": [                 // Correspondence of message fields to database columns.
            {
                "event": string,           // LDAP: "ldap-access"; HTTP: "http-access".
                "table": string,           // LDAP: "ldapaccess"; HTTP: "httpaccess".
                "fieldToColumn": {         // Map of field names to database column names.
                    "event-field": "database-column" // Event-field takes JSON pointer.
                }
            }
        ]
    }
}

For a sample configuration, see opendj/config/audit-handlers/jdbc-config.json-example.

indefinite, infinity, undefined, unlimited: unlimited duration
zero, disabled: zero-length duration
days, day, d: days
hours, hour, h: hours
minutes, minute, min, m: minutes
seconds, second, sec, s: seconds
milliseconds, millisecond, millisec, millis, milli, ms: milliseconds
microseconds, microsecond, microsec, micros, micro, us: microseconds
nanoseconds, nanosecond, nanosec, nanos, nano, ns: nanoseconds

JMS

A JMS handler is a JMS producer that publishes messages to an appropriately configured Java Message Service.

To enable the JMS handler, see Configure a Custom Access Log. The JSON configuration file for the JMS handler has the following format:

{
    "class": "org.forgerock.audit.handlers.jms.JmsAuditEventHandler",
    "config": {
        "name": string,                    // Handler name, such as "jms".
        "enabled": boolean,                // Is the handler enabled?
        "topics": array,                   // LDAP: "ldap-access"; HTTP: "http-access".
        "deliveryMode": string,            // One of "NON_PERSISTENT", "PERSISTENT".
        "sessionMode": string,             // One of "AUTO", "CLIENT", "DUPS_OK".
        "batch": {                         // (Optional) Default: Use default settings.
            "capacity": number,            // Maximum capacity of publishing queue. Default: 1.
            "maxBatchedEvents": number,    // Maximum events to deliver in single publishing call.
                                           // Default: 1.
            "writeInterval": string        // Interval between transmissions to JMS.
                                           // Default: "10 millis".
        },
        "jndi": {                          // (Optional) Default: Use default settings.
            "connectionFactoryName": string, // JNDI name for JMS connection factory.
                                           // Default: "ConnectionFactory".
            "topicName": string            // (Optional) Match the value in the context.
                                           // Default: "audit".
            "contextProperties": {         // JNDI InitialContext properties.
                // These depend on the JNDI provider. See the provider documentation for details.
            }
        }
    }
}

For a sample configuration, see opendj/config/audit-handlers/jms-config.json-example.

Splunk

A Splunk handler sends messages to a Splunk service.

This audit handler is deprecated.

To enable the Splunk handler, see Configure a Custom Access Log. The JSON configuration file for the Splunk handler has the following format:

{
    "class": "org.forgerock.audit.handlers.splunk.SplunkAuditEventHandler",
    "config": {
        "name": string,                    // Handler name, such as "splunk".
        "enabled": boolean,                // Is the handler enabled?
        "topics": array,                   // LDAP: "ldap-access"; HTTP: "http-access".
        "authzToken": string,              // Splunk authorization token for HTTP requests.
        "buffering": {                     // Required message buffering configuration.
            "maxBatchedEvents": number,    // Maximum messages in prepared statement.
            "maxSize": number,             // Maximum number of buffered messages.
            "writeInterval": duration      // Duration as described below.
        },
        "connection": {                    // (Optional) Default: Use default settings.
            "host": string,                // Splunk hostname. Default: "localhost".
            "port": number,                // Splunk port number. Default: "8088".
            "useSSL": boolean              // Use secure connection to Splunk? Default: false.
        }
    }
}

For a sample configuration, see opendj/config/audit-handlers/splunk-config.json-example.

indefinite, infinity, undefined, unlimited: unlimited duration
zero, disabled: zero-length duration
days, day, d: days
hours, hour, h: hours
minutes, minute, min, m: minutes
seconds, second, sec, s: seconds
milliseconds, millisecond, millisec, millis, milli, ms: milliseconds
microseconds, microsecond, microsec, micros, micro, us: microseconds
nanoseconds, nanosecond, nanosec, nanos, nano, ns: nanoseconds

Syslog

A Syslog handler sends messages to the UNIX system log as governed by RFC 5424, The Syslog Protocol.

The implementation currently only supports writing access messages, not error messages. As a result, this feature is of limited use in most deployments.

To enable a Syslog handler, see Configure a Custom Access Log. The JSON configuration file for the Syslog handler has the following format:

{
    "class": "org.forgerock.audit.handlers.syslog.SyslogAuditEventHandler",
    "config": {
        "name": string,            // Handler name, such as "syslog".
        "enabled": boolean,        // Default: false.
        "topics": array,           // LDAP: "ldap-access"; HTTP: "http-access".
        "protocol": string,        // "TCP" or "UDP".
        "host": string,            // Syslog daemon host, such as localhost;
                                   // must resolve to IP address.
        "port": number,            // Syslog daemon port number, such as 514; range: 0 to 65535.
        "connectTimeout": number,  // If using TCP, milliseconds to wait before timing out.
        "facility": string,        // Syslog facility to use for event messages.
        "buffering": {             // (Optional) Default: write each message separately, no buffering.
            "enabled": boolean,    // Buffer messages to be sent? Default: false.
            "maxSize": number      // Maximum number of buffered messages. Default: 5000.
        }
    }
}

For a sample configuration, see opendj/config/audit-handlers/syslog-config.json-example.

For additional details, see Syslog Facility Values.

Syslog Facility Values
Value	Description
`kern`	Kernel messages.
`user`	User-level messages.
`mail`	Mail system.
`daemon`	System daemons.
`auth`	Security/authorization messages.
`syslog`	Messages generated internally by `syslogd`.
`lpr`	Line printer subsystem.
`news`	Network news subsystem.
`uucp`	UUCP subsystem.
`cron`	Clock daemon.
`authpriv`	Security/authorization messages.
`ftp`	FTP daemon.
`ntp`	NTP subsystem.
`logaudit`	Log audit.
`logalert`	Log alert.
`clockd`	Clock daemon.
`local0`	Local use 0.
`local1`	Local use 1.
`local2`	Local use 2.
`local3`	Local use 3.
`local4`	Local use 4.
`local5`	Local use 5.
`local6`	Local use 6.
`local7`	Local use 7.

DS 7.1.8

Log to a Service

Elasticsearch

JDBC

JMS

Splunk

Syslog