Audit

Audit Service is responsible for collecting and logging audit events. Internal audit components are built on top of shared components provided by Wrensec Commons project.

OSGi service class

org.forgerock.openidm.audit.impl.AuditServiceImpl

OSGi persistent identifier

org.forgerock.openidm.audit

Configuration file

audit.json

Router mapping

/audit

Several Wren:IDM services capture user and system interactions (e.g. user authentication or object synchronization) and generate audit events that are being routed to the central audit service. Audit service then uses preconfigured audit event handlers to further process captured events (e.g. by storing them in a database table).

Audit events of all types contain common attributes that can be used to filter audit events or correlate related audit events. These attributes include:

  • _id – unique identification of audit event

  • timestamp – timestamp in ISO 8601 format with UTC time zone

  • eventName – type of audit event (see Audit Event Topics)

  • transactionId – identifier linking audit events to a single originating transaction

  • userId – identifier of user who invoked the given action

  • trackingIds – additional tracking identifiers to help correlating related audit events across multiple systems

Audit Event Topics

Audit service handles the following event topics:

  • access – access log for CREST endpoints

  • activity – CREST actions performed on a specific object (e.g. update of a managed user)

  • authentication – result for an authentication attempt

  • config – configuration changes

  • recon – reconciliation events for the whole reconciliation process and every processed object

  • sync – result of object synchronization operation (implicit synchronization)

Audit Handlers

Audit service provides several configurable handlers that participate in processing captured audit events. Following output handlers are available by default:

  • CsvAuditEventHandler – CSV files (access.csv, activity.csv, …​)

  • ElasticsearchAuditEventHandler – Elasticsearch full-text search engine

  • JmsAuditEventHandler – Java Message Service API processor

  • JsonAuditEventHandler – JSON files (acess.audit.json, activity.audit.json, …​)

  • RepositoryAuditEventHandler – tables in Wren:IDM database

  • RouterAuditEventHandler – any internal CREST API endpoint

  • SplunkAuditEventHandler – Splunk system

  • SyslogAuditEventHandler – Syslog server through Syslog protocol

For more information see audit module in wrensec-commons GitHub repository.

Configuration

The audit service is configured through audit.json file in project/conf directory. The following configuration properties are available:

  • auditServiceConfig

    • handlerForQueries – name of the audit log query handler (i.e. handler that will process audit log queries)

    • availableAuditEventHandlers – array of available audit handlers

    • filterPolicies – audit event filtering policies (policy determines whether audit event will be processed or not)

  • eventHandlers – audit event handler configuration

  • eventTopics – configuration of event topics (e.g. ignored actions / fields for the topic)

  • exceptionFormatter – script for formatting exceptions to be stored in audit events

Example of audit service configuration with two handlers (JsonAuditEventHandler and RepositoryAuditEventHandler):

{
  "auditServiceConfig" : {
    "handlerForQueries" : "repo",
    "availableAuditEventHandlers" : [
      "org.forgerock.audit.handlers.csv.CsvAuditEventHandler",
      "org.forgerock.audit.handlers.elasticsearch.ElasticsearchAuditEventHandler",
      "org.forgerock.audit.handlers.jms.JmsAuditEventHandler",
      "org.forgerock.audit.handlers.json.JsonAuditEventHandler",
      "org.forgerock.openidm.audit.impl.RepositoryAuditEventHandler",
      "org.forgerock.openidm.audit.impl.RouterAuditEventHandler",
      "org.forgerock.audit.handlers.splunk.SplunkAuditEventHandler",
      "org.forgerock.audit.handlers.syslog.SyslogAuditEventHandler"
    ],
    "filterPolicies" : {
      "value" : {
        "excludeIf" : [
          "/access/http/request/headers/Authorization",
          "/access/http/request/headers/X-OpenIDM-Password",
          "/access/http/request/cookies/session-jwt",
          "/access/http/response/headers/Authorization",
          "/access/http/response/headers/X-OpenIDM-Password"
        ],
        "includeIf" : [ ]
      }
    }
  },
  "eventHandlers" : [
    {
      "class" : "org.forgerock.audit.handlers.json.JsonAuditEventHandler",
      "config" : {
        "name" : "json",
        "logDirectory" : "&{launcher.working.location}/audit",
        "buffering" : {
          "maxSize" : 100000,
          "writeInterval" : "100 millis"
        },
        "topics" : [
          "access",
          "activity",
          "recon",
          "sync",
          "authentication",
          "config"
        ]
      }
    },
    {
      "class" : "org.forgerock.openidm.audit.impl.RepositoryAuditEventHandler",
      "config" : {
        "name" : "repo",
        "topics" : [
          "access",
          "activity",
          "recon",
          "sync",
          "authentication",
          "config"
        ]
      }
    }
  ],
  "eventTopics" : {
    "config" : {
      "filter" : {
        "actions" : [
          "create",
          "update",
          "delete",
          "patch",
          "action"
        ]
      }
    },
    "activity" : {
      "filter" : {
        "actions" : [
          "create",
          "update",
          "delete",
          "patch",
          "action"
        ]
      },
      "watchedFields" : [ ],
      "passwordFields" : [
        "password"
      ]
    }
  },
  "exceptionFormatter" : {
    "type" : "text/javascript",
    "file" : "bin/defaults/script/audit/stacktraceFormatter.js"
  }
}

With the preceding configuration audit event logs will be stored in the Wren:IDM database and also in the JSON files (located in audit directory).