Package org.forgerock.audit.handlers.elasticsearch

Class ElasticsearchAuditEventHandler

java.lang.Object
org.forgerock.audit.events.handlers.AuditEventHandlerBase
org.forgerock.audit.handlers.elasticsearch.ElasticsearchAuditEventHandler
All Implemented Interfaces:
AuditEventHandler, BatchConsumer
public class ElasticsearchAuditEventHandler extends AuditEventHandlerBase implements BatchConsumer
AuditEventHandler for Elasticsearch.

  • Constructor Details

    • ElasticsearchAuditEventHandler

      public ElasticsearchAuditEventHandler(ElasticsearchAuditEventHandlerConfiguration configuration, EventTopicsMetaData eventTopicsMetaData, org.forgerock.http.Client client)
      Create a new ElasticsearchAuditEventHandler instance.
      Parameters:
      configuration - Configuration parameters that can be adjusted by system administrators.
      eventTopicsMetaData - Meta-data for all audit event topics.
      client - HTTP client or null to use default client.

  • Method Details

    • startup

      public void startup() throws ResourceException
      Description copied from interface: AuditEventHandler
      Instruct this object that it is safe to initialize file handles and network connections.

      Reconfiguration of the AuditService and its handlers is achieved by replacing rather than modifying the existing objects. Therefore, it's essential that the replacements do not perform any I/O that would interfere with the operation of the objects they are replacing until the old objects are shutdown. For example, when shutting down an old instance of a file-based AuditEventHandler, the old instance may need to flush buffers, apply file rotation or retention policies, or even add line or block signatures as part of tamper evident logging. Any of these operations could be broken if two handler instances are operating on the same set of files simultaneously.

      Specified by:
      startup in interface AuditEventHandler
      Throws:
      ResourceException - if starting the AuditEventHandler fails

    • shutdown

      public void shutdown() throws ResourceException
      Description copied from interface: AuditEventHandler
      Instruct this object to flush any buffers and close any open file handles or network connections.
      Specified by:
      shutdown in interface AuditEventHandler
      Throws:
      ResourceException - if closing the AuditEventHandler fails

    • queryEvents

      public Promise<QueryResponse,ResourceException> queryEvents(org.forgerock.services.context.Context context, String topic, QueryRequest query, QueryResourceHandler handler)
      Queries the Elasticsearch Search API for audit events. Query some events from the provided topic.
      Specified by:
      queryEvents in interface AuditEventHandler
      Parameters:
      context - The context chain that initiated the event.
      topic - The topic on which query is performed.
      query - The request with the query.
      handler - The handler to process responses for the query.
      Returns:
      a promise with either a response or an exception

    • readEvent

      public Promise<ResourceResponse,ResourceException> readEvent(org.forgerock.services.context.Context context, String topic, String resourceId)
      Description copied from interface: AuditEventHandler
      Reads an event with the provided resource id from the provided topic.
      Specified by:
      readEvent in interface AuditEventHandler
      Parameters:
      context - The context chain that initiated the event.
      topic - The topic where event is read.
      resourceId - The identifier of the event.
      Returns:
      a promise with either a response or an exception

    • publishEvent

      public Promise<ResourceResponse,ResourceException> publishEvent(org.forgerock.services.context.Context context, String topic, JsonValue event)
      Description copied from interface: AuditEventHandler
      Publishes an event to the provided topic.

      Note for implementors, it is imperative that the supplied event is not modified in any way as this may cause undesirable behaviour where multiple handlers are configured. If the event must be modified, then make a copy of it and work with that.

      Specified by:
      publishEvent in interface AuditEventHandler
      Parameters:
      context - The context chain that initiated the event.
      topic - The topic where to publish the event.
      event - The event to publish - which should be considered immutable.
      Returns:
      a promise with either a response or an exception

    • publishSingleEvent

      protected Promise<ResourceResponse,ResourceException> publishSingleEvent(String topic, JsonValue event)
      Publishes a single event to the provided topic.
      Parameters:
      topic - The topic where to publish the event.
      event - The event to publish.
      Returns:
      a promise with either a response or an exception

    • addToBatch

      public void addToBatch(String topic, JsonValue event, StringBuilder payload) throws BatchException
      Adds an audit event to an Elasticsearch Bulk API payload.
      Specified by:
      addToBatch in interface BatchConsumer
      Parameters:
      topic - Event topic
      event - Event JSON payload
      payload - Elasticsearch Bulk API payload
      Throws:
      BatchException - indicates failure to add-to-batch

    • publishBatch

      public Promise<Void,BatchException> publishBatch(String payload)
      Publishes a Bulk API payload to Elasticsearch.
      Specified by:
      publishBatch in interface BatchConsumer
      Parameters:
      payload - Elasticsearch Bulk API payload
      Returns:
      a simple promise encapsulating any potential batch exception

    • buildBasicAuthHeaderValue

      protected String buildBasicAuthHeaderValue()
      Builds a basic authentication header-value, if username and password are provided in configuration.
      Returns:
      Basic authentication header-value or null if not configured

    • buildEventUri

      protected String buildEventUri(String topic, String eventId)
      Builds an Elasticsearch API URI for operating on a single event (e.g., index, get, etc.).
      Parameters:
      topic - Audit topic
      eventId - Event ID
      Returns:
      URI

    • buildBulkUri

      protected String buildBulkUri()
      Builds an Elasticsearch API URI for Bulk API.
      Returns:
      URI

    • buildSearchUri

      protected String buildSearchUri(String topic, int pageSize, int offset)
      Builds an Elasticsearch API URI for Search API.
      Parameters:
      topic - The audit topic to search.
      pageSize - The number of results to return.
      offset - The number of results to skip.
      Returns:
      The search uri.

    • buildBaseUri

      protected String buildBaseUri()
      Builds an Elasticsearch API base URI. The format is, 
      http[s]://host:port/indexName
      Returns:
      Base URI

    • resourceException

      protected static ResourceException resourceException(String indexName, String topic, String resourceId, org.forgerock.http.protocol.Response response)
      Gets an Exception Promise containing an Elasticsearch HTTP response status and payload.
      Parameters:
      indexName - Index name
      topic - Event topic
      resourceId - Event ID
      response - HTTP response
      Returns:
      Exception Promise