How To
ForgeRock Identity Cloud

How do I extend auditing in Identity Cloud to include additional fields?

Last updated Oct 18, 2021

The purpose of this article is to provide information on extending Identity Cloud auditing to include additional fields for managed object activities. For example, you might want to include before and after values for changes to a user's email address or last name in your audit logs.


Overview

By default, Identity Cloud provides auditing on the managed object fields that are safe to log. You can include additional fields by adding them to the includeIf property in the audit configuration. For example, you might want to include before and after fields for certain activities, such as changes to a user's email address or last name, in your audit log.

You can only make configuration changes in your Development environment. ForgeRock then promotes configuration from Development to Staging and then to Production. See Understanding Identity Cloud environments and promotion process for further information.

Caution

When adding non-safelisted audit event fields, be mindful of the type of information that you intend to expose in the logs. For example, you may need to keep personally identifiable information (PII) out of the logs.

Adding additional fields to audit logging

Before you can access the audit configuration, you will need an access token to authenticate to the Identity Cloud REST API. See Authenticate to Identity Cloud REST API with Access Token for further information.

Note

It is recommended that you back up your audit configuration before making any changes.

Add the fields to audit logging as follows:

  1. Retrieve the existing audit configuration, for example: $ curl \ --request GET 'https://<YourTenantName>.forgerock.io/openidm/config/audit' \ --header 'authorization: Bearer <access-token>' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/javascript, */*; q=0.01'

replacing <YourTenantName> with your Identity Cloud tenant and <access-token> with the access token you obtained when you authenticated to the Identity Cloud REST API. 

  1. Make a backup of the audit configuration before updating it.
  2. Update the includeIf property (under filterPolicies ) to include the fields you want to add. For example: "includeIf": [   "/activity/before/mail",    "/activity/after/mail"    "/activity/before/sn",    "/activity/after/sn"   ]In this example, you would use the following curl command to update the audit configuration:$ curl --request PUT 'https://<YourTenantName>.forgerock.io/openidm/config/audit' \ --header 'authorization: Bearer <access-token>' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/javascript, */*; q=0.01' \ --data-raw '{    "_id": "audit",     "auditServiceConfig": {         "handlerForQueries": "json",         "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.audit.handlers.json.stdout.JsonStdoutAuditEventHandler",             "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/cookies/&{com.iplanet.am.cookie.name}",                     "/access/http/request/cookies/session-jwt",                     "/access/http/request/headers/&{com.sun.identity.auth.cookieName}",                     "/access/http/request/headers/&{com.iplanet.am.cookie.name}",                     "/access/http/request/headers/accept-encoding",                     "/access/http/request/headers/accept-language",                     "/access/http/request/headers/Authorization",                     "/access/http/request/headers/cache-control",                     "/access/http/request/headers/connection",                     "/access/http/request/headers/content-length",                     "/access/http/request/headers/content-type",                     "/access/http/request/headers/proxy-authorization",                     "/access/http/request/headers/X-OpenAM-Password",                     "/access/http/request/headers/X-OpenIDM-Password",                     "/access/http/request/queryParameters/access_token",                     "/access/http/request/queryParameters/IDToken1",                     "/access/http/request/queryParameters/id_token_hint",                     "/access/http/request/queryParameters/Login.Token1",                     "/access/http/request/queryParameters/redirect_uri",                     "/access/http/request/queryParameters/requester",                     "/access/http/request/queryParameters/sessionUpgradeSSOTokenId",                     "/access/http/request/queryParameters/tokenId",                     "/access/http/response/headers/Authorization",                     "/access/http/response/headers/Set-Cookie",                     "/access/http/response/headers/X-OpenIDM-Password"                 ],                 "includeIf": [                     "/activity/before/mail",                     "/activity/after/mail"                     "/activity/before/sn",                     "/activity/after/sn"                 ]             }         },         "caseInsensitiveFields": [             "/access/http/request/headers",             "/access/http/response/headers"         ]     },     "eventHandlers": [         {             "class": "org.forgerock.audit.handlers.json.JsonAuditEventHandler",             "config": {                 "name": "json",                 "logDirectory": "&{idm.data.dir}/audit",                 "buffering": {                     "maxSize": 100000,                     "writeInterval": "100 millis"                 },                 "topics": [                     "access",                     "activity",                     "sync",                     "authentication",                     "config"                 ]             }         },         {             "class": "org.forgerock.openidm.audit.impl.RepositoryAuditEventHandler",             "config": {                 "name": "repo",                 "enabled": false,                 "topics": [                     "access",                     "activity",                     "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"     } }'replacing <YourTenantName> with your Identity Cloud tenant and <access-token> with the access token you obtained when you authenticated to the Identity Cloud REST API.

Audit logs for idm-activity and idm-everything sources now include the fields you have added. For example, the following entry in a sample activity log shows a change to a user's last name (from Brown to Granger) and email address (from jbrown@example.com to jgranger@example.com):

{         "payload" : {             "message" : "",             "runAs" : "bd220328-9762-458b-b05a-982ac3c7fc54",             "transactionId" : "1630683558570-abec9e9304c84ad368ba-28676/0",             "before" : {                "sn" : "Brown",                "mail" : "jbrown@example.com"             },             "operation" : "PATCH",             "passwordChanged" : false,             "_id" : "52f7cea0-285d-4ef6-bda3-83256dda71c5-1300250",             "revision" : "00000000412cae36",             "eventName" : "activity",             "userId" : "bd220328-9762-458b-b05a-982ac3c7fc54",             "status" : "SUCCESS",             "objectId" : "managed/alpha_user/ce7492dc-8759-47b3-b4ee-eda8d4de4ab1",             "timestamp" : "2021-09-03T15:39:42.862Z",             "changedFields" : [],             "after" : {                "sn" : "Granger",                "mail" : "jgranger@example.com"             }          },          "type" : "application/json",          "timestamp" : "2021-09-03T15:39:44.040095219Z"       }

See View Audit Logs for further information on viewing audit logs for Identity Cloud.

Note

Identity Cloud stores audit data for 30 days. To keep audit data for longer, you'll need to store it in your own data stores. Currently, you can only gather audit logs by pulling them from the REST API endpoint (/monitoring/logs).

See Also

What logging sources are available in Identity Cloud?

Use Policies to Filter Audit Data

Promote Configuration


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.