--- title: AuditService description: The audit service records access and notifications audit events. Learn how to record other types of audit events in Record custom audit events. component: pinggateway version: 2026 page_id: pinggateway:reference:AuditService canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/AuditService.html revdate: 2025-09-01T17:49:57Z section_ids: AuditService-usage: Usage AuditService-properties: Properties AuditService-example: Example AuditService-moreinfo: More information --- # AuditService The audit service records `access` and `notifications` audit events. Learn how to record other types of audit events in [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. 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: ```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, ...], "topicSchemasDirectory": configuration expression } } ``` ## 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, PingGateway 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. PingGateway supports the event handlers listed in [AuditFramework](AuditFramework.html). * `"topicSchemasDirectory"`: *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" } } } } ``` Source: [customTopic.json](../_attachments/audit-schemas/customTopic.json) ## 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.html) [org.forgerock.audit.AuditService](../_attachments/apidocs/org/forgerock/audit/AuditService.html)