Implementing the Audit Logging Service

When implementing 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. See the following sections for more information:

AM also supports the classic Logging Service, based on Java SDK, that will be deprecated in a future release. For more information, see "Implementing the Classic Logging Service".

Configuring 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/.

To Configure Global Audit Logging

  1. Log in to the AM console as an administrator, for example amAdmin.

  2. Navigate to Configure > Global Services > Audit Logging.

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

    1. Activate Audit logging to start the audit logging feature.

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

      AM has a predefined whitelist built in 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.

      Important

      The Audit Logging Service lets you suppress the output of certain event types, because logging them may have an impact on 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 whitelist, see "Audit Log Default Whitelist".

      To specify an additional field or value to be whitelisted, or blacklisted, 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. You may be interested in capturing, or hiding, HTTP headers, query parameters, or potentially sensitive data like passwords in the access logs.

        For example, you might want to filter out surnames by hiding the sn field from activity events. To do so, add the following pointers to the Field blacklist filters list: 

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

      • 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

    3. Save your changes.

      For more information on configuring audit logging properties, see "Audit Logging".

  4. On the Secondary Configurations tab, you can edit the configuration of the Global JSON Handler, or you can create new audit event handlers. For more information, see "Configuring Audit Event Handlers".

To Configure Audit Logging in a Realm

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. Navigate to Realms > Realm Name > Services.

  2. Select Add a Service.

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

  4. Select Create.

    The Audit Logging Service page appears. Configure the Audit Logging Service as follows:

  5. Ensure audit logging is Enabled.

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

    AM has a predefined whitelist built in 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.

    Important

    The Audit Logging Service lets you suppress the output of certain event types, because logging them may have an impact on 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 whitelist, see "Audit Log Default Whitelist".

    To specify an additional field or value to be whitelisted, or blacklisted, 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. You may be interested in capturing, or hiding, HTTP headers, query parameters, or potentially sensitive data like passwords in the access logs.

      For example, you might want to filter out surnames by hiding the sn field from activity events. To do so, add the following pointers to the Field blacklist filters list: 

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

    • 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

  7. Save your changes.

    For more information on configuring audit logging properties, see "Audit Logging".

  8. On the Secondary Configurations tab, select Add a Secondary Configuration. Choose an event handler from the list.

    For more information about supported event handlers and how to configure then, see "Configuring Audit Event Handlers".

Configuring Audit Event Handlers

AM supports the following types of audit event handlers:

Audit Event Handlers
Audit Event Handler TypePublishes toHow to Configure
JSONJSON files"Configuring JSON Audit Event Handlers"
CSVCSV files"Configuring CSV Audit Event Handlers"
SyslogThe syslog daemon"Configuring Syslog Audit Event Handlers"
JDBCA relational database"Implementing JDBC Audit Event Handlers"
JMSJMS topics"Implementing JMS Audit Event Handlers"
SplunkA Splunk server"Implementing Splunk Audit Event Handlers"

This section provides procedures for configuring each type of audit handler.

Configuring JSON Audit Event Handlers

The following procedure describes how to configure a JSON audit event handler:

To Configure a JSON Audit Event Handler

  1. Log in to the AM console as an administrator, for example amAdmin.

  2. 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, navigate to to Configure > Global Services > Audit Logging.

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

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

  3. 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 select JSON.

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

  5. (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.

  6. Click Create.

    After the JSON 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:

    1. Select Enabled to activate the event handler, if disabled.

    2. Choose the topics for your audit logs. For a description of each topic, see "Audit Log Topics".

    3. Click Save Changes.

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

    1. Override the default location of your logs if necessary, and save your changes. The default value is %BASE_DIR%/%SERVER_URI%/log/.

      Important

      Make sure to 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 and tamper-evident logs.

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

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

    4. Click Save Changes.

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

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

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

    3. (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.

    4. 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 .

    5. 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.

    6. (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.

    7. Click Save Changes.

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

    1. 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.

    2. 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.

    3. 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.

    4. Click Save Changes.

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

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

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

    3. Click Save Changes.

Configuring CSV Audit Event Handlers

The following procedure describes how to configure a comma-separated values (CSV) audit event handler:

To Configure a CSV Audit Event Handler

Important

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 a a text editor.

  1. Log in to the AM console as an administrator, for example amAdmin.

  2. 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, navigate to to Configure > Global Services > Audit Logging.

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

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

  3. On the Secondary Configurations tab, select Add a Secondary Configuration. Choose CVS from the list.

    The New CVS page appears. Enter the basic configuration for the new handler by performing the following actions:

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

  5. (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.

  6. Enable or disable the Buffering option.

  7. Select Create.

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

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

    1. Select Enabled to activate the event handler, if disabled.

    2. Choose the topics for your audit logs. For a description of each topic, see "Audit Log Topics".

    3. Save your changes.

  9. On the CSV Configuration tab, override the default location of your logs if necessary, and save your changes. The default value is %BASE_DIR%/%SERVER_URI%/log/.

    Important

    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.

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

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

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

    3. (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.

    4. 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 .

    5. 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.

    6. (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.

    7. Save your changes.

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

    1. 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.

    2. 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.

    3. 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.

    4. Save your changes.

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

    1. Select 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.

    2. Enable Flush Each Event Immediately 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 Flush Each Event Immediately 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.

    3. Save your changes.

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

    1. Select 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.

    2. 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.

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

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

    5. Save your changes.

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

      1. Download the AM-SSOAdminTools-5.1.3.11.zip file from the ForgeRock BackStage website.

      2. Install the tools by performing the steps in "To Set Up Administration Tools".

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

        $ /path/to/AM-SSOAdminTools-5.1.3.11/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.

        Tip

        Run the tool without any parameters to see the online help.

Configuring Syslog Audit Event Handlers

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 console.

The following procedure describes how to configure a Syslog audit event handler:

To Configure a Syslog Audit Event Handler

  1. Log in to the AM console as an administrator, for example amAdmin.

  2. 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, navigate to to Configure > Global Services > Audit Logging.

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

  3. On the Secondary Configurations tab, select Add a Secondary Configuration. Choose Syslog from the list.

    The New Syslog page appears. Enter the basic configuration for the new handler by performing the following actions:

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

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

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

  7. 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.

  8. Enable or disable the Buffering option.

  9. Select Create.

    After the syslog 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 event handler and configure the topics for your audit logs:

    1. Select Enabled to activate the event handler, if disabled.

    2. Choose the topics for your audit logs. For a description of each topic, see "Audit Log Topics".

    3. Save your changes.

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

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

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

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

    3. 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.

    4. From the Transport Protocol drop-down list, select TCP or UDP.

    5. 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
      FacilityDescription
      AUTHSecurity or authorization messages
      AUTHPRIVSecurity or authorization messages
      CLOCKDClock daemon
      CRONScheduling daemon
      DAEMONSystem daemons
      FTPFTP daemon
      KERNKernel messages
      LOCAL0Local use 0 (local0)
      LOCAL1Local use 1 (local1)
      LOCAL2Local use 2 (local2)
      LOCAL3Local use 3 (local3)
      LOCAL4Local use 4 (local4)
      LOCAL5Local use 5 (local5)
      LOCAL6Local use 6 (local6)
      LOCAL7Local use 7 (local7)
      LOGALERTLog alert
      LOGAUDTLog audit
      LPRLine printer subsystem
      MAILMail system
      NEWSNetwork news subsystem
      NTPNetwork time protocol
      SYSLOGInternal messages generated by syslogd
      USERUser-level messages
      UUCPUnix-to-unix-copy (UUCP) subsystem

    6. Save your changes.

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

    1. Select 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.

    2. Save your changes.

Implementing JDBC Audit Event Handlers

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, see "JDBC Audit Log Tables".

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

To 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:

To Configure a JDBC Audit Event Handler

  1. Log in to the AM console as an administrator, for example amAdmin.

  2. 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, navigate to to Configure > Global Services > Audit Logging.

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

  3. On the Secondary Configurations tab, select Add a Secondary Configuration. Choose JDBC from the list.

    The New JDBC page appears. Enter the basic configuration for the new handler by performing the following actions:.

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

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

  6. 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

  7. 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.

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

  9. Enable or disable the Buffering option.

  10. Select the Create button.

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

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

    1. Select Enabled to activate the event handler, if disabled.

    2. Select the topics for your audit logs. For a description of each topic, see "Audit Log Topics".

    3. Save your changes.

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

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

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

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

    3. 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

    4. 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.

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

    6. In the Connection Timeout (seconds) field, enter the maximum wait time before failing the connection.

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

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

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

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

    11. Save your changes.

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

    1. Select Buffering Enabled to start audit event buffering.

    2. In the Buffer Size (number of events) 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.

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

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

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

    6. Save your changes.

Implementing JMS Audit Event Handlers

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. See 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. [3]

  • 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:

To 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. See 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 NameExample 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.

See your JMS message broker's 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:

To Configure a JMS Audit Event Handler

  1. Log in to the AM console as an administrator, for example amAdmin.

  2. 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, navigate to to Configure > Global Services > Audit Logging.

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

  3. On the Secondary Configurations tab, select Add a Secondary Configuration. Choose JMS from the list.

    The New JMS configuration page appears. 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. Select 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:

    1. Select Enabled to activate the event handler, if disabled.

    2. Select the topics for your audit logs. For a description of each topic, see "Audit Log Topics".

    3. Save your 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:

    1. From the Delivery Mode drop-down list, specify 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.

    2. From the Session Mode drop-down list, leave the default setting, AUTO, unless your JMS broker implementation requires otherwise. See your broker documentation for more information.

    3. 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 the Add button.

    4. In the JMS Topic Name field, specify 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.

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

    6. Save your changes.

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

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

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

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

    4. Save your changes.


[3] Note that 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.

Implementing Splunk Audit Event Handlers

AM supports sending audit logging data to a Splunk HTTP event collector REST endpoint. This endpoint requires an authentication token created in Splunk and configured in the AM event handler.

Before configuring the Splunk audit event handler in AM, configure the endpoint in Splunk:

To Prepare Splunk

Perform the following steps in Splunk:

  1. Create a source type to match AM audit logs. Consider the following configuration tips:

    • It must be a structured type.

    • It must not have indexed extractions.

    • It must have event breaks on every line.

    • Timestamp extraction must be automatic.

  2. Create an HTTP event collector token that uses the source type you just created.

  3. Obtain the HTTP event collector token value for the token you just created. For example, AD565CB5-BB8A-40FD-8A7C-94F549CEDECF.

    This token, which allows AM to log data to Splunk, is required for the AM audit event handler configuration.

  4. Obtain the HTTP event collector port. For example, 8088.

  5. Ensure that the HTTP event collector and its tokens are enabled.

The following procedure describes how to configure a Splunk audit event handler in AM. Perform the following steps after you have created a Splunk HTTP event collector token:

To Configure a Splunk Audit Event Handler

  1. Log in to the AM console as an administrator, for example amAdmin.

  2. 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, navigate to to Configure > Global Services > Audit Logging.

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

  3. On the Secondary Configurations tab, select Add a Secondary Configuration. Choose Splunk from the list.

    The New Splunk configuration page appears. Enter the basic configuration for the new handler by performing the following actions:

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

  5. In the Server Hostname field, enter the hostname or IP address of the Splunk HTTP event collector to which AM should connect when writing audit events.

  6. In the Server Port field, enter the port number to access the Splunk HTTP event collector.

  7. In the Authorization Token field, enter the authorization token for the Splunk HTTP event collector REST endpoint.

  8. Select Create.

    After the Splunk 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 handler and configure the topics for your audit logs:

    1. Select Enabled to activate the event handler, if disabled.

    2. Select the topics for your audit logs. For a description of each topic, see "Audit Log Topics".

    3. Save your changes.

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

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

    1. In the Server Hostname field, enter the hostname or IP address of the Splunk server to which AM should connect when writing audit events.

    2. In the Server Port field, enter the port number to access the Splunk HTTP event collector REST endpoint.

    3. If SSL is enabled and configured between AM and the Splunk server, select SSL Enabled.

    4. In the Authorization Token field, enter the authorization token for the Splunk HTTP event collector REST endpoint.

    5. Save your changes.

  12. On the Buffering tab, configure options about how log events should be buffered in memory before they are written to the Splunk data store:

    1. In the Batch Size field, specify the number of audit events that AM pulls from the audit buffer when writing a batch of events to Splunk.

      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 Splunk. If the buffer becomes empty, the dedicated thread goes to sleep until a new item gets added.

    2. In the Queue Capacity field, specify the maximum number of audit events that AM can queue in this audit handler's buffer.

      If the number of events to queue exceeds the queue capacity, AM raises an exception and the excess audit events are dropped, and therefore not written to Splunk.

    3. In the Write interval (in milliseconds) field, specify how often AM should write buffered events to Splunk.

    4. Save your changes.


[3] Note that 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.

Configuring the Trust Transaction Header System Property

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. Customers can also set this header themselves from their own applications or scripts calling into the ForgeRock platform.

You can set a new property org.forgerock.http.TrustTransactionHeader to true, which will trust any incoming X-ForgeRock-TransactionId headers. By default, the org.forgerock.http.TrustTransactionHeader 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.

To Configure the Trust Transactions Header System Property

  1. Log in to the AM console.

  2. Navigate to Configure > Server Defaults > Advanced.

  3. In the Add a Name field, enter org.forgerock.http.TrustTransactionHeader, and enter true in the corresponding Add a Value field.

  4. Save your changes.

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

  5. Repeat this procedure for all servers requiring this property.


[3] Note that 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.

Read a different version of :