Audit framework

PingGateway uses the ForgeRock common audit framework to record audit events, using an implementation that is common across the ForgeRock platform.

Audit logs use timestamps in UTC format (for example, 2018-07-18T08:48:00.160Z), a unified standard that is not affected by time changes for daylight savings. The timestamps format is not configurable.

The following objects are available for auditing:

AuditService

The audit service is based on the ForgeRock common audit event framework to record access audit events. For information about how to record other types of audit event, refer to Record custom audit events.

By default, no routes in a configuration are audited; the NoOpAuditService object type provides an empty audit service to the top-level heap and its child routes. PingGateway provides a default empty service based on the NoOpAuditService type. The top-level heap and child routes inherit from the setting and use a service equivalent to the following declaration:

{
  "name": "AuditService",
  "type": "NoOpAuditService"
}

Configure auditing in the following ways:

Override the NoOpAuditService for all routes in the configuration

Define an AuditService object named AuditService in config.json. No other configuration is required; all routes use the same AuditService.

Configure an audit service that can be optionally used by all routes in the configuration

Do both of the following:

In config.json in the top-level heap, define an AuditService object that is not named AuditService.
In a route, configure the Route property auditService to refer to the name of the declared AuditService heaplet.

Configure an audit service specifically for a route

Do one of the following:

Define an AuditService object named AuditService in the route heap.
In the route heap or a parent heap, define an AuditService object that is not named AuditService; configure the Route property auditService to refer to the name of the declared AuditService heaplet.
Configure the Route property auditService with an inline AuditService object.

One configuration can contain multiple AuditServices.

When you define multiple AuditServices that use JsonAuditEventHandler or CsvAuditEventHandler, configure each of the event handlers with a different logDirectory. This prevents the AuditServices from logging to the same audit logging file.

Usage

{
  "name": string,
  "type": "AuditService",
  "config": {
    "config": object,
    "eventHandlers": [ object, ...],
    "topicsSchemasDirectory": configuration expression<string>
  }
}

Properties

"config": object, required

Configures the audit service itself, rather than event handlers. If the configuration uses only default settings, you can omit the field instead of including an empty object as the field value.

{
  "config": {
    "handlerForQueries": configuration_expression<string>,
    "availableAuditEventHandlers": [configuration_expression<string>, ...],
    "caseInsensitiveFields": [configuration_expression<string>, ...],
    "filterPolicies": {
      "field": {
        "includeIf": [configuration_expression<string>, ...],
        "excludeIf": [configuration_expression<string>, ...]
      }
    }
  }
}

"handlerForQueries": configuration expression<string>, optional

The name of the event handler to use when querying audit event messages over REST.

"availableAuditEventHandlers": array of configuration expression<strings>, optional

A list of fully qualified event handler class names for event handlers available to the audit service.

"caseInsensitiveFields": array of configuration expression<strings>, optional

A list of audit event fields to be considered as case-insensitive for filtering. The fields are referenced using JSON pointer syntax. The list can be null or empty.

Default: /access/http/request/headers and /access/http/response/headers fields are considered case-insensitive for filtering. All other fields are considered case-sensitive.

"filterPolicies": object, optional

To prevent logging of sensitive data for an event, the Common Audit implementation uses a safelist to specify which event fields appear in the logs. By default, only event fields that are safelisted are included in the audit event logs. For more information about safelisting, refer to Safelisting audit event fields for the logs.

"field": object, optional

This property specifies non-safelisted event fields to include in the logs, and safelisted event fields to exclude from the logs.

If includeIf and excludeIf are specified for the same field, excludeIf takes precedence.

Audit event fields use JSON pointer notation, and are taken from the JSON schema for the audit event content.

Default: Include only safelisted event fields in the logs.

"includeIf": array of configuration expression<strings>, optional:

A list of non-safelisted audit event fields to include in the logs. Specify the topic and the hierarchy to the field. Any child fields of the specified field are encompassed.

Before you include non-safelisted event fields in the logs, consider the impact on security. Including some headers, query parameters, or cookies in the logs could cause credentials or tokens to be logged, and allow anyone with access to the logs to impersonate the holder of these credentials or tokens.

"excludeIf": array of configuration expression<strings>, optional:

A list of safelisted audit event fields to exclude from the logs. Specify the topic and the hierarchy to the field. Any child fields of the specified field are encompassed.

The following example excludes fields for the access topic:

{
  "field": {
    "excludeIf": [
      "/access/http/request/headers/host",
      "/access/http/request/path",
      "/access/server",
      "/access/response"
    ]
  }
}

For an example route that excludes fields, see Exclude safelisted audit event fields from logs.

"eventHandlers": array of Event Handler objects, required

An array of one or more audit event handler configuration objects to deal with audit events.

The configuration of the event handler depends on type of event handler. PingGateway supports the event handlers listed in AuditFramework.

"topicsSchemasDirectory": configuration expression<string>, optional

Directory containing the JSON schema for the topic of a custom audit event. The schema defines which fields are included in the topic. For information about the syntax, see JSON Schema.

Default: $HOME/.openig/audit-schemas (Windows, %appdata%\OpenIG\OpenIG\audit-schemas)

For an example of how to configure custom audit events, see Record custom audit events.

The following example schema includes the mandatory fields, _id, timestamp, transactionId, and eventName, and an optional customField:

{
  "schema": {
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "/",
    "type": "object",
    "properties": {
      "_id": {
        "type": "string"
      },
      "timestamp": {
        "type": "string"
      },
      "transactionId": {
        "type": "string"
      },
      "eventName": {
        "type": "string"
      },
      "customField": {
        "type": "string"
      }
    }
  }
}

Example

The following example audit service logs access event messages in a comma-separated variable file, named /path/to/audit/logs/access.csv:

{
  "name": "AuditService",
  "type": "AuditService",
  "config": {
    "config": {},
    "eventHandlers": [
      {
        "class": "org.forgerock.audit.handlers.csv.CsvAuditEventHandler",
        "config": {
          "name": "csv",
          "logDirectory": "/path/to/audit/logs",
          "topics": [
            "access"
          ]
        }
      }
    ]
  }
}

The following example route uses the audit service:

{
  "handler": "ReverseProxyHandler",
  "auditService": "AuditService"
}

More information

NoOpAuditService

org.forgerock.audit.AuditService

CsvAuditEventHandler

An audit event handler that responds to events by logging messages to files in comma-separated variable (CSV) format.

Declare the configuration in an audit service, as described in AuditService.

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

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

Usage

{
  "class": "org.forgerock.audit.handlers.csv.CsvAuditEventHandler",
  "config": {
    "name": configuration expression<string>,
    "logDirectory": configuration expression<string>,
    "topics": [ configuration expression<string>, ... ],
    "enabled": configuration expression<boolean>,
    "formatting": {
      "quoteChar": configuration expression<string>,
      "delimiterChar": configuration expression<string>,
      "endOfLineSymbols": configuration expression<string>
    },
    "buffering": {
      "enabled": configuration expression<boolean>,
      "autoFlush": configuration expression<boolean>
    },
    "security": {
      "enabled": configuration expression<boolean>,
      "filename": configuration expression<string>,
      "password": configuration expression<string>,
      "signatureInterval": configuration expression<duration>
    },
    "fileRotation": {
      "rotationEnabled": configuration expression<boolean>,
      "maxFileSize": configuration expression<number>,
      "rotationFilePrefix": configuration expression<string>,
      "rotationFileSuffix": configuration expression<string>,
      "rotationInterval": configuration expression<duration>,
      "rotationTimes": [ configuration expression<duration>, ... ]
    },
    "fileRetention": {
      "maxDiskSpaceToUse": configuration expression<number>,
      "maxNumberOfHistoryFiles": configuration expression<number>,
      "minFreeSpaceRequired": configuration expression<number>
    },
    "rotationRetentionCheckInterval": configuration expression<duration>
  }
}

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

"name": configuration expression<string>, required: The name of the event handler.

"logDirectory": configuration expression<string>, required

The file system directory where this event handler writes log files.

When multiple AuditServices are defined in the deployment, prevent them from logging to the same audit logging file by setting different values for logDirectory.

"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 access audit 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.

"enabled": configuration expression<boolean>, optional

Whether this event handler is active.

Default: true

"formatting": object, optional

Formatting settings for CSV log files.

The formatting object has the following fields:

"quoteChar": configuration expression<string>, optional: A single character to quote CSV entries.

Default: "
"delimiterChar": configuration expression<string>, optional: A single character to delimit CSV entries.

Default: ,
"endOfLineSymbols": configuration expression<string>, optional: A character or characters to separate a line.

Default: System-dependent line separator defined for the JVM

"buffering": object, optional

Do not enable buffering when security is configured for tamper-evident logging.

Buffering settings for writing CSV log files. 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
"autoFlush": configuration expression<boolean>, optional: Whether events are automatically flushed after being written.

Default: true

"security": object, optional

When security is configured for tamper-evident logging, do not enable buffering.

Security settings for CSV log files. These settings govern tamper-evident logging, whereby messages are signed. By default tamper-evident logging is not enabled.

The security object has the following fields:

"enabled": configuration expression<boolean>, optional: Whether tamper-evident logging is enabled.

Default: false

Tamper-evident logging depends on a specially prepared keystore. For an example, see Recording Access Audit Events in CSV.
"filename": configuration expression<string>, required: File system path to the keystore containing the private key for tamper-evident logging.

The keystore must be a keystore of type JCEKS. For an example, see Recording access audit events in CSV.
"password": configuration expression<string>, required: The password for the keystore for tamper-evident logging.

This password is used for the keystore and for private keys. For an example, see Recording access audit events in CSV.
"signatureInterval": configuration expression<duration>, required: The time interval after which to insert a signature in the CSV file. This duration must not be zero, and must not be unlimited.

"fileRotation": object, optional

File rotation settings for log files.

"rotationEnabled": configuration expression<boolean>, optional

A flag to enable rotation of log files.

Default: false.

"maxFileSize": configuration expression<number>, optional

The maximum file size of an audit log file in bytes. A setting of 0 or less indicates that the policy is disabled.

Default: 0.

"rotationFilePrefix": configuration expression<string>, optional

The prefix to add to a log file on rotation. This has an effect when time-based file rotation is enabled.

"rotationFileSuffix": configuration expression<string>, optional

The suffix to add to a log file on rotation, possibly expressed in SimpleDateFormat.

This has an effect when time-based file rotation is enabled.

Default: -yyyy.MM.dd-HH.mm.ss, where yyyy characters are replaced with the year, MM characters are replaced with the month, dd characters are replaced with the day, HH characters are replaced with the hour (00-23), mm characters are replaced with the minute (00-60), and ss characters are replaced with the second (00-60).

"rotationInterval": configuration expression<duration>, optional

The time interval after which to rotate log files. This duration must not be zero. This has the effect of enabling time-based file rotation.

"rotationTimes": array of configuration expression<durations>, optional

The durations, counting from midnight UTC, after which to rotate files.

The following example schedules rotation six and twelve hours after midnight:

"rotationTimes": [ "6 hours", "12 hours" ]

This has the effect of enabling time-based file rotation.

"fileRetention": object, optional

File retention settings for log files.

"maxNumberOfHistoryFiles": configuration expression<number>, optional: The maximum number of historical audit files that can be stored. If the number exceeds this maximum, older files are deleted. A value of -1 disables purging of old log files.

Default: 0.
"maxDiskSpaceToUse": configuration expression<number>, optional: The maximum disk space in bytes that can be used for audit files. If the audit files use more than this space, older files are deleted. A negative or zero value indicates that this policy is disabled, and historical audit files can use unlimited disk space.

Default: 0
"minFreeSpaceRequired": configuration expression<string>, optional: The minimum free disk space in bytes required on the system that houses the audit files. If the free space drops below this minimum, older files are deleted. A negative or zero value indicates that this policy is disabled, and no minimum space requirements apply.

Default: 0

"rotationRetentionCheckInterval": configuration expression<string>, optional

Interval at which to periodically check file rotation and retention policies. The interval must be a duration, for example, 5 seconds, 5 minutes, or 5 hours.

PingGateway checks whether to rotate the current audit file at each interval. If so, it also checks whether to retain old audit files.

Default: 5 seconds

Example

For information about how to record audit events in a CSV file, see Recording Access Audit Events in CSV.

The following example configures a CSV audit event handler to write a log file, /path/to/audit/logs/access.csv, that is signed every 10 seconds to make it tamper-evident:

{
  "name": "csv",
  "topics": [
    "access"
  ],
  "logDirectory": "/path/to/audit/logs/",
  "security": {
    "enabled": "true",
    "filename": "/path/to/secrets/audit-keystore",
    "password": "password",
    "signatureInterval": "10 seconds"
  }
}

More information

org.forgerock.audit.handlers.csv.CsvAuditEventHandler

ElasticsearchAuditEventHandler (deprecated)

This object is deprecated; use one of the following objects instead:

SyslogAuditEventHandler
JsonAuditEventHandler, with elasticsearchCompatible set to true

For more information, refer to the Deprecated section of the Release Notes.

An audit event handler that responds to events by logging messages in the Elasticsearch search and analytics engine. For information about downloading and installing Elasticsearch, refer to the Elasticsearch Getting started document.

Usage

Configure the ElasticsearchAuditEventHandler within an AuditService:

{
  "type": "AuditService",
  "config": {
    "config": {},
    "eventHandlers": [{
      "class": "org.forgerock.audit.handlers.elasticsearch.ElasticsearchAuditEventHandler",
      "config": {
        "name": configuration expression<string>,
        "topics": [ configuration expression<string>, ... ],
        "connection": {
          "host": configuration expression<string>,
          "port": configuration expression<number>,
          "useSSL": configuration expression<boolean>,
          "username": configuration expression<string>,
          "password": configuration expression<string>
        },
        "indexMapping": {
          "indexName": configuration expression<string>
        },
        "buffering": {
          "enabled": configuration expression<boolean>,
          "writeInterval": configuration expression<duration>,
          "maxSize": configuration expression<number>,
          "maxBatchedEvents": configuration expression<number>
        }
      }
    }
  }
}

The ElasticsearchAuditEventHandler relays audit events to Elasticsearch through the HTTP protocol, using a handler defined in a heap. The handler can be of any kind of handler, from a simple ClientHandler to a complex Chain, composed of multiple filters and a final handler or ScriptableHandler.

PingGateway searches first for a handler named ElasticsearchClientHandler. If not found, PingGateway searches for a client handler named AuditClientHandler. If not found, PingGateway uses the route’s default client handler, named ClientHandler.

The following example configures a ClientHandler named ElasticsearchClientHandler:

{
  "name": "ElasticsearchClientHandler",
  "type": "ClientHandler",
  "config": {}
}

The following example configures a ScriptableHandler named AuditClientHandler:

{
  "name": "AuditClientHandler",
  "type": "ScriptableHandler",
  "config": {}
}

Properties

"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 access audit 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.

"connection": object, optional

Connection settings for sending messages to Elasticsearch. If this object is not configured, it takes default values for its fields. This object has the following fields:

"host": configuration expression<string>, optional: Hostname or IP address of Elasticsearch.

Default: localhost
"port": configuration expression<number>, optional: The port used by Elasticsearch. The value must be between 0 and 65535.

Default: 9200
"useSSL": configuration expression<boolean>, optional: Setting to use or not use SSL/TLS to connect to Elasticsearch.

Default: false
"username": configuration expression<string>, optional: Username when basic authentication is enabled through Elasticsearch Shield.
"password": configuration expression<string>, optional: Password when basic authentication is enabled through Elasticsearch Shield.

"indexMapping": object, optional

Defines how an audit event and its fields are stored and indexed.

"indexName": configuration expression<string>, optional: The index name. Set this parameter if the default name audit conflicts with an existing Elasticsearch index.

Default: audit.

"buffering": object, optional

Settings for buffering events and batch writes.

"enabled": configuration expression<boolean>, optional: Setting to use or not use log buffering.

Default: false.
"writeInterval": configuration expression<duration>: The interval at which to send buffered event messages to Elasticsearch. If buffering is enabled, this interval must be greater than 0.

Default: 1 second
"maxBatchedEvents": configuration expression<number>, optional: The maximum number of event messages in a batch write to Elasticsearch for each writeInterval.

Default: 500
"maxSize": configuration expression<number>, optional: The maximum number of event messages in the queue of buffered event messages.

Default: 10000

Example

In the following example, an Elasticsearch audit event handler logs audit events for access. For an example of setting up and testing this configuration, refer to [maintenance-guide:].

{
  "name": "30-elasticsearch",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(request.uri.path, '^/home/elasticsearch-audit')}",
  "heap": [
    {
      "name": "AuditService",
      "type": "AuditService",
      "config": {
        "eventHandlers": [
          {
            "class": "org.forgerock.audit.handlers.elasticsearch.ElasticsearchAuditEventHandler",
            "config": {
              "name": "elasticsearch",
              "indexMapping": {
                "indexName": "audit"
              },
              "connection": {
                "host": "localhost",
                "port": 9200,
                "useSSL": false
              },
              "topics": [
                "access"
              ]
            }
          }
        ]
      }
    }
  ],
  "auditService": "AuditService",
  "handler": "ReverseProxyHandler"
}

More information

org.forgerock.audit.handlers.elasticsearch.ElasticsearchAuditEventHandler

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/.openig is 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 access audit 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, and h2.

"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 AuditService is 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"
}

More information

org.forgerock.audit.handlers.jdbc.JdbcAuditEventHandler

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. For more information, refer to Basic JMS API Concepts

The JMS audit event handler does not 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/.openig is 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

For a list of properties in the "config" object, refer to JMS Audit Event Handler in IDM’s Integrator’s guide.

"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 access audit 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 PERSISTENT or NON_PERSISTENT.

"sessionMode": configuration expression<string>, required

Acknowledgement mode in sessions without transactions. Set to AUTO, CLIENT, or DUPS_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.initial

For example, "org.apache.activemq.jndi.ActiveMQInitialContextFactory".

To substitute a different JNDI message broker, change the JNDI context properties.
java.naming.provider.url

For 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.url to:
```
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.audit

For example, "audit".

To use the JMS resources provided by your application server, leave this field empty. The values for topicName and connectionFactoryName are 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.audit in contextProperties.

"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. For an example of setting up and testing this configuration, refer to 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"
    }
  }
}

More information

org.forgerock.audit.handlers.jms.JmsAuditEventHandler

JsonAuditEventHandler

Logs events as JSON objects to a set of JSON files. There is one file for each topic defined in topics, named with the format topic.audit.json.

The JsonAuditEventHandler is the preferred file-based audit event handler.

Declare the configuration in an audit service, as described in AuditService.

Usage

{
  "name": string,
  "type": "AuditService",
  "config": {
    "config": {},
    "eventHandlers": [
    {
      "class": "org.forgerock.audit.handlers.json.JsonAuditEventHandler",
      "config": {
        "name": configuration expression<string>,
        "topics": [ configuration expression<string>, ... ],
        "logDirectory": configuration expression<string>,
        "elasticsearchCompatible": configuration expression<boolean>,
        "fileRotation": {
          "rotationEnabled": configuration expression<boolean>,
          "maxFileSize": configuration expression<number>,
          "rotationFilePrefix": configuration expression<string>,
          "rotationFileSuffix": configuration expression<string>,
          "rotationInterval": configuration expression<duration>,
          "rotationTimes": [ configuration expression<duration>, ... ]
        },
        "fileRetention": {
          "maxNumberOfHistoryFiles": configuration expression<number>,
          "maxDiskSpaceToUse": configuration expression<number>,
          "minFreeSpaceRequired": configuration expression<number>
        },
        "rotationRetentionCheckInterval": configuration expression<duration>,
        "buffering": {
          "writeInterval": configuration expression<duration>,
          "maxSize": configuration expression<number>
        }
      }
    }]
  }
}

Configuration

"name": configuration expression<string>, required: The event handler name. This property is used only to refer to the event handler, but is not used to name the generated log file.

"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 access audit 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.

"logDirectory": configuration expression<string>, required

The file system directory where this event handler writes log files.

When multiple AuditServices are defined in the deployment, prevent them from logging to the same audit logging file by setting different values for logDirectory.

elasticsearchCompatible: configuration expression<boolean>, optional

Set to true to enable compatibility with ElasticSearch JSON format. For more information, refer to the ElasticSearch documentation.

Default: false