PingGateway 2024.9

SplunkAuditEventHandler (deprecated)

This object is deprecated; use SyslogAuditEventHandler or JsonAuditEventHandler instead. For more information, refer to the Deprecated section of the Release Notes.

The Splunk audit event handler logs PingGateway events to a Splunk system.

For an example of setting up and testing Splunk, see Recording access audit events in Splunk.

Usage

Configure the SplunkAuditEventHandler within an AuditService:

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

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.

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

The following example configures a ClientHandler named SplunkClientHandler:

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

The following example configures a ScriptableHandler named AuditClientHandler:

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

Configuration

"name": configuration expression<string>, required

The name of the event handler.

"topics": array of configuration expression<strings>, required

One or more topics that this event handler intercepts. PingGateway can record the following audit event topics:

  • access: Log access audit events. Access audit events occur at the system boundary, and include the arrival of the initial request and departure of the final response.

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

  • customTopic: Log custom audit events. To create a topic for a custom audit event, include a JSON schema for the topic in your PingGateway configuration.

    To record custom audit events, configure AuditService in the heap, and refer to it from the route or subroutes. For an example of how to set up custom audit events, refer to Record custom audit events.

"enabled": configuration expression<boolean>, required

Specifies whether this audit event handler is enabled.

"connection": 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>, optional

Specifies whether PingGateway should connect to the audit event handler instance over SSL.

Default: false

"host": configuration expression<string>, optional

Hostname or IP address of the Splunk system.

Default: localhost

"port": configuration expression<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 PingGateway routes that use Splunk.

Default: 8088

"buffering": 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>, optional

The maximum number of event messages in the queue of buffered event messages.

Default: 10000

"maxBatchedEvents": configuration expression<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>, 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>, required

The authorization token associated with the configured HTTP event collector.

Example

In the following example, PingGateway events are logged to a Splunk system.

{
  "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": "<splunk-authorization-token>",
              "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.

More information

org.forgerock.audit.handlers.splunk.SplunkAuditEventHandler