PingGateway 2024.9

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