--- title: Audit framework description: IG uses the ForgeRock common audit framework to record audit events, using an implementation that is common across the ForgeRock platform. component: pinggateway version: 2023.11 page_id: pinggateway:reference:AuditFramework canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/AuditFramework.html llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2022-04-12T12:16:42Z superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/AuditFramework.html section_ids: AuditService: AuditService AuditService-usage: Usage AuditService-properties: Properties AuditService-example: Example AuditService-moreinfo: More information CsvAuditEventHandler: CsvAuditEventHandler CsvAuditEventHandler-usage: Usage CsvAuditEventHandler-configuration: Configuration CsvAuditEventHandler-example: Example CsvAuditEventHandler-moreinfo: More information ElasticsearchAuditEventHandler: ElasticsearchAuditEventHandler (deprecated) ElasticsearchAuditEventHandler-usage: Usage ElasticsearchAuditEventHandler-properties: Properties ElasticsearchAuditEventHandler-example: Example ElasticsearchAuditEventHandler-moreinfo: More information JdbcAuditEventHandler: JdbcAuditEventHandler JdbcAuditEventHandler-usage: Usage JdbcAuditEventHandler-conf: Configuration JdbcAuditEventHandler-example: Example JdbcAuditEventHandler-moreinfo: More information JmsAuditEventHandler: JmsAuditEventHandler JmsAuditEventHandler-usage: Usage JmsAuditEventHandler-conf: Configuration jms-example: Example JmsAuditEventHandler-moreinfo: More information JsonAuditEventHandler: JsonAuditEventHandler JsonAuditEventHandler-usage: Usage JsonAuditEventHandler-conf: Configuration JsonAuditEventHandler-example: Example JsonAuditEventHandler-moreinfo: More information JsonStdoutAuditEventHandler: JsonStdoutAuditEventHandler JsonStdoutAuditEventHandler-usage: Usage JsonStdoutAuditEventHandler-conf: Configuration JsonStdoutAuditEventHandler-example: Example JsonStdoutAuditEventHandler-moreinfo: More information NoOpAuditService: NoOpAuditService NoOpAuditService-usage: Usage NoOpAuditService-moreinfo: More information SyslogAuditEventHandler: SyslogAuditEventHandler SyslogAuditEventHandler-usage: Usage SyslogAuditEventHandler-conf: Configuration SyslogAuditEventHandler-example: Example SyslogAuditEventHandler-moreinfo: More information SplunkAuditEventHandler: SplunkAuditEventHandler (deprecated) SplunkAuditEventHandler-usage: Usage SplunkAuditEventHandler-conf: Configuration splunk-example: Example SplunkAuditEventHandler-moreinfo: More information --- # Audit framework IG 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](../configure/extending.html#audit-custom). By default, no routes in a configuration are audited; the [NoOpAuditService](NoOpAuditService.html) object type provides an empty audit service to the top-level heap and its child routes. IG 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: ```json { "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](Route.html) 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](Route.html) property `auditService` to refer to the name of the declared `AuditService` heaplet. * Configure the [Route](Route.html) 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 ```json { "name": string, "type": "AuditService", "config": { "config": object, "eventHandlers": [ object, ...], "topicsSchemasDirectory": configuration expression, "event-handlers": [ object, ...] // deprecated } } ``` ### Properties * `"config"`: *[object](preface.html#definition-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. ```json { "config": { "handlerForQueries": configuration_expression, "availableAuditEventHandlers": [configuration_expression, ...], "caseInsensitiveFields": [configuration_expression, ...], "filterPolicies": { "field": { "includeIf": [configuration_expression, ...], "excludeIf": [configuration_expression, ...] } } } } ``` * `"handlerForQueries"`: *configuration expression<[string](preface.html#definition-string)>, optional* The name of the event handler to use when querying audit event messages over REST. * `"availableAuditEventHandlers"`: *array of configuration expression<[strings](preface.html#definition-string)>, optional* A list of fully qualified event handler class names for event handlers available to the audit service. * `"caseInsensitiveFields"`: *array of configuration expression<[strings](preface.html#definition-string)>, 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](preface.html#definition-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](../maintenance-guide/auditing.html#common-audit-safelist). * `"field"`: *[object](preface.html#definition-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](preface.html#definition-string)>, 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](preface.html#definition-string)>, 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: ```json { "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](../maintenance-guide/auditing.html#proc-audit-exclude). * `"eventHandlers"`: *array of Event Handler [objects](preface.html#definition-object), 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. IG supports the event handlers listed in [AuditFramework](#). * `"topicsSchemasDirectory"`: *configuration expression<[string](preface.html#definition-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](https://json-schema.org). Default: `$HOME/.openig/audit-schemas` (Windows, `%appdata%\OpenIG\audit-schemas`) For an example of how to configure custom audit events, see [Record custom audit events](../configure/extending.html#audit-custom). The following example schema includes the mandatory fields, `_id`, `timestamp`, `transactionId`, and `eventName`, and an optional `customField`: ```json { "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" } } } } ``` * "event-handlers": array of configuration objects, required | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | This property is deprecated. Use `eventHandlers` instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | The event handlers that deal with audit events. ### Example The following example audit service logs access event messages in a comma-separated variable file, named `/path/to/audit/logs/access.csv`: ```json { "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: ```json { "handler": "ReverseProxyHandler", "auditService": "AuditService" } ``` ### More information [NoOpAuditService](#NoOpAuditService) [org.forgerock.audit.AuditService](../_attachments/apidocs/org/forgerock/audit/AuditService.html) ## 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](#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 ```json { "class": "org.forgerock.audit.handlers.csv.CsvAuditEventHandler", "config": { "name": configuration expression, "logDirectory": configuration expression, "topics": [ configuration expression, ... ], "enabled": configuration expression, "formatting": { "quoteChar": configuration expression, "delimiterChar": configuration expression, "endOfLineSymbols": configuration expression }, "buffering": { "enabled": configuration expression, "autoFlush": configuration expression }, "security": { "enabled": configuration expression, "filename": configuration expression, "password": configuration expression, "signatureInterval": configuration expression }, "fileRotation": { "rotationEnabled": configuration expression, "maxFileSize": configuration expression, "rotationFilePrefix": configuration expression, "rotationFileSuffix": configuration expression, "rotationInterval": configuration expression, "rotationTimes": [ configuration expression, ... ] }, "fileRetention": { "maxDiskSpaceToUse": configuration expression, "maxNumberOfHistoryFiles": configuration expression, "minFreeSpaceRequired": configuration expression }, "rotationRetentionCheckInterval": configuration expression } } ``` 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](Expressions.html#Expressions). ### Configuration * `"name"`: *configuration expression<[string](preface.html#definition-string)>, required* The name of the event handler. - `"logDirectory"`: *configuration expression<[string](preface.html#definition-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](preface.html#definition-string)>, required* 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 `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 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, refer to [Record custom audit events](../configure/extending.html#audit-custom). - `"enabled"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Whether this event handler is active. Default: true - `"formatting"`: *[object](preface.html#definition-object), optional* Formatting settings for CSV log files. The formatting object has the following fields: * `"quoteChar"`: *configuration expression<[string](preface.html#definition-string)>, optional* A single character to quote CSV entries. Default: `"` * `"delimiterChar"`: *configuration expression<[string](preface.html#definition-string)>, optional* A single character to delimit CSV entries. Default: `,` * `"endOfLineSymbols"`: *configuration expression<[string](preface.html#definition-string)>, optional* A character or characters to separate a line. Default: System-dependent line separator defined for the JVM - `"buffering"`: *[object](preface.html#definition-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](preface.html#definition-boolean)>, optional* Whether log buffering is enabled. Default: false * `"autoFlush"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Whether events are automatically flushed after being written. Default: true - `"security"`: *[object](preface.html#definition-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](preface.html#definition-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](../maintenance-guide/auditing.html#proc-audit-csv). * `"filename"`: *configuration expression<[string](preface.html#definition-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](../maintenance-guide/auditing.html#proc-audit-csv). * `"password"`: *configuration expression<[string](preface.html#definition-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](../maintenance-guide/auditing.html#proc-audit-csv). * `"signatureInterval"`: *configuration expression<[duration](preface.html#definition-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](preface.html#definition-object), optional* File rotation settings for log files. * `"rotationEnabled"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* A flag to enable rotation of log files. Default: false. * `"maxFileSize"`: *configuration expression<[number](preface.html#definition-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](preface.html#definition-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](preface.html#definition-string)>, optional* The suffix to add to a log file on rotation, possibly expressed in [SimpleDateFormat](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/text/SimpleDateFormat.html). 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](preface.html#definition-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](preface.html#definition-duration)>, optional* The durations, counting from midnight, after which to rotate files. The following example schedules rotation six and twelve hours after midnight: ```json "rotationTimes": [ "6 hours", "12 hours" ] ``` This has the effect of enabling time-based file rotation. * `"fileRetention"`: *[object](preface.html#definition-object), optional* File retention settings for log files. * `"maxNumberOfHistoryFiles"`: *configuration expression<[number](preface.html#definition-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](preface.html#definition-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](preface.html#definition-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](preface.html#definition-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. Default: 5 seconds ### Example For information about how to record audit events in a CSV file, see [Recording Access Audit Events in CSV](../maintenance-guide/auditing.html#audit-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: ```json { "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](../_attachments/apidocs/org/forgerock/audit/handlers/csv/CsvAuditEventHandler.html) ## ElasticsearchAuditEventHandler (deprecated) | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | This object is deprecated; use one of the following objects instead:- [SyslogAuditEventHandler](SyslogAuditEventHandler.html) - [JsonAuditEventHandler](JsonAuditEventHandler.html), with `elasticsearchCompatible` set to `true`For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) 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](http://www.elastic.co/guide/en/elasticsearch/reference/current/getting-started.html) document. ### Usage Configure the ElasticsearchAuditEventHandler within an [AuditService](#AuditService): ```none { "type": "AuditService", "config": { "config": {}, "eventHandlers": [{ "class": "org.forgerock.audit.handlers.elasticsearch.ElasticsearchAuditEventHandler", "config": { "name": configuration expression, "topics": [ configuration expression, ... ], "connection": { "host": configuration expression, "port": configuration expression, "useSSL": configuration expression, "username": configuration expression, "password": configuration expression }, "indexMapping": { "indexName": configuration expression }, "buffering": { "enabled": configuration expression, "writeInterval": configuration expression, "maxSize": configuration expression, "maxBatchedEvents": configuration expression } } } } } ``` 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. IG searches first for a handler named `ElasticsearchClientHandler`. If not found, IG searches for a client handler named `AuditClientHandler`. If not found, IG uses the route's default client handler, named `ClientHandler`. The following example configures a ClientHandler named `ElasticsearchClientHandler`: ```json { "name": "ElasticsearchClientHandler", "type": "ClientHandler", "config": {} } ``` The following example configures a ScriptableHandler named `AuditClientHandler`: ```json { "name": "AuditClientHandler", "type": "ScriptableHandler", "config": {} } ``` ### Properties * `"name"`: *configuration expression<[string](preface.html#definition-string)>, required* The name of the event handler. - `"topics"`: *array of configuration expression<[strings](preface.html#definition-string)>, required* 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 `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 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, refer to [Record custom audit events](../configure/extending.html#audit-custom). - `"connection"`: *[object](preface.html#definition-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](preface.html#definition-string)>, optional* Hostname or IP address of Elasticsearch. Default: `localhost` * `"port"`: *configuration expression<[number](preface.html#definition-number)>, optional* The port used by Elasticsearch. The value must be between 0 and 65535. Default: `9200` * `"useSSL"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Setting to use or not use SSL/TLS to connect to Elasticsearch. Default: `false` * `"username"`: *configuration expression<[string](preface.html#definition-string)>, optional* Username when basic authentication is enabled through Elasticsearch Shield. * `"password"`: *configuration expression<[string](preface.html#definition-string)>, optional* Password when basic authentication is enabled through Elasticsearch Shield. - `"indexMapping"`: *[object](preface.html#definition-object), optional* Defines how an audit event and its fields are stored and indexed. * `"indexName"`: *configuration expression<[string](preface.html#definition-string)>, optional* The index name. Set this parameter if the default name `audit` conflicts with an existing Elasticsearch index. Default: `audit`. - `"buffering"`: *[object](preface.html#definition-object), optional* Settings for buffering events and batch writes. * `"enabled"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Setting to use or not use log buffering. Default: false. * `"writeInterval"`: *configuration expression<[duration](preface.html#definition-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](preface.html#definition-number)>, optional* The maximum number of event messages in a batch write to Elasticsearch for each `writeInterval`. Default: 500 * `"maxSize"`: *configuration expression<[number](preface.html#definition-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, read [Audit the deployment](../maintenance-guide/auditing.html). ```json { "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](../_attachments/apidocs/org/forgerock/audit/handlers/elasticsearch/ElasticsearchAuditEventHandler.html) ## 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](#AuditService). To configure IG 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 ```json { "class": "org.forgerock.audit.handlers.jdbc.JdbcAuditEventHandler", "config": { "name": configuration expression, "topics": [ configuration expression, ... ], "databaseType": configuration expression, "enabled": configuration expression, "buffering": { "enabled": configuration expression, "writeInterval": configuration expression, "autoFlush": configuration expression, "maxBatchedEvents": configuration expression, "maxSize": configuration expression, "writerThreads": configuration expression }, "connectionPool": { "driverClassName": configuration expression, "dataSourceClassName": configuration expression, "jdbcUrl": configuration expression, "username": configuration expression, "password": configuration expression, "autoCommit": configuration expression, "connectionTimeout": configuration expression, "idleTimeout": configuration expression, "maxLifetime": configuration expression, "minIdle": configuration expression, "maxPoolSize": configuration expression, "poolName": configuration expression }, "tableMappings": [ { "event": configuration expression, "table": configuration expression, "fieldToColumn": map or configuration expression } ] } } ``` ### Configuration * `"name"`: *configuration expression<[string](preface.html#definition-string)>, required* The name of the event handler. - `"topics"`: *array of configuration expression<[strings](preface.html#definition-string)>, required* 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 `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 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, refer to [Record custom audit events](../configure/extending.html#audit-custom). - `"databaseType"`: *configuration expression<[string](preface.html#definition-string)>, required* The database type name. Built-in support is provided for `oracle`, `mysql`, and `h2`. - `"enabled"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Whether this event handler is active. Default: true. - `"buffering"`: *[object](preface.html#definition-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](preface.html#definition-boolean)>, optional* Whether log buffering is enabled. Default: false. * `"writeInterval"`: *configuration expression<[duration](preface.html#definition-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](preface.html#definition-boolean)>, optional* Whether the events are automatically flushed after being written. Default: true. * `"maxBatchedEvents"`: *configuration expression<[number](preface.html#definition-number)>, optional* The maximum number of event messages batched into a [PreparedStatement](https://docs.oracle.com/en/java/javase/17/docs/api/java.sql/java/sql/PreparedStatement.html). Default: 100. * `"maxSize"`: : *configuration expression<[number](preface.html#definition-number)>, optional* The maximum size of the queue of buffered event messages. Default: 5000. * `"writerThreads"`: *configuration expression<[number](preface.html#definition-number)>, optional* The number of threads to write buffered event messages to the database. Default: 1. - `"connectionPool"`: *[object](preface.html#definition-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](preface.html#definition-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](preface.html#definition-string)>, optional* The class name of the data source for the database. * `"jdbcUrl"`: *configuration expression<[string](preface.html#definition-string)>, required* The JDBC URL to connect to the database. * `"username"`: *configuration expression<[string](preface.html#definition-string)>, required* The username identifier for the database user with access to write the messages. * `"password"`: *configuration expression<[number](preface.html#definition-number)>, optional* The password for the database user with access to write the messages. * `"autoCommit"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Whether to commit transactions automatically when writing messages. Default: true. * `"connectionTimeout"`: *configuration expression<[number](preface.html#definition-number)>, optional* The number of milliseconds to wait for a connection from the pool before timing out. Default: 30000. * `"idleTimeout"`: *configuration expression<[number](preface.html#definition-number)>, optional* The number of milliseconds to allow a database connection to remain idle before timing out. Default: 600000. * `"maxLifetime"`: *configuration expression<[number](preface.html#definition-number)>, optional* The number of milliseconds to allow a database connection to remain in the pool. Default: 1800000. * `"minIdle"`: *configuration expression<[number](preface.html#definition-number)>, optional* The minimum number of idle connections in the pool. Default: 10. * `"maxPoolSize"`: *configuration expression<[number](preface.html#definition-number)>, optional* The maximum number of connections in the pool. Default: 10. * `"poolName"`: *configuration expression<[string](preface.html#definition-string)>, optional* The name of the connection pool. - `"tableMappings"`: *array of [objects](preface.html#definition-object), required* Table mappings for directing event content to database table columns. A table mappings object has the following fields: * `"event"`: *configuration expression<[string](preface.html#definition-string)>, required* The audit event that the table mapping is for. Set this to `access`. * `"table"`: *configuration expression<[string](preface.html#definition-string)>, required* The name of the database table that corresponds to the mapping. * `"fieldToColumn"`: *map or configuration expression<[map](preface.html#definition-map)>, required* A map of one or more data pairs with the format `Map`, 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: ```json { "fieldToColumn": { "string": "configuration expression", ... } } ``` ```json { "fieldToColumn": "configuration expression" } ``` 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: ```json { "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](../maintenance-guide/auditing.html#audit-jdbc). In the following example, IG events are logged to an h2 database: ```json { "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](../_attachments/apidocs/org/forgerock/audit/handlers/jdbc/JdbcAuditEventHandler.html) ## 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](http://docs.oracle.com/javaee/6/tutorial/doc/bncdx.html) 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](http://docs.oracle.com/javaee/6/tutorial/doc/bncdx.html#bnced) 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](http://activemq.apache.org/), but you can choose a different JMS message broker. | Declare the configuration in an audit service, as described in [AuditService](#AuditService). ### Usage ```json { "name": string, "type": "AuditService", "config": { "config": {}, "eventHandlers": [ { "class": "org.forgerock.audit.handlers.jms.JmsAuditEventHandler", "config": { "name": configuration expression, "topics": [ configuration expression, ... ], "deliveryMode": configuration expression, "sessionMode": configuration expression, "jndi": { "contextProperties": map, "topicName": configuration expression, "connectionFactoryName": configuration expression } } }] } } ``` The values in this configuration object can use configuration expressions, as described in [Configuration and Runtime Expressions](Expressions.html#expression-runtime-configtime). ### Configuration For a list of properties in the `"config"` object, refer to [JMS Audit Event Handler](https://docs.pingidentity.com/pingidm/7.4/audit-guide/audit-config-prop-jms.html) in IDM's *Integrator's guide*. * `"name"`: *configuration expression<[string](preface.html#definition-string)>, required* The name of the event handler. - `"topics"`: *array of configuration expression<[strings](preface.html#definition-string)>, required* 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 `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 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, refer to [Record custom audit events](../configure/extending.html#audit-custom). * `"deliveryMode"`: *configuration expression<[string](preface.html#definition-string)>, required* Delivery mode for messages from a JMS provider. Set to `PERSISTENT` or `NON_PERSISTENT`. * `"sessionMode"`: *configuration expression<[string](preface.html#definition-string)>, required* Acknowledgement mode in sessions without transactions. Set to `AUTO`, `CLIENT`, or `DUPS_OK`. * `"contextProperties"`:\_[map](preface.html#definition-map), optional\_ Settings with which to populate the initial context. The map values are evaluated as configuration expression<[strings](preface.html#definition-string)>. 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: ```none 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](preface.html#definition-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](preface.html#definition-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](../maintenance-guide/auditing.html#audit-jms). ```json { "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](../_attachments/apidocs/org/forgerock/audit/handlers/jms/JmsAuditEventHandler.html) ## 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](#AuditService). ### Usage ```json { "name": string, "type": "AuditService", "config": { "config": {}, "eventHandlers": [ { "class": "org.forgerock.audit.handlers.json.JsonAuditEventHandler", "config": { "name": configuration expression, "topics": [ configuration expression, ... ], "logDirectory": configuration expression, "elasticsearchCompatible": configuration expression, "fileRotation": { "rotationEnabled": configuration expression, "maxFileSize": configuration expression, "rotationFilePrefix": configuration expression, "rotationFileSuffix": configuration expression, "rotationInterval": configuration expression, "rotationTimes": [ configuration expression, ... ] }, "fileRetention": { "maxNumberOfHistoryFiles": configuration expression, "maxDiskSpaceToUse": configuration expression, "minFreeSpaceRequired": configuration expression }, "rotationRetentionCheckInterval": configuration expression, "buffering": { "writeInterval": configuration expression, "maxSize": configuration expression } } }] } } ``` ### Configuration * `"name"`: *configuration expression<[string](preface.html#definition-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](preface.html#definition-string)>, required* 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 `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 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, refer to [Record custom audit events](../configure/extending.html#audit-custom). - `"logDirectory"`: *configuration expression<[string](preface.html#definition-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](preface.html#definition-boolean)>, optional* Set to `true` to enable compatibility with ElasticSearch JSON format. For more information, refer to the [ElasticSearch](https://www.elastic.co/guide/en/logstash/current/index.html) documentation. Default: `false` * `"fileRotation"`: *[object](preface.html#definition-object), optional* File rotation settings for log files. * `"rotationEnabled"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* A flag to enable rotation of log files. Default: false. * `"maxFileSize"`: *configuration expression<[number](preface.html#definition-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](preface.html#definition-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](preface.html#definition-string)>, optional* The suffix to add to a log file on rotation, possibly expressed in [SimpleDateFormat](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/text/SimpleDateFormat.html). 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](preface.html#definition-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](preface.html#definition-duration)>, optional* The durations, counting from midnight, after which to rotate files. The following example schedules rotation six and twelve hours after midnight: ```json "rotationTimes": [ "6 hours", "12 hours" ] ``` This has the effect of enabling time-based file rotation. * `"fileRetention"`: *[object](preface.html#definition-object), optional* File retention settings for log files. * `"maxNumberOfHistoryFiles"`: *configuration expression<[number](preface.html#definition-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](preface.html#definition-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](preface.html#definition-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](preface.html#definition-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. Default: 5 seconds * `"buffering"`: *[object](preface.html#definition-object), optional* Settings for buffering events and batch writes. * `"writeInterval"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* The interval at which to send buffered event messages. If buffering is enabled, this interval must be greater than 0. Default: 1 second * `"maxSize"`: *configuration expression<[number](preface.html#definition-number)>, optional* The maximum number of event messages in the queue of buffered event messages. Default: 10000 ### Example For an example of setting up and testing this configuration, see [Recording Access Audit Events in JSON](../maintenance-guide/auditing.html#audit-json). ### More information [org.forgerock.audit.handlers.json.JsonAuditEventHandler](../_attachments/apidocs/org/forgerock/audit/handlers/json/JsonAuditEventHandler.html) ## JsonStdoutAuditEventHandler Logs events to JSON standard output (stdout). Declare the configuration in an audit service, as described in [AuditService](#AuditService). ### Usage ```json { "name": string, "type": "AuditService", "config": { "config": {}, "eventHandlers": [ { "class": "org.forgerock.audit.handlers.json.stdout.JsonStdoutAuditEventHandler", "config": { "name": configuration expression, "topics": [ configuration expression, ... ], "elasticsearchCompatible": configuration expression } } } } ``` ### Configuration * `"name"`: *configuration expression<[string](preface.html#definition-string)>, required* The name of the event handler. - `"topics"`: *array of configuration expression<[strings](preface.html#definition-string)>, required* 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 `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 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, refer to [Record custom audit events](../configure/extending.html#audit-custom). - `elasticsearchCompatible`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Set to `true` to enable compatibility with ElasticSearch JSON format. For more information, refer to the [ElasticSearch](https://www.elastic.co/guide/en/logstash/current/index.html) documentation. Default: `false` ### Example In the following example, a JsonStdoutAuditEventHandler logs audit events. For an example of setting up and testing this configuration, refer to [Recording access audit events to standard output](../maintenance-guide/auditing.html#audit-jsonstdout). ```json { "name": "30-jsonstdout", "baseURI": "http://app.example.com:8081", "condition": "${find(request.uri.path, '^/home/jsonstdout-audit')}", "heap": [ { "name": "AuditService", "type": "AuditService", "config": { "eventHandlers": [ { "class": "org.forgerock.audit.handlers.json.stdout.JsonStdoutAuditEventHandler", "config": { "name": "jsonstdout", "elasticsearchCompatible": false, "topics": [ "access" ] } } ], "config": {} } } ], "auditService": "AuditService", "handler": "ReverseProxyHandler" } ``` ### More information [org.forgerock.audit.handlers.json.stdout.JsonStdoutAuditEventHandler](../_attachments/apidocs/org/forgerock/audit/handlers/json/stdout/JsonStdoutAuditEventHandler.html) ## NoOpAuditService Provides an empty audit service to the top-level heap and its child routes. Use NoOpAuditService to prevent routes from using the parent audit service, when an AuditService is not explicitly defined. For information about how to override the default audit service, refer to [Audit framework](AuditFramework.html). ### Usage ```json { "name": "AuditService", "type": "NoOpAuditService" } ``` ```json "auditService": "NoOpAuditService" ``` ### More information [AuditService](#AuditService) [org.forgerock.openig.audit.NoOpAuditService](../_attachments/apidocs/org/forgerock/openig/audit/NoOpAuditService.html) ## SyslogAuditEventHandler An audit event handler that responds to events by logging messages to the UNIX system log as governed by RFC 5424, [The Syslog Protocol](https://www.rfc-editor.org/rfc/rfc5424). Declare the configuration in an audit service, as described in [AuditService](#AuditService). ### Usage ```json { "class": "org.forgerock.audit.handlers.syslog.SyslogAuditEventHandler", "config": { "name": configuration expression, "topics": [ configuration expression, ... ], "protocol": configuration expression, "host": configuration expression, "port": configuration expression, "connectTimeout": configuration expression, "facility": configuration expression, "buffering": { "enabled": configuration expression, "maxSize": configuration expression }, "severityFieldMappings": [ { "topic": configuration expression, "field": configuration expression, "valueMappings": { "field-value": object } } ] } } ``` 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, refer to [Expressions](Expressions.html#Expressions). ### Configuration * `"name"`: *configuration expression<[string](preface.html#definition-string)>, required* The name of the event handler. - `"topics"`: *array of configuration expression<[strings](preface.html#definition-string)>, required* 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 `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 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, refer to [Record custom audit events](../configure/extending.html#audit-custom). * `"protocol"`: *configuration expression<[string](preface.html#definition-string)>, required* The transport protocol used to send event messages to the Syslog daemon. Set this to `TCP` for Transmission Control Protocol, or to `UDP` for User Datagram Protocol. * `"host"`: *configuration expression<[string](preface.html#definition-string)>, required* The hostname of the Syslog daemon to which to send event messages. The hostname must resolve to an IP address. * `"port"`: *configuration expression<[number](preface.html#definition-number)>, required* The port of the Syslog daemon to which to send event messages. The value must be between 0 and 65535. * `"connectTimeout"`: *configuration expression<[number](preface.html#definition-number)>, required when using TCP* The number of milliseconds to wait for a connection before timing out. * `"facility"`: *configuration expression<[enumeration](preface.html#definition-enumeration)>, required* The Syslog facility to use for event messages. Set to one of the following values: * `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 * `"buffering"`: *[object](preface.html#definition-object), optional* Buffering settings for writing to the system log facility. The default is for messages to be written to the log for each event. * `"enabled"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Whether log buffering is enabled. Default: false. * `"maxSize"`: *configuration expression<[number](preface.html#definition-number)>, optional* The maximum number of buffered event messages. Default: 5000. * `"severityFieldMappings"`: *[object](preface.html#definition-object), optional* Severity field mappings set the correspondence between audit event fields and Syslog severity values. The severity field mappings object has the following fields: * `"topic"`: *configuration expression<[string](preface.html#definition-string)>, required* The audit event topic to which the mapping applies. Set this to a value configured in `topics`. * `"field"`: *configuration expression<[string](preface.html#definition-string)>, required* The audit event field to which the mapping applies. Audit event fields use JSON pointer notation, and are taken from the JSON schema for the audit event content. * `"valueMappings"`: *[object](preface.html#definition-object), required* The map of audit event values to Syslog severities, where both the keys and the values are strings. Syslog severities are one of the following values: * `emergency`: System is unusable. * `alert`: Action must be taken immediately. * `critical`: Critical conditions. * `error`: Error conditions. * `warning`: Warning conditions. * `notice`: Normal but significant condition. * `informational`: Informational messages. * `debug`: Debug-level messages. ### Example The following example configures a Syslog audit event handler that writes to the system log daemon on `syslogd.example.com`, port `6514` over TCP with a timeout of 30 seconds. The facility is the first one for local use, and response status is mapped to Syslog informational messages: ```json { "class": "org.forgerock.audit.handlers.syslog.SyslogAuditEventHandler", "config": { "name": "MySyslogAuditEventHandler", "topics": ["access"], "protocol": "TCP", "host": "https://syslogd.example.com", "port": 6514, "connectTimeout": 30000, "facility": "local0", "severityFieldMappings": [ { "topic": "access", "field": "response/status", "valueMappings": { "FAILED": "INFORMATIONAL", "SUCCESSFUL": "INFORMATIONAL" } } ] } } ``` ### More information [org.forgerock.audit.handlers.syslog.SyslogAuditEventHandler](../_attachments/apidocs/org/forgerock/audit/handlers/syslog/SyslogAuditEventHandler.html) ## SplunkAuditEventHandler (deprecated) | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This object is deprecated; use [SyslogAuditEventHandler](SyslogAuditEventHandler.html) or [JsonAuditEventHandler](JsonAuditEventHandler.html) instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | The Splunk audit event handler logs IG events to a Splunk system. For an example of setting up and testing Splunk, see [Recording access audit events in Splunk](../maintenance-guide/auditing.html#audit-splunk). ### Usage Configure the SplunkAuditEventHandler within an [AuditService](#AuditService): ```json { "type": "AuditService", "config": { "config": {}, "eventHandlers": [{ "class": "org.forgerock.audit.handlers.splunk.SplunkAuditEventHandler", "config": { "name": configuration expression, "topics": [ configuration expression, ... ], "enabled": configuration expression, "connection": { "useSSL": configuration expression, "host": configuration expression, "port": configuration expression }, "buffering": { "maxSize": configuration expression, "writeInterval": configuration expression, "maxBatchedEvents": configuration expression }, "authzToken": configuration expression } }] } } ``` The SplunkAuditEventHandler relays audit events to Splunk 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. IG searches first for a handler named `SplunkAuditEventHandler`. If not found, IG searches for a client handler named `AuditClientHandler`. If not found, IG uses the route's default client handler, named `ClientHandler`. The following example configures a ClientHandler named `SplunkClientHandler`: ```json { "name": "SplunkClientHandler", "type": "ClientHandler", "config": {} } ``` The following example configures a ScriptableHandler named `AuditClientHandler`: ```json { "name": "AuditClientHandler", "type": "ScriptableHandler", "config": {} } ``` ### Configuration * `"name"`: *configuration expression<[string](preface.html#definition-string)>, required* The name of the event handler. - `"topics"`: *array of configuration expression<[strings](preface.html#definition-string)>, required* 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 `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 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, refer to [Record custom audit events](../configure/extending.html#audit-custom). - `"enabled"`: *configuration expression<[boolean](preface.html#definition-boolean)>, required* Specifies whether this audit event handler is enabled. - `"connection"`: *[object](preface.html#definition-object), optional* Connection settings for sending messages to the Splunk system. If this object is not configured, it takes default values for its fields. This object has the following fields: * `"useSSL"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Specifies whether IG should connect to the audit event handler instance over SSL. Default: `false` * `"host"`: *configuration expression<[string](preface.html#definition-string)>, optional* Hostname or IP address of the Splunk system. Default: `localhost` * `"port"`: *configuration expression<[number](preface.html#definition-number)>, optional* The dedicated Splunk port for HTTP input. Before you install Splunk, make sure this port is free. Otherwise, change the port number in Splunk and in the IG routes that use Splunk. Default: `8088` - `"buffering"`: *[object](preface.html#definition-object), optional* Settings for buffering events and batch writes. If this object is not configured, it takes default values for its fields. This object has the following fields: * `"maxSize"`: *configuration expression<[number](preface.html#definition-number)>, optional* The maximum number of event messages in the queue of buffered event messages. Default: 10000 * `"maxBatchedEvents"`: *configuration expression<[number](preface.html#definition-number)>, optional* The maximum number of event messages in a batch write to this event handler for each `writeInterval`. Default: 500 * `"writeInterval"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* The delay after which the writer thread is scheduled to run after encountering an empty event buffer. Default: 100 ms (units of 'ms' or 's' are recommended) - `"authzToken"`: *configuration expression<[string](preface.html#definition-string)>, required* The authorization token associated with the configured HTTP event collector. ### Example In the following example, IG events are logged to a Splunk system. ```json { "name": "30-splunk", "baseURI": "http://app.example.com:8081", "condition": "${find(request.uri.path, '^/home/splunk-audit')}", "heap": [ { "name": "AuditService", "type": "AuditService", "config": { "eventHandlers": [ { "class": "org.forgerock.audit.handlers.splunk.SplunkAuditEventHandler", "config": { "name": "splunk", "enabled": true, "authzToken": "", "connection": { "host": "localhost", "port": 8088, "useSSL": false }, "topics": [ "access" ], "buffering": { "maxSize": 10000, "maxBatchedEvents": 500, "writeInterval": "100 ms" } } } ] } } ], "auditService": "AuditService", "handler": "ReverseProxyHandler" } ``` For an example of setting up and testing this configuration, see [Recording Access Audit Events in Splunk](../maintenance-guide/auditing.html#audit-splunk). ### More information [org.forgerock.audit.handlers.splunk.SplunkAuditEventHandler](../_attachments/apidocs/org/forgerock/audit/handlers/splunk/SplunkAuditEventHandler.html)