JdbcAuditEventHandler
An audit event handler that responds to events by logging messages to an appropriately configured relational database table.
Declare the configuration in an audit service, as described in "AuditService".
Usage
{
"class": "org.forgerock.audit.handlers.jdbc.JdbcAuditEventHandler",
"config": {
"name": configuration expression<string>,
"topics": [ configuration expression<string>, ... ],
"databaseType": configuration expression<string>,
"enabled": configuration expression<boolean>,
"buffering": {
"enabled": configuration expression<boolean>,
"writeInterval": configuration expression<duration>,
"autoFlush": configuration expression<boolean>,
"maxBatchedEvents": configuration expression<number>,
"maxSize": configuration expression<number>,
"writerThreads": configuration expression<number>
},
"connectionPool": {
"driverClassName": configuration expression<string>,
"dataSourceClassName": configuration expression<string>,
"jdbcUrl": configuration expression<string>,
"username": configuration expression<string>,
"password": configuration expression<string>,
"autoCommit": configuration expression<boolean>,
"connectionTimeout": configuration expression<number>,
"idleTimeout": configuration expression<number>,
"maxLifetime": configuration expression<number>,
"minIdle": configuration expression<number>,
"maxPoolSize": configuration expression<number>,
"poolName": configuration expression<string>
},
"tableMappings": [
{
"event": configuration expression<string>,
"table": configuration expression<string>,
"fieldToColumn": configuration expression<map>
}
]
}
}The values in this configuration object can use expressions as long as they resolve to the correct types for each field. For details about expressions, see "Expressions".
Configuration
The "config" object has the following properties:
"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".
"databaseType": configuration expression<string>, requiredThe database type name.
Built-in support is provided for
oracle,mysql, andh2. Unrecognized database types rely on a GenericDatabaseStatementProvider."enabled": configuration expression<boolean>, optionalWhether this event handler is active.
Default: true.
"buffering": object, optionalBuffering settings for sending messages to the database. The default is for messages to be written to the log file for each event.
The buffering object has the following fields:
"enabled": configuration expression<boolean>, optionalWhether log buffering is enabled.
Default: false.
"writeInterval": configuration expression<duration>, requiredThe interval at which to send buffered event messages to the database.
This interval must be greater than 0 if buffering is enabled.
For information about supported formats for
duration, see duration."autoFlush": configuration expression<boolean>, optionalWhether the events are automatically flushed after being written.
Default: true.
"maxBatchedEvents": configuration expression<number>, optionalThe maximum number of event messages batched into a PreparedStatement.
Default: 100.
"maxSize": : configuration expression<number>, optionalThe maximum size of the queue of buffered event messages.
Default: 5000.
"writerThreads": configuration expression<number>, optionalThe number of threads to write buffered event messages to the database.
Default: 1.
"connectionPool": object, requiredConnection pool settings for sending messages to the database.
The connection pool object has the following fields:
"driverClassName": configuration expression<string>, optionalThe class name of the driver to use for the JDBC connection. For example, with MySQL Connector/J, the class name is
com.mysql.jdbc.Driver."dataSourceClassName": configuration expression<string>, optionalThe class name of the data source for the database.
"jdbcUrl": configuration expression<string>, requiredThe JDBC URL to connect to the database.
"username": configuration expression<string>, requiredThe username identifier for the database user with access to write the messages.
"password": configuration expression<number>, optionalThe password for the database user with access to write the messages.
"autoCommit": configuration expression<boolean>, optionalWhether to commit transactions automatically when writing messages.
Default: true.
"connectionTimeout": configuration expression<number>, optionalThe number of milliseconds to wait for a connection from the pool before timing out.
Default: 30000.
"idleTimeout": configuration expression<number>, optionalThe number of milliseconds to allow a database connection to remain idle before timing out.
Default: 600000.
"maxLifetime": configuration expression<number>, optionalThe number of milliseconds to allow a database connection to remain in the pool.
Default: 1800000.
"minIdle": configuration expression<number>, optionalThe minimum number of idle connections in the pool.
Default: 10.
"maxPoolSize": configuration expression<number>, optionalThe maximum number of connections in the pool.
Default: 10.
"poolName": configuration expression<string>, optionalThe name of the connection pool.
"tableMappings": array of objects, requiredTable mappings for directing event content to database table columns.
A table mappings object has the following fields:
"event": configuration expression<string>, requiredThe audit event that the table mapping is for.
Set this to
access."table": configuration expression<string>, requiredThe name of the database table that corresponds to the mapping.
"fieldToColumn": configuration expression<map>, requiredMaps of names of audit event fields to database columns, where the keys and values are both strings.
Audit event fields use JSON pointer notation, and are taken from the JSON schema for the audit event content.
Example
The following example configures a JDBC audit event handler using a local MySQL database, writing to a table named auditaccess:
{
"class": "org.forgerock.audit.handlers.jdbc.JdbcAuditEventHandler",
"config": {
"databaseType": "mysql",
"name": "jdbc",
"topics": [
"access"
],
"connectionPool": {
"jdbcUrl": "jdbc:mysql://localhost:3306/audit?allowMultiQueries=true&characterEncoding=utf8",
"username": "audit",
"password": "audit"
},
"tableMappings": [
{
"event": "access",
"table": "auditaccess",
"fieldToColumn": {
"_id": "id",
"timestamp": "timestamp_",
"eventName": "eventname",
"transactionId": "transactionid",
"userId": "userid",
"trackingIds": "trackingids",
"server/ip": "server_ip",
"server/port": "server_port",
"client/host": "client_host",
"client/ip": "client_ip",
"client/port": "client_port",
"request/protocol": "request_protocol",
"request/operation": "request_operation",
"request/detail": "request_detail",
"http/request/secure": "http_request_secure",
"http/request/method": "http_request_method",
"http/request/path": "http_request_path",
"http/request/queryParameters": "http_request_queryparameters",
"http/request/headers": "http_request_headers",
"http/request/cookies": "http_request_cookies",
"http/response/headers": "http_response_headers",
"response/status": "response_status",
"response/statusCode": "response_statuscode",
"response/elapsedTime": "response_elapsedtime",
"response/elapsedTimeUnits": "response_elapsedtimeunits"
}
}
]
}
} Examples including statements to create tables are provided in the JDBC handler library, forgerock-audit-handler-jdbc-version.jar, Unpack the library, then find the examples under the db/ folder.
The JDBC handler library is built into the IG .war file.