--- title: Use policies to filter audit data description: Configure filter policies in PingIDM to include or exclude specific fields and values in audit logs, and view the default safelists for each event topic component: pingidm version: 8.1 page_id: pingidm:audit-guide:filtering-audit-policies canonical_url: https://docs.pingidentity.com/pingidm/8.1/audit-guide/filtering-audit-policies.html keywords: ["Audit", "Logs", "Configuration", "Filters", "Policies"] section_ids: audit-log-safelist: Default audit log safelists by event topic audit-filter-policy-ui: Configure audit filter policies in the admin UI audit_filter_example: Audit filter example --- # Use policies to filter audit data In addition to [event-based filtering](filtering-audit-events.html), 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`: ```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](audit-log-topics.html#default-audit-topics). | ## Default audit log safelists by event topic > **Collapse: 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 > **Collapse: Activity Safelist** > > * /\_id > > * /timestamp > > * /eventName > > * /transactionId > > * /trackingIds > > * /userId > > * /runAs > > * /objectId > > * /operation > > * /changedFields > > * /revision > > * /status > > * /message > > * /passwordChanged > > * /context > > * /provider > **Collapse: Authentication Safelist** > > * /\_id > > * /timestamp > > * /eventName > > * /transactionId > > * /trackingIds > > * /userId > > * /principal > > * /entries > > * /result > > * /provider > > * /method > **Collapse: Configuration Safelist** > > * /\_id > > * /timestamp > > * /eventName > > * /transactionId > > * /trackingIds > > * /userId > > * /runAs > > * /objectId > > * /operation > > * /changedFields > > * /revision > **Collapse: Reconciliation Safelist** > > * /\_id > > * /action > > * /ambiguousTargetObjectIds > > * /entryType > > * /eventName > > * /exception > > * /linkQualifier > > * /mapping > > * /message > > * /messageDetail > > * /reconAction > > * /reconciling > > * /reconId > > * /situation > > * /sourceObjectId > > * /status > > * /targetObjectId > > * /timestamp > > * /trackingIds > > * /transactionId > > * /userId > **Collapse: 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 1. From the navigation bar, click Configure > System Preferences. 2. On the System Preferences page, click the Audit tab. The Audit Filter Policy area displays the policies that exist in `conf/audit.json`. 3. 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: ```json "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: ```json { "_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](#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`: ```json "filterPolicies" : { "field" : { "excludeIf" : [ ], "includeIf" : [ "/activity/before/telephoneNumber", "/activity/after/telephoneNumber" ] } ``` With this configuration, a similar change would appear in the activity log as: ```json { "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:```json "caseInsensitiveFields" : [ "http.request.cookies" ], ``` |