Use policies to filter audit data

In addition to event-based filtering, you can use policies to include or exclude specific information in the audit logs. By default, IDM safelists fields that are safe to log. To include or exclude additional fields or values, edit conf/audit.json:

"filterPolicies" : {
    "value" : {
        "excludeIf" : [ ],
        "includeIf" : [ ]
    }
}

Although you can’t edit the default safelist, IDM processes the safelist before the blocklist, so any items added to excludeIf override their safelist status.

To specify data to exclude from audit logs, use the excludeIf property.
- To exclude an entire field, use the field property.
- To exclude a field that contains a specific value, use the value property.
To specify data to include in custom audit event logs, use the includeIf property.

This setting has no effect on default audit event topics.

Default audit log safelists by event topic

Access Safelist

/_id
/timestamp
/eventName
/transactionId
/trackingIds
/userId
/client
/server
/http/request/secure
/http/request/method
/http/request/path
/http/request/headers/accept
/http/request/headers/accept-api-version
/http/request/headers/content-type
/http/request/headers/host
/http/request/headers/user-agent
/http/request/headers/x-forwarded-for
/http/request/headers/x-forwarded-host
/http/request/headers/x-forwarded-port
/http/request/headers/x-forwarded-proto
/http/request/headers/x-original-uri
/http/request/headers/x-real-ip
/http/request/headers/x-request-id
/http/request/headers/x-requested-with
/http/request/headers/x-scheme
/request
/response
/roles

Activity Safelist

/_id
/timestamp
/eventName
/transactionId
/trackingIds
/userId
/runAs
/objectId
/operation
/changedFields
/revision
/status
/message
/passwordChanged
/context
/provider

Authentication Safelist

/_id
/timestamp
/eventName
/transactionId
/trackingIds
/userId
/principal
/entries
/result
/provider
/method

Configuration Safelist

/_id
/timestamp
/eventName
/transactionId
/trackingIds
/userId
/runAs
/objectId
/operation
/changedFields
/revision

Reconciliation Safelist

/_id
/action
/ambiguousTargetObjectIds
/entryType
/eventName
/exception
/linkQualifier
/mapping
/message
/messageDetail
/reconAction
/reconciling
/reconId
/situation
/sourceObjectId
/status
/targetObjectId
/timestamp
/trackingIds
/transactionId
/userId

Synchronization Safelist

/_id
/action
/eventName
/exception
/linkQualifier
/mapping
/message
/messageDetail
/situation
/sourceObjectId
/status
/targetObjectId
/timestamp
/trackingIds
/transactionId
/userId

Configure audit filter policies in the admin UI

From the navigation bar, click Configure > System Preferences.
On the System Preferences page, click the Audit tab.

The Audit Filter Policy area displays the policies that exist in conf/audit.json.
Make changes in the Audit Filter Policy area, and click Save.

Audit filter example

A typical use case for filtering audit data by policy is to keep personally identifiable information (PII) out of the logs. To exclude a specific field from the audit logs, add the field to the filterPolicies element, as follows:

"filterPolicies" : {
    "value" : {...}
    "field" : {
        "excludeIf" : [
            "/eventTopic/objectURI"
        ]
    }
}

Consider the following entry in a sample activity log, showing a change to the telephoneNumber field for a user:

{
  "_id": "334ed888-3179-4990-b475-c1982403f063-27593",
  "timestamp": "2021-11-09T23:33:25.802Z",
  "eventName": "activity",
  "transactionId": "334ed888-3179-4990-b475-c1982403f063-27554",
  "userId": "openidm-admin",
  "runAs": "openidm-admin",
  "objectId": "managed/user/ba46c2cc-e897-4a69-bb3c-a0c83d9f88bb",
  "operation": "PATCH",
  "changedFields": [],
  "revision": "d4907846-7a84-4da6-898c-a8c9b6f992c5-1210",
  "status": "SUCCESS",
  "message": "",
  "passwordChanged": false
}

Because the default Activity Safelist doesn’t contain telephoneNumber, the change isn’t reflected in the audit log.

To include the before and after telephone number in the activity audit log, add the following filter policy to conf/audit.json:

"filterPolicies" : {
  "field" : {
    "excludeIf" : [ ],
    "includeIf" : [
      "/activity/before/telephoneNumber",
      "/activity/after/telephoneNumber" ]
}

With this configuration, a similar change would appear in the activity log as:

{
  "before": {
    "telephoneNumber": "360-555-5566"
  },
  "after": {
    "telephoneNumber": "360-555-5555"
  },
  "_id": "334ed888-3179-4990-b475-c1982403f063-28385",
  "timestamp": "2021-11-09T23:35:51.718Z",
  "eventName": "activity",
  "transactionId": "334ed888-3179-4990-b475-c1982403f063-28346",
  "userId": "openidm-admin",
  "runAs": "openidm-admin",
  "objectId": "managed/user/ba46c2cc-e897-4a69-bb3c-a0c83d9f88bb",
  "operation": "PATCH",
  "changedFields": [],
  "revision": "d4907846-7a84-4da6-898c-a8c9b6f992c5-1242",
  "status": "SUCCESS",
  "message": "",
  "passwordChanged": false
}

By default, the /access/http/request/headers and /access/http/response/headers fields are considered case-insensitive for filtering. All other fields are considered case-sensitive.

To specify that a value should be filtered, regardless of case, add the caseInsensitiveFields property to your audit configuration, including an array of fields that should be considered case-insensitive. Fields are referenced using JSON pointer syntax and the array of fields can be empty.

With the following configuration, the audit service excludes cookies named session-jwt and session-JWT from the log:

"caseInsensitiveFields" : [
    "http.request.cookies"
],

PingIDM 7.5.0

Use policies to filter audit data

Default audit log safelists by event topic

Configure audit filter policies in the admin UI

Audit filter example