Auditing
Web Agent logs audit events for security, troubleshooting, and regulatory compliance.
Remote and local auditing
Remote auditing
In remote auditing, the agent logs events to the audit event handler configured in the AM realm. In an environment with several AM servers, the agent writes audit logs to the AM server that satisfies the agent request for client authentication or resource authorization.
The agent logs audit events remotely only when AM’s global audit logging is enabled and configured in the realm where the agent runs.
Set up global audit logging in the AM admin UI:
-
In the AM admin UI, go to Configure > Global Services > Audit logging.
-
Enable Audit logging.
-
Enter values to include in Field whitelist filters or Field blacklist filters.
The following example path in the Field whitelist filters list includes the
Accept-Language value in the http.request.headers field in access events:
/access/http/request/headers/accept-language
Learn more from AM’s Global audit logging.
Audit event logs
Audit logs are written in UTF-8 format. The following example shows an audit event log for successful access to a resource:
{
"timestamp":"2023-10-30T11:56:57Z",
"eventName":"AM-ACCESS-OUTCOME",
"transactionId":"608...77e",
"userId":"id=demo,ou=user,dc=openam,dc=forgerock,dc=org",
"trackingIds":[
"fd5...095",
"fd5...177"
],
"component":"Web Policy Agent",
"realm":"/",
"server":{
"ip":"127.0.0.1",
"port":8020
},
"request":{
"protocol":"HTTP/1.1",
"operation":"GET"
},
"http":{
"request":{
"secure":false,
"method":"GET",
"path":"/examples",
"cookies":{
"am-auth-jwt":"eyJ...iOi[...]"
"i18next":"en",
"amlbcookie":"01",
"iPlanetDirectoryPro":"Ts2...oxR[...]"
}
}
},
"response":{
"status":"DENIED"
},
"_id":"fd5...703" //This ID is internal to AM and available only in remote logs.
}The audit log format uses the log structure shared by the Ping Identity Platform. Learn more from Audit log format in AM’s Security guide.
Web Agent supports propagation of the transaction ID across the Ping Identity Platform,
using the HTTP header X-ForgeRock-TransactionId. Learn more from
Trust transaction headers
in AM’s Security guide.
Configure auditing
By default, auditing is disabled. Configure audit logging as follows:
-
On the AM admin UI, select REALMS > Realm Name > Applications > Agents > Web > Agent Name.
-
On the Global tab, select the following options to select the type of audit events to log and the audit location. By default, auditing is disabled:
-
In
agent.conf, optionally configure Audit Path as Full URL to log the full URL of the HTTP request. If not configured, only the path component of the HTTP request is logged. -
In
agent.conf, optionally configure the following properties to manage the location and size of the log files:After changing a bootstrap property, restart the web server where the agent runs.