AuditService

Configure the audit service, based on the ForgeRock common audit event framework:

  • To record access audit events, configure AuditService inline in a route, or in the heap.

  • To record custom audit events, configure AuditService in the heap, and refer to it from the route or subroutes.

    For information about how to configure custom audit events, see "Recording Custom Audit Events".

Default Audit Service

By default, there is no auditing of a configuration. The NoOpAuditService provides an empty audit service to the top-level heap and its child routes.

To configure auditing for the whole configuration, define an AuditService object named AuditService in the top-level heap.

To prevent a route from inheriting the NoOpAuditService or a parent audit service, do one of the following:

  • Define an AuditService object named AuditService in the route heap. No other configuration is required.

  • Configure the Route property auditService with an inline audit service or a reference to an AuditService object defined in the route heap or a parent heap.

For more information, see "NoOpAuditService".

Usage

{
  "name": string,
  "type": "AuditService",
  "config": {
    "config": object,
    "eventHandlers": array,
    "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.

The configuration object has the following fields:

"handlerForQueries": string, optional

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

"availableAuditEventHandlers": array of strings, optional

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

"caseInsensitiveFields": array of 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 whitelist to specify which event fields appear in the logs. By default, only event fields that are whitelisted are included in the audit event logs.

For more information about whitelisting, see "Safelisting Audit Event Fields for the Logs".

"field": object, optional

This property specifies non-whitelisted event fields to include in the logs, and whitelisted 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 whitelisted event fields in the logs.

"includeIf": array of strings, optional

A list of non-whitelisted 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.

Important

Before you include non-whitelisted 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 strings, optional

A list of whitelisted 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 configuration 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. IG supports the event handlers listed in Audit Framework.

"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 (on Windows, %appdata%\OpenIG\audit-schemas)

For an example of how to configure custom audit events, see "Recording 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"
}
Read a different version of :