PingGateway 2024.9

ElasticsearchAuditEventHandler (deprecated)

This object is deprecated; use one of the following objects instead:

For more information, refer to the Deprecated 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 document.

Usage

Configure the ElasticsearchAuditEventHandler within an AuditService:

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

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.

PingGateway searches first for a handler named ElasticsearchClientHandler. 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 ElasticsearchClientHandler:

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

The following example configures a ScriptableHandler named AuditClientHandler:

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

Properties

"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.

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

Hostname or IP address of Elasticsearch.

Default: localhost

"port": configuration expression<number>, optional

The port used by Elasticsearch. The value must be between 0 and 65535.

Default: 9200

"useSSL": configuration expression<boolean>, optional

Setting to use or not use SSL/TLS to connect to Elasticsearch.

Default: false

"username": configuration expression<string>, optional

Username when basic authentication is enabled through Elasticsearch Shield.

"password": configuration expression<string>, optional

Password when basic authentication is enabled through Elasticsearch Shield.

"indexMapping": object, optional

Defines how an audit event and its fields are stored and indexed.

"indexName": configuration expression<string>, optional

The index name. Set this parameter if the default name audit conflicts with an existing Elasticsearch index.

Default: audit.

"buffering": object, optional

Settings for buffering events and batch writes.

"enabled": configuration expression<boolean>, optional

Setting to use or not use log buffering.

Default: false.

"writeInterval": configuration expression<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>, optional

The maximum number of event messages in a batch write to Elasticsearch for each writeInterval.

Default: 500

"maxSize": configuration expression<number>, optional

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

Default: 10000

More information

org.forgerock.audit.handlers.elasticsearch.ElasticsearchAuditEventHandler