PingAM 7.5.0

Implement audit logging

When you implement the audit logging service, decide whether you require specific audit systems per realm, or if a global configuration suits your deployment. Next, determine which event handlers suit your needs from those supported by AM. Refer to the following sections for more information:

Configure audit logging

AM’s default audit event handler is the JSON audit event handler, which comes configured and enabled for the global audit logging service. The global configuration is used to control audit logging in realms that do not have the audit logging service added to them. AM also supports configuring an audit logging service on a per-realm basis.

The JSON audit event handler stores its JSON log files under /path/to/openam/var/audit/.

Global audit logging

  1. In the AM admin UI, go to Configure > Global Services > Audit Logging.

  2. Configure the following options on the Global Attributes tab:

    • Activate Audit logging to start the audit logging feature.

    • In the Field whitelist filters and Field blacklist filters lists, enter any values to include (allowlist) or exclude (denylist) from the audit event logs.

      AM has a predefined allowlist that only records values that do not contain sensitive information. Use the filters to override the built-in list, or to hide additional values that you do not want recorded.

      The audit logging service lets you suppress the output of certain event types, because logging them can impact performance. These event types are not logged by default, regardless of the configuration of the filter lists.

      The filter lists will only apply to these event topics if logging is enabled for them.

      For more information, see org.forgerock.openam.audit.identity.activity.events.blacklist in Advanced properties.

      For information about the fields that appear in the default allowlist, refer to Audit log default allowlist.

      To specify an additional field or value to be allowlisted, or denylisted, add a value using a JSON pointer-like syntax that starts with the event topic (access, activity, authentication, or config), followed by the field name, or the path to the value in the field.

      The lists allow two types of filtering:

      • Filter fields in events.

        Fine-grained event filtering lets you capture or hide specific information such as HTTP headers, query parameters, or potentially sensitive data.

        For example, if you are logging identity changes (AM-IDENTITY-CHANGE has been removed from the org.forgerock.openam.audit.identity.activity.events.blacklist property) you could filter out the surnames of user identities by hiding the sn field from activity events.

        To hide surname values before and after an identity change, you would add the following JSON pointers to the Field blacklist filters property:

        /activity/before/sn
/activity/after/sn

        To hide the original surname (before a change), you would add only `/activity/before/sn ` to the Field blacklist filters property.

      • Filter specific values in fields that store key-value pairs as JSON, such as the HTTP headers, query parameters, and cookies.

        For example, to include the Accept-Language value in the http.request.headers field in access events, add the following pointer to the Field whitelist filters list:

        /access/http/request/headers/accept-language

    • Click Save Changes.

      For information on configuring audit logging properties, refer to Audit logging.

  3. On the Secondary Configurations tab, you can edit the configuration of the Global JSON Handler and create new audit event handlers.

    For more information, refer to Configure audit event handlers.

Realm-specific audit logging

You can configure the audit logging service for realms, allowing you to configure realm-specific log locations and handler types.

When the audit logging service is added to a realm, it inherits the configuration defined under Configure > Global Services > Audit Logging > Realm Defaults. Properties configured explicitly in the realm-level service override the realm defaults.

To configure the audit logging service in a realm, perform the following steps:

  1. Go to Realms > Realm Name > Services.

  2. Click Add a Service.

  3. From the Choose a service type drop-down list, choose Audit Logging.

  4. Click Create.

    On the Audit Logging Service page, configure the Audit Logging Service as follows:

    1. Ensure audit logging is Enabled.

      In the Field whitelist filters and Field blacklist filters lists, enter any values to include (allowlist) or exclude (denylist) from the audit event logs.

      AM has a predefined allowlist that only records values that do not contain sensitive information. Use the filters to override the built-in list, or to hide additional values that you do not want recorded.

      The audit logging service lets you suppress the output of certain event types, because logging them can impact performance. These event types are not logged by default, regardless of the configuration of the filter lists.

      The filter lists will only apply to these event topics if logging is enabled for them.

      For more information, see org.forgerock.openam.audit.identity.activity.events.blacklist in Advanced properties.

      For information about the fields that appear in the default allowlist, refer to Audit log default allowlist.

      To specify an additional field or value to be allowlisted, or denylisted, add a value using a JSON pointer-like syntax that starts with the event topic (access, activity, authentication, or config), followed by the field name, or the path to the value in the field.

      The lists allow two types of filtering:

      • Filter fields in events.

        Fine-grained event filtering lets you capture or hide specific information such as HTTP headers, query parameters, or potentially sensitive data.

        For example, if you are logging identity changes (AM-IDENTITY-CHANGE has been removed from the org.forgerock.openam.audit.identity.activity.events.blacklist property) you could filter out the surnames of user identities by hiding the sn field from activity events.

        To hide surname values before and after an identity change, you would add the following JSON pointers to the Field blacklist filters property:

        /activity/before/sn
/activity/after/sn

        To hide the original surname (before a change), you would add only `/activity/before/sn ` to the Field blacklist filters property.

      • Filter specific values in fields that store key-value pairs as JSON, such as the HTTP headers, query parameters, and cookies.

        For example, to include the Accept-Language value in the http.request.headers field in access events, add the following pointer to the Field whitelist filters list:

        /access/http/request/headers/accept-language

    2. Click Save.

      For information on configuring audit logging properties, refer to Audit logging.

  5. On the Secondary Configurations tab, choose Add a Secondary Configuration.

    Choose an event handler from the list.

    For more information about supported event handlers and how to configure then, refer to Configure audit event handlers.

Configure audit event handlers

AM supports the following types of audit event handlers:

Audit Event Handlers
Audit Event Handler Type Publishes to How to Configure

JSON

JSON files

JSON audit event handler

CSV

CSV files

CSV audit event handler

Syslog

The syslog daemon

Syslog audit event handler

JDBC

A relational database

JDBC Audit Event Handler

JMS

JMS topics

JMS Audit Event Handler

JSON audit event handler

  1. In the AM admin UI, determine whether to create the event handler in a realm or use the default global event handler, then take one of the following actions:

    • To create the event handler in the global configuration, go to Configure > Global Services > Audit Logging.

      Note that the JSON audit event handler is already configured in the global configuration. Click it to change its properties.

    • To create the event handler in a realm, go to Realms > Realm Name > Services > Audit Logging.

  2. On the Secondary Configurations tab, click Global JSON Handler or the Edit icon on the right if present. If no handler is present, click Add a Secondary Configuration, and choose JSON.

  3. On the New JSON configuration page, enter a name for the event handler. For example, JSON Audit Event Handler.

  4. (Optional) In the Rotation Times field, enter a time duration after midnight to trigger file rotation, in seconds. For example, you can provide a value of 3600 to trigger rotation at 1:00 AM. Negative durations are not supported.

  5. Click Create.

    After the JSON audit event handler is created, several configuration tabs appear. To configure the event handler, perform the following steps:

  6. On the General Handler Configuration tab, enable the event handler and configure the topics for your audit logs:

    • Choose Enabled to activate the event handler, if disabled.

    • Choose the audit log topics for your audit logs.

    • Click Save Changes.

  7. On the JSON Configuration tab, configure JSON options:

    • Override the default location of your logs if necessary, and save your changes. The default value is as follows:

      • Unix/Linux

      • Windows

      %BASE_DIR%/var/audit

      BASE_DIR is the local PingAM configuration directory; for example /path/to/openam.

      %BASE_DIR%\var\audit

      BASE_DIR is the local PingAM configuration directory; for example \path\to\openam.

      You must configure a different log directory for each JSON audit event handler instance. If two instances are writing to the same file, it can interfere with log rotation.

    • Enable ElasticSearch JSON Format Compatible to direct AM to generate JSON formats that are compatible with the ElasticSearch format.

    • In the File Rotation Retention Check Interval field, edit the time interval (seconds) to check the time-base file rotation policies.

    • Click Save Changes.

  8. On the File Rotation tab, configure how files are rotated when they reach a specified file size or time interval:

    • Enable Rotation Enabled to activate file rotation. If file rotation is disabled, AM ignores log rotation and appends to the same file.

    • In the Maximum File Size field, enter the maximum size of an audit file before rotation.

    • (Optional). In the File Rotation Prefix field, enter an arbitrary string that will be prefixed to every audit log to identify it. This parameter is used when time-based or size-based rotation is enabled.

    • In the File Rotation Suffix field, enter a timestamp suffix based on the Java SimpleDateFormat that will be added to every audit log. This parameter is used when time-based or size-based log rotation is enabled. The default value is -yyyy.MM.dd-kk.mm.ss.

    • In the Rotation Interval field, enter a time interval to trigger audit log file rotation in seconds. A negative or zero value disables this feature.

    • (Optional) In the Rotation Times field, enter a time duration after midnight to trigger file rotation, in seconds. For example, you can provide a value of 3600 to trigger rotation at 1:00 AM. Negative durations are not supported.

    • Click Save Changes.

  9. On the File Retention tab, configure how long log files should be retained in your system:

    • In the Maximum Number of Historical Files field, enter a number for allowed backup audit files. A value of -1 indicates an unlimited number of files and disables the pruning of old history files.

    • In the Maximum Disk Space field, enter the maximum amount of disk space that the audit files can use. A negative or zero value indicates that this policy is disabled.

    • In the Minimum Free Space Required field, enter the minimum amount of disk space required to store audit files. A negative or zero value indicates that this policy is disabled.

    • Click Save Changes.

  10. On the Buffering tab, configure whether log events should be buffered in memory before they are written to the JSON file:

    • In the Batch Size field, enter the maximum number of audit log events that can be buffered.

    • In the Write interval field, enter the time interval in milliseconds at which buffered events are written to a file.

    • Click Save Changes.

CSV audit event handler

Due to the security concerns of opening CSV files with Excel, OpenOffice, and other spreadsheet programs, it is recommended that you open CSV files with alternative software, such as a text editor.

  1. In the AM admin UI, determine whether to create the event handler in a realm or use the default global event handler, then take one of the following actions:

    • To create the event handler in the global configuration, go to Configure > Global Services > Audit Logging.

      Note that the CSV audit event handler is already configured in the global configuration. Click its name to change its properties.

    • To create the event handler in a realm, go to Realms > Realm Name > Services > Audit Logging.

  2. On the Secondary Configurations tab, click Add a Secondary Configuration. Choose CVS from the list.

    On the New CVS page, enter the basic configuration for the new handler by performing the following actions:

  3. Enter a name for the event handler. For example, CSV Audit Event Handler.

  4. (Optional) In the Rotation Times field, enter a time duration after midnight to trigger file rotation, in seconds. For example, you can provide a value of 3600 to trigger rotation at 1:00 AM. Negative durations are not supported.

  5. Enable or disable the Buffering option.

  6. Click Create.

    After the CSV audit event handler is created, several configuration tabs appear. To configure the event handler, perform the following steps:

  7. On the General Handler Configuration tab, enable the event handler and configure the topics for your audit logs:

    • Click Enabled to activate the event handler, if disabled.

    • Choose the audit log topics for your audit logs.

    • Click Save.

  8. On the CSV Configuration tab, override the default location of your logs if necessary, and click Save Changes. The default value is as follows:

    • Unix/Linux

    • Windows

    %BASE_DIR%/var/audit, where BASE_DIR is the local PingAM configuration directory; for example /path/to/openam.

    %BASE_DIR%\var\audit, where BASE_DIR is the local PingAM configuration directory; for example /path/to/openam.

    Configure a different log directory for each CVS audit event handler instance. If two instances are writing to the same file, it can interfere with log rotation and tamper-evident logs.

  9. On the File Rotation tab, configure how files are rotated when they reach a specified file size or time interval:

    • Click Rotation Enabled to activate file rotation. If file rotation is disabled, AM ignores log rotation and appends to the same file.

    • In the Maximum File Size field, enter the maximum size of an audit file before rotation.

    • (Optional). In the File Rotation Prefix field, enter an arbitrary string that will be prefixed to every audit log to identify it. This parameter is used when time-based or size-based rotation is enabled.

    • In the File Rotation Suffix field, enter a timestamp suffix based on the Java SimpleDateFormat that will be added to every audit log. This parameter is used when time-based or size-based log rotation is enabled. The default value is -yyyy.MM.dd-kk.mm.ss.

    • In the Rotation Interval field, enter a time interval to trigger audit log file rotation in seconds. A negative or zero value disables this feature.

    • (Optional) In the Rotation Times field, enter a time duration after midnight to trigger file rotation, in seconds. For example, you can provide a value of 3600 to trigger rotation at 1:00 AM. Negative durations are not supported.

    • Click Save Changes.

  10. On the File Retention tab, configure how long log files should be retained in your system:

    • In the Maximum Number of Historical Files field, enter a number for allowed backup audit files. A value of -1 indicates an unlimited number of files and disables the pruning of old history files.

    • In the Maximum Disk Space field, enter the maximum amount of disk space that the audit files can use. A negative or zero value indicates that this policy is disabled.

    • In the Minimum Free Space Required field, enter the minimum amount of disk space required to store audit files. A negative or zero value indicates that this policy is disabled.

    • Click Save Changes.

  11. On the Buffering tab, configure whether log events should be buffered in memory before they are written to the CSV file:

    • Click Buffering Enabled to activate buffering.

      When buffering is enabled, all audit events are put into an in-memory buffer (one per handled topic), so that the original thread that generated the event can fulfill the requested operation, rather than wait for I/O to complete. A dedicated thread (one per handled topic) constantly pulls events from the buffer in batches and writes them to the CSV file. If the buffer becomes empty, the dedicated thread goes to sleep until a new item gets added. The default buffer size is 5000 bytes.

    • Enable the Flush Each Event Immediately option to write all buffered events before flushing.

      When the dedicated thread accesses the buffer, it copies the contents to an array to reduce contention, and then iterates through the array to write to the CSV file. The bytes written to the file can be buffered again in Java classes and the underlying operating system.

      When the Flush Each Event Immediately option is enabled, AM flushes the bytes after each event is written. If the feature is disabled (default), the Java classes and underlying operation system determine when to flush the bytes.

    • Click Save Changes.

  12. On the Tamper Evident Configuration tab, configure whether to detect audit log tampering:

    • Click Is Enabled to activate the tamper evident feature for CSV logs.

      When tamper evident logging is enabled, AM generates an HMAC digest for each audit log event and inserts it into each audit log entry. The digest detects any addition or modification to an entry.

      AM also supports another level of tamper evident security by periodically adding a signature entry to a new line in each CSV file. The entry signs the preceding block of events, so that verification can establish if any of these blocks have been added, removed, or edited by some user.

    • In the Certificate Store Location field, enter the location of the keystore AM will use to sign the CSV logs, by default %BASE_DIR%/%SERVER_URI%/Logger.jks.

      The recommended approach is to create two keystores:

      • A keystore for AM to use. This keystore is configured in the Certificate Store Location field and must contain a signing key pair called signature and an HMAC key called password.

      • A keystore for the verification tool. This keystore must contain the HMAC password key, and the public key of the signature key pair.

    You can use a simple script to create your keystores, for example: create-keystore.sh.

    • In the Certificate Store Password field, enter the password of the keystore.

    • In the Signature Interval field, enter a value in seconds for AM to generate and add a new signature to the audit log entry.

    • Click Save Changes.

    • To verify that rotated logs have not been tampered with, perform the following steps:

      • Download the AM-SSOAdminTools-5.1.3.26.zip file from the BackStage website.

      • Install the administration tools.

      • Use the verifyarchive tool to verify rotated log files as follows:

        $ /path/to/AM-SSOAdminTools-5.1.3.26/openam/bin/verifyarchive \
 --archive /path/to/openam/var/audit/ \
 --topic access \
 --suffix -yyyy.MM.dd-HH.mm.ss \
 --keystore /path/to/keystore-verifier.jks \
 --password password

        In this example, the tool checks files with a suffix of the type yyyy.MM.dd-HH.mm.ss using their counterparts with suffix .keystore. For example, the tool checks the tamper-evident-access-csv-2019.01.12-12.04.33 file against the tamper-evident-access-csv-2019.01.12-12.04.33.keystore file. The .keystore file contains the HMAC digest the tool uses to validate the signature of the logs.

        The tool returns PASS or FAIL alongside the names of the files that have been tested. For example:

        PASS    tamper-evident-access-csv-2019.01.12-12.04.33
FAIL    tamper-evident-access-csv-2019.01.12-12.05.20    The HMac at row 2 is not correct.
        Run the tool without any parameters to access the online help.

Syslog audit event handler

AM can publish audit events to a syslog server, which is based on a widely-used logging protocol. You can configure your syslog settings on the AM admin UI.

  1. In the AM admin UI, determine whether to create the event handler in a realm or use the default global event handler, then take one of the following actions:

    • To create the event handler in the global configuration, go to Configure > Global Services > Audit Logging.

    • To create the event handler in a realm, go to Realms > Realm Name > Services > Audit Logging.

  2. On the Secondary Configurations tab, click Add a Secondary Configuration. Choose Syslog from the list.

    On the New Syslog page, enter the basic configuration for the new handler by performing the following actions:

  3. Enter a name for the event handler. For example, Syslog Audit Event Handler.

  4. In the Server hostname field, enter the hostname or IP address of the receiving syslog server.

  5. In the Server port field, enter the port of the receiving syslog server.

  6. In the Connection timeout field, enter the number of seconds to connect to the syslog server. If the server has not responded in the specified time, a connection timeout occurs.

  7. Enable or disable the Buffering option.

  8. Click Create.

    After the syslog audit event handler is created, several configuration tabs appear. To configure the event handler, perform the following steps:

  9. On the General Handler Configuration tab, enable the event handler and configure the topics for your audit logs:

    • Click Enabled to activate the event handler, if disabled.

    • Choose the audit log topics for your audit logs.

    • Click Save Changes.

  10. On the Audit Event Handler Factory tab, keep the default class name for the audit event handler.

  11. On the Syslog Configuration tab, configure the main syslog event handler properties:

    • In the Server hostname field, enter the hostname or IP address of the receiving syslog server.

    • In the Server port field, enter the port of the receiving syslog server.

    • In the Connection timeout field, enter the number of seconds to connect to the syslog server. If the server has not responded in the specified time, a connection timeout occurs.

    • From the Transport Protocol drop-down list, choose TCP or UDP.

    • Choose the facility.

      A syslog message includes a PRI field that is calculated from the facility and severity values. All topics set the severity to INFORMATIONAL but you can choose the facility from the Facility drop-down list:

      Syslog Facilities
      Facility Description

      AUTH

      Security or authorization messages

      AUTHPRIV

      Security or authorization messages

      CLOCKD

      Clock daemon

      CRON

      Scheduling daemon

      DAEMON

      System daemons

      FTP

      FTP daemon

      KERN

      Kernel messages

      LOCAL0

      Local use 0 (local0)

      LOCAL1

      Local use 1 (local1)

      LOCAL2

      Local use 2 (local2)

      LOCAL3

      Local use 3 (local3)

      LOCAL4

      Local use 4 (local4)

      LOCAL5

      Local use 5 (local5)

      LOCAL6

      Local use 6 (local6)

      LOCAL7

      Local use 7 (local7)

      LOGALERT

      Log alert

      LOGAUDT

      Log audit

      LPR

      Line printer subsystem

      MAIL

      Mail system

      NEWS

      Network news subsystem

      NTP

      Network time protocol

      SYSLOG

      Internal messages generated by syslogd

      USER

      User-level messages

      UUCP

      Unix-to-unix-copy (UUCP) subsystem

    • Click Save Changes.

  12. On the Buffering tab, configure whether you want buffering or not:

    • Click Buffering Enabled to activate it.

      When buffering is enabled, all audit events that get generated are formatted as syslog messages and put into a queue. A dedicated thread constantly pulls events from the queue in batches and transmits them to the syslog server. If the queue becomes empty, the dedicated thread goes to sleep until a new item gets added. The default queue size is 5000.

    • Click Save Changes.

JDBC Audit Event Handler

You can configure AM to write audit logs to Oracle, MySQL, PostgreSQL, or other JDBC databases. AM writes audit log records to the following tables: am_auditaccess, am_auditactivity, am_auditauthentication, and am_auditconfig. For more information on the JDBC table formats for each of the logs, refer to JDBC audit log tables.

Before configuring the JDBC audit event handler, you must perform several steps to allow AM to log to the database:

Prepare for JDBC audit logging

  1. Create tables in the relational database in which you will write the audit logs. The SQL for Oracle, PostgreSQL, and MySQL table creation is in the audit.sql file under /path/to/tomcat/webapps/openam/WEB-INF/template/sql/db-type.

    If you are using a different relational database, tailor one of the provided audit.sql files to conform to your database’s SQL syntax.

  2. JDBC audit logging requires a database user with read and write privileges for the audit tables. Do one of the following:

    • Identify an existing database user and grant that user privileges for the audit tables.

    • Create a new database user with read and write privileges for the audit tables.

  3. Obtain the JDBC driver from your database vendor. Place the JDBC driver .zip or .jar file in the container’s WEB-INF/lib classpath.

    For example, place the JDBC driver in /path/to/tomcat/webapps/openam/WEB-INF/lib if you use Apache Tomcat.

The following procedure describes how to configure a JDBC audit event handler. Perform the following steps after you have created audit log tables in your database and installed the JDBC driver in the AM web container:

Configure a JDBC audit event handler

  1. In the AM admin UI, determine whether to create the event handler in a realm or use the default global event handler, then take one of the following actions:

    • To create the event handler in the global configuration, go to Configure > Global Services > Audit Logging.

    • To create the event handler in a realm, go to Realms > Realm Name > Services > Audit Logging.

  2. On the Secondary Configurations tab, click Add a Secondary Configuration. Choose JDBC from the list.

    Enter the basic configuration for the new handler by performing the following actions:.

  3. Enter a name for the event handler. For example, JDBC Audit Event Handler.

  4. In the JDBC Database URL field, enter the URL for your database server. For example, jdbc:oracle:thin:@//host.example.com:1521/ORCL.

  5. In the JDBC Driver field, enter the classname of the driver to connect to the database. For example:

    1. oracle.jdbc.driver.OracleDriver - for Oracle databases

    2. com.mysql.jdbc.Driver - for MySQL databases

    3. org.postgresql.Driver - for PostgreSQL databases

  6. In the Database Username field, enter the username to authenticate to the database server.

    This user must have read and write privileges for the audit tables.

  7. In the Database Password field, enter the password used to authenticate to the database server.

  8. Enable or disable the Buffering option.

  9. Click Create.

    After the JDBC audit event handler is created, several configuration tabs appear. To configure the event handler, perform the following steps:

  10. On the General Handler Configuration tab, enable the handler and configure the topics for your audit logs:

    • Click Enabled to activate the event handler, if disabled.

    • Choose the audit log topics for your audit logs.

    • Click Save.

  11. On the Audit Event Handler Factory tab, enter the fully-qualified class name of your custom JDBC audit event handler and save your changes.

  12. On the Database Configuration tab, configure the main JDBC event handler properties:

    • From the Database Type drop-down list, choose the audit database type. The default value is Oracle.

    • In the JDBC Database URL field, enter the URL for your database server. For example, jdbc:oracle:thin:@//host.example.com:1521/ORCL.

    • In the JDBC Driver field, enter the classname of the driver to connect to the database. For example:

      1. oracle.jdbc.driver.OracleDriver - for Oracle databases

      2. com.mysql.jdbc.Driver - for MySQL databases

      3. org.postgresql.Driver - for PostgreSQL databases

    • In the Database Username field, enter the username to authenticate to the database server.

      This user must have read and write privileges for the audit tables.

    • In the Database Password field, enter the password used to authenticate to the database server.

    • In the Connection Timeout field, enter the maximum wait time before failing the connection.

    • In the Maximum Connection Idle Timeout field, enter the maximum idle time in seconds before the connection is closed.

    • In the Maximum Connection Time field, enter the maximum time in seconds for a connection to stay open.

    • In the Minimum Idle Connections field, enter the minimum number of idle connections allowed in the connection pool.

    • In the Maximum Connections field, enter the maximum number of connections in the connection pools.

    • Click Save.

  13. On the Buffering tab, configure the buffering settings:

    • Click Buffering Enabled to start audit event buffering.

    • In the Buffer Size field, set the size of the event buffer queue where events should queue up before being written to the database.

      If the queue reaches full capacity, the process will block until a write occurs.

    • In the Write Interval field, set the interval in seconds in which buffered events are written to the database.

    • In the Writer Threads field, set the number of threads used to write the buffered events.

    • In the Max Batched Events field, set the maximum number of batched statements the database can support per connection.

    • Click Save Changes.

JMS Audit Event Handler

AM supports audit logging to a JMS message broker. JMS is a Java API for sending messages between clients using a publish and subscribe model as follows:

  • AM audit logging to JMS requires that the JMS message broker supports using JNDI to locate a JMS connection factory. Refer to your JMS message broker documentation to verify that you can make connections to your broker by using JNDI before attempting to implement an AM JMS audit handler.

  • AM acts as a JMS publisher client, publishing JMS messages containing audit events to a JMS topic.

    AM and JMS use the term topic differently. An AM audit topic is a category of audit log event that has an associated one-to-one mapping to a schema type. A JMS topic is a distribution mechanism for publishing messages delivered to multiple subscribers.

  • A JMS subscriber client, which is not part of the AM software and must be developed and deployed separately from AM, subscribes to the JMS topic to which AM publishes audit events. The client then receives the audit events over JMS and processes them as desired.

Before configuring the JMS audit event handler, you must perform several steps to allow AM to publish audit events as a JMS client:

Prepare for JMS audit logging

  1. Obtain JNDI connection properties that AM requires to connect to your JMS message broker. The specific connection properties vary depending on the broker. Refer to your JMS message broker documentation for details.

    For example, connecting to an Apache ActiveMQ message broker requires the following properties:

    Example Apache ActiveMQ JNDI Connection Properties
    Property Name Example Value

    java.naming.factory.initial

    org.apache.activemq.jndi.ActiveMQInitialContextFactory

    java.naming.provider.url

    tcp://localhost:61616

    topic.audit

    audit

  2. Obtain the JNDI lookup name of the JMS connection factory for your JMS message broker.

    For example, for Apache ActiveMQ, the JNDI lookup name is ConnectionFactory.

  3. Obtain the JMS client .jar file from your JMS message broker vendor. Add the .jar file to AM’s classpath by placing it in the WEB-INF/lib directory.

    For example, place the JMS client .jar file in /path/to/tomcat/webapps/openam/WEB-INF/lib if you use Apache Tomcat.

The following procedure describes how to configure a JMS audit event handler.

If your JMS message broker requires an SSL connection, you might need to perform additional, broker-dependent configuration tasks. For example, you might need to import a broker certificate into the AM keystore, or provide additional JNDI context properties.

Refer to your JMS message broker documentation for specific requirements for making SSL connections to your broker, and implement them as needed in addition to the steps in the following procedure.

Perform the following steps after you have installed the JMS client .jar file in the AM web container:

Configure a JMS audit event handler

  1. In the AM admin UI, determine whether to create the event handler in a realm or use the default global event handler, then take one of the following actions:

    • To create the event handler in the global configuration, go to Configure > Global Services > Audit Logging.

    • To create the event handler in a realm, go to Realms > Realm Name > Services > Audit Logging.

  2. On the Secondary Configurations tab, click Add a Secondary Configuration. Choose JMS from the list.

  3. On the New JMS Configuration page, enter the basic configuration for the new handler by performing the following actions:

  4. Enter a name for the event handler. For example, JMS Audit Event Handler.

  5. Click Create.

    After the JMS audit event handler is created, several configuration tabs appear. To configure the event handler, perform the following steps:

  6. On the General Handler Configuration tab, enable the handler and configure the topics for your audit logs:

    • Click Enabled to activate the event handler, if disabled.

    • Choose the audit log topics for your audit logs.

    • Click Save Changes.

  7. On the Audit Event Handler Factory tab, keep the default class name for the audit event handler.

  8. On the JMS Configuration tab, configure the main JMS event handler properties:

    • From the Delivery Mode drop-down list, choose the JMS delivery mode.

      With persistent delivery, the JMS provider ensures that messages are not lost in transit in case of a provider failure by logging messages to storage when they are sent. Therefore, persistent delivery mode guarantees JMS message delivery, while non-persistent mode provides better performance.

      The default delivery mode is NON_PERSISTENT delivery. Therefore, if your deployment requires delivery of every audit event to JMS subscriber clients, be sure to set the configuration to PERSISTENT delivery.

    • From the Session Mode drop-down list, choose the default setting, AUTO, unless your JMS broker implementation requires otherwise. Refer to your broker documentation for more information.

    • Specify properties that AM will use to connect to your JMS message broker as key-value pairs in the JNDI Context Properties field.

      AM is configured for the audit JNDI lookup name and JMS topic, but you can modify or delete this configuration, or add new key-value pairs. To add new key-value pairs, fill the Key and Value fields and click Add.

    • In the JMS Topic Name field, enter the name of the JMS topic to which AM will publish messages containing audit events.

      Subscriber clients that process AM audit events must subscribe to this topic.

    • In the JMS Connection Factory Name field, specify the JNDI lookup name of the JMS connection factory.

    • Click Save Changes.

  9. On the Batch Events tab, configure how log events should be batched before they are published to the JMS message broker:

    • In the Capacity field, specify the maximum capacity of the publishing queue. Execution is blocked if the queue size reaches capacity.

    • In the Max Batched field, specify the maximum number of events to be delivered when AM publishes the events to the JMS message broker.

    • In the Writing Interval field, specify the interval (in seconds) between transmissions to JMS.

    • Click Save Changes.

Trust transaction headers

AM supports the propagation of the transaction ID across the ForgeRock platform, such as from DS or IDM to AM, using the HTTP header X-ForgeRock-TransactionId. The X-ForgeRock-TransactionId header is automatically set in all outgoing HTTP calls from one ForgeRock product to another. You can also set this header from your own applications or scripts calling into the ForgeRock platform.

By default, the org.forgerock.http.TrustTransactionHeader system property is set to false, so that a malicious actor cannot flood the system with requests using the same transaction ID header to hide their tracks. Setting org.forgerock.http.TrustTransactionHeader to true trusts any incoming X-ForgeRock-TransactionId headers.

  1. In the AM admin UI, go to Configure > Server Defaults > Advanced and scroll to the bottom of the list.

  2. In the PROPERTY NAME column, add org.forgerock.http.TrustTransactionHeader. In the corresponding PROPERTY VALUE column, enter true.

  3. Click + to add the property and save your work.

    Your AM instance will now accept incoming X-ForgeRock-TransactionId headers, which can be tracked in the audit logs.

  4. Repeat this procedure for all servers that require this property.