How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I configure audit logging via ssoadm in AM (All versions)?

Last updated May 18, 2021

The purpose of this article is to provide information on configuring audit logging via ssoadm in AM. This also includes information on adding, deleting and modifying audit event handlers.


Configuring audit logging

You can configure audit logging at either a global or realm level as required. The global and realm configuration options are described in Reference › Audit Logging with the equivalent ssoadm attribute names. Alternatively, you can return all the current settings to get you started using the ssoadm get-attr-defs command (global) or the ssoadm get-realm-svc-attrs command (realm). For example:

  • AM 7 and later: $ ./ssoadm get-attr-defs -s AuditService -t global -u uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org -f pwd.txt
  • Pre-AM 7: $ ./ssoadm get-attr-defs -s AuditService -t global -u amadmin -f pwd.txt

Example response:

auditEnabled=true fieldFilterPolicy=/access/http/request/queryParameters/tokenId fieldFilterPolicy=/access/http/request/headers/cache-control fieldFilterPolicy=/access/http/request/queryParameters/redirect_uri fieldFilterPolicy=/access/http/request/queryParameters/Login.Token1 fieldFilterPolicy=/access/http/request/headers/accept-language fieldFilterPolicy=/config/before fieldFilterPolicy=/access/http/request/headers/%AM_AUTH_COOKIE_NAME% fieldFilterPolicy=/config/after fieldFilterPolicy=/access/http/request/queryParameters/access_token fieldFilterPolicy=/access/http/request/headers/X-OpenAM-Password fieldFilterPolicy=/access/http/request/queryParameters/id_token_hint fieldFilterPolicy=/access/http/request/headers/proxy-authorization fieldFilterPolicy=/access/http/request/queryParameters/IDToken1 fieldFilterPolicy=/access/http/request/queryParameters/requester fieldFilterPolicy=/access/http/request/headers/connection fieldFilterPolicy=/access/http/request/queryParameters/sessionUpgradeSSOTokenId fieldFilterPolicy=/access/http/request/headers/content-type fieldFilterPolicy=/access/http/request/cookies/%AM_COOKIE_NAME% fieldFilterPolicy=/access/http/request/headers/accept-encoding fieldFilterPolicy=/access/http/request/headers/authorization fieldFilterPolicy=/access/http/request/headers/content-length fieldFilterPolicy=/access/http/request/headers/%AM_COOKIE_NAME% Schema attribute defaults were returned.

Global

You can set global properties using the following ssoadm command:

$ ./ssoadm set-attr-defs -s AuditService -t global -u [adminID] -f [passwordfile] -a [attributes]

replacing [adminID], [passwordfile] and [attributes] with appropriate values.

Realm level

You can set realm level properties using the following ssoadm command:

$ ./ssoadm set-realm-svc-attrs -s AuditService -e [realmname] -u [adminID] -f [passwordfile] -a [attributes]

replacing [realmname], [adminID], [passwordfile] and [attributes] with appropriate values.

Configuring audit event handlers

The following audit event handlers are available depending on your version of AM:

Audit event handler type AM 7.x AM 6.x AM 5.x
JSON Yes Yes Yes
CSV Yes Yes Yes
Syslog Yes Yes Yes
JDBC Yes Yes Yes
Elasticsearch -- Yes Yes
JMS Yes Yes Yes
Splunk Yes* Yes Yes

* The Elasticsearch and Splunk audit event handlers are deprecated in AM 7.1.

You can configure audit event handlers at a global level or realm level (secondary configurations) as required. The following commands show the realm parameter included; if you want to configure them at the global level instead, just exclude the realm parameter. The properties you can set are described in Reference › Audit Logging with the corresponding ssoadm attribute name. Alternatively, you can return all the current settings for an existing audit event handler using the ssoadm get-sub-cfg command. For example, to return the settings for the global JSON handler with no realm parameter:

  • AM 7 and later: $ ./ssoadm get-sub-cfg -s AuditService -u uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org -f pwd.txt -g "Global JSON Handler"
  • Pre-AM 7: $ ./ssoadm get-sub-cfg -s AuditService -u amadmin -f pwd.txt -g "Global JSON Handler"

Example response:

rotationInterval=-1 rotationTimes= bufferingMaxSize=100000 topics=access topics=activity topics=config topics=authentication rotationEnabled=true retentionMinFreeSpaceRequired=-1 enabled=true handlerFactory=org.forgerock.openam.audit.events.handlers.JsonAuditEventHandlerFactory retentionMaxNumberOfHistoryFiles=1 retentionMaxDiskSpaceToUse=-1 rotationFileSuffix=-yyyy.MM.dd-HH.mm.ss bufferingWriteInterval=5 rotationMaxFileSize=100000000 location=%BASE_DIR%/%SERVER_URI%/log/ rotationFilePrefix= elasticsearchCompatible=false rotationRetentionCheckInterval=5 Sub Configuration, Global JSON Handler was retrieved.

See the following sections for details on maintaining audit event handlers:

Adding a new audit event handler

You can add an audit event handler using the following ssoadm command:

$ ./ssoadm create-sub-cfg -s AuditService -e [realmname] -u [adminID] -f [passwordfile] -g [eventHandlerType] -b [eventHandlerName] -a [attributes]

replacing [realmname], [adminID], [passwordfile], [eventHandlerType], [eventHandlerName] and [attributes] with appropriate values, where [eventHandlerType] should equal one of the types in the above table.

Modifying an existing audit event handler

You can modify an existing audit event handler using the following ssoadm command:

$ ./ssoadm set-sub-cfg -s AuditService -e [realmname] -u [adminID] -f [passwordfile] -g [eventHandlerName] -o set -a [attributes]

replacing [realmname], [adminID], [passwordfile], [eventHandlerName] and [attributes] with appropriate values. 

Example

To configure the file to rotate once a day (86400 seconds) for an existing audit event handler (called Daily JSON File in this example), you would use a ssoadm command such as:

  • AM 7 and later: $ ./ssoadm set-sub-cfg -s AuditService -e / -u uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org -f pwd.txt -g "Daily JSON File" -o set -a rotationEnabled=true rotationInterval=86400 rotationFileSuffix=-yy.MM.dd-HH.mm
  • Pre-AM 7: $ ./ssoadm set-sub-cfg -s AuditService -e / -u amadmin -f pwd.txt -g "Daily JSON File" -o set -a rotationEnabled=true rotationInterval=86400 rotationFileSuffix=-yy.MM.dd-HH.mm

Deleting an audit event handler

You can delete an audit event handler using the following ssoadm command:

$ ./ssoadm delete-sub-cfg -s AuditService -e [realmname] -u [adminID] -f [passwordfile] -g [eventHandlerName]

replacing [realmname], [adminID], [passwordfile] and [eventHandlerName] with appropriate values. 

See Also

Error when flushing the writer message when AM (All versions) is under high load with audit logging enabled

How do I improve the performance of ssoadm in AM (All versions)?

FAQ: Installing and using ssoadm in AM

Using ssoadm in AM

Security Guide › Configuring Audit Event Handlers

Related Training

N/A

Related Issue Tracker IDs

N/A


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