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.
To configure PingGateway to use the database, add the database .jar file containing the Driver as follows:
-
Create the directory
$HOME/.openig/extra, where$HOME/.openigis the instance directory, and add .jar files to the directory.
The JDBC handler library is in the lib directory.
Unpack the library, then find the examples under the db/ folder.
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": map or configuration expression<map>
}
]
}
}Configuration
"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.
-
"databaseType": configuration expression<string>, required-
The database type name.
Built-in support is provided for
oracle,mysql, andh2. "enabled": configuration expression<boolean>, optional-
Whether this event handler is active.
Default: true.
"buffering": object, optional-
Buffering 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>, optional-
Whether log buffering is enabled.
Default: false.
"writeInterval": configuration expression<duration>, required-
The interval at which to send buffered event messages to the database.
This interval must be greater than 0 if buffering is enabled.
"autoFlush": configuration expression<boolean>, optional-
Whether the events are automatically flushed after being written.
Default: true.
"maxBatchedEvents": configuration expression<number>, optional-
The maximum number of event messages batched into a PreparedStatement.
Default: 100.
"maxSize": : configuration expression<number>, optional-
The maximum size of the queue of buffered event messages.
Default: 5000.
"writerThreads": configuration expression<number>, optional-
The number of threads to write buffered event messages to the database.
Default: 1.
"connectionPool": object, required-
When a JdbcDataSource object named
AuditServiceis defined in the route heap. This configuration is not required.Connection pool settings for sending messages to the database.
"driverClassName": configuration expression<string>, optional-
The 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>, optional-
The class name of the data source for the database.
"jdbcUrl": configuration expression<string>, required-
The JDBC URL to connect to the database.
"username": configuration expression<string>, required-
The username identifier for the database user with access to write the messages.
"password": configuration expression<number>, optional-
The password for the database user with access to write the messages.
"autoCommit": configuration expression<boolean>, optional-
Whether to commit transactions automatically when writing messages.
Default: true.
"connectionTimeout": configuration expression<number>, optional-
The number of milliseconds to wait for a connection from the pool before timing out.
Default: 30000.
"idleTimeout": configuration expression<number>, optional-
The number of milliseconds to allow a database connection to remain idle before timing out.
Default: 600000.
"maxLifetime": configuration expression<number>, optional-
The number of milliseconds to allow a database connection to remain in the pool.
Default: 1800000.
"minIdle": configuration expression<number>, optional-
The minimum number of idle connections in the pool.
Default: 10.
"maxPoolSize": configuration expression<number>, optional-
The maximum number of connections in the pool.
Default: 10.
"poolName": configuration expression<string>, optional-
The name of the connection pool.
"tableMappings": array of objects, required-
Table mappings for directing event content to database table columns.
A table mappings object has the following fields:
"event": configuration expression<string>, required-
The audit event that the table mapping is for.
Set this to
access. "table": configuration expression<string>, required-
The name of the database table that corresponds to the mapping.
"fieldToColumn": map or configuration expression<map>, required-
A map of one or more data pairs with the format
Map<String, String>, where:-
The key is the name of an audit event field
-
The value is the name of a database column, or a configuration expression that evaluates to the name of a database column
The following formats are allowed:
{ "fieldToColumn": { "string": "configuration expression<string>", ... } }{ "fieldToColumn": "configuration expression<map>" }Audit event fields use JSON pointer notation, and are taken from the JSON schema for the audit event content.
In the following example, the property is a map whose keys and values are strings representing the names of audit event fields and database columns:
{ "fieldToColumn": { "_id": "id", "timestamp": "timestamp_", ... } -
Example
Examples including statements to create tables are provided in the JDBC
handler library, forgerock-audit-handler-jdbc-version.jar.
For an example of using JdbcAuditEventHandler, refer to Recording access audit events in a database.
In the following example, PingGateway events are logged to an h2 database:
{
"name": "audit-jdbc",
"baseURI": "http://app.example.com:8081",
"condition": "${find(request.uri.path, '^/home/audit-jdbc')}",
"heap": [
{
"name": "SystemAndEnvSecretStore-1",
"type": "SystemAndEnvSecretStore"
},
{
"name": "AuditDataSource",
"type": "JdbcDataSource",
"config": {
"dataSourceClassName" : "org.h2.jdbcx.JdbcDataSource",
"username" : "sa",
"passwordSecretId" : "database.password",
"secretsProvider" : "SystemAndEnvSecretStore-1",
"properties" : {
"url" : "jdbc:h2:tcp://localhost/~/test"
}
}
},
{
"name": "AuditService",
"type": "AuditService",
"config": {
"eventHandlers": [
{
"class": "org.forgerock.audit.handlers.jdbc.JdbcAuditEventHandler",
"config": {
"databaseType": "h2",
"name": "jdbc",
"topics": [
"access"
],
"tableMappings": [
{
"event": "access",
"table": "audit.auditaccess",
"fieldToColumn": {
"_id": "id",
"timestamp": "timestamp_",
"eventName": "eventname",
"transactionId": "transactionid",
"userId": "userid",
"trackingIds": "trackingids",
"server/ip": "server_ip",
"server/port": "server_port",
"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"
}
}
]
}
}
]
}
}
],
"auditService": "AuditService",
"handler": "ReverseProxyHandler"
}