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.
IG searches first for a handler named ElasticsearchClientHandler.
If not found, IG searches for a client handler named
AuditClientHandler. If not found, IG 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. IG 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
accessaudit 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 IG 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
auditconflicts 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
Example
In the following example, an Elasticsearch audit event handler logs audit events for access. For an example of setting up and testing this configuration, refer to [maintenance-guide:].
{
"name": "30-elasticsearch",
"baseURI": "http://app.example.com:8081",
"condition": "${find(request.uri.path, '^/home/elasticsearch-audit')}",
"heap": [
{
"name": "AuditService",
"type": "AuditService",
"config": {
"eventHandlers": [
{
"class": "org.forgerock.audit.handlers.elasticsearch.ElasticsearchAuditEventHandler",
"config": {
"name": "elasticsearch",
"indexMapping": {
"indexName": "audit"
},
"connection": {
"host": "localhost",
"port": 9200,
"useSSL": false
},
"topics": [
"access"
]
}
}
]
}
}
],
"auditService": "AuditService",
"handler": "ReverseProxyHandler"
}