This procedure assumes the AM bootstrap keystore and the AM keystore are not the same. You should not create key aliases for AM features in the bootstrap keystore. For more information, see "To Reconfigure the Bootstrap Keystore".

Perform the following steps to create key aliases in a new keystore, for example, when creating the new AM keystore:

1. Change directories to the keystore location, for example /path/to/openam/openam.

2. Create two files, each containing only the password in cleartext. For example:

   • .am_keystore_storepass contains the cleartext keystore password.

     $ echo -n newstorepassword > .am_keystore_storepass

   • .am_keystore_keypass contains the cleartext password for the key aliases that reside in the keystore.

     $ echo -n newkeypassword > .am_keystore_keypass

   Important

   Use echo -n to avoid inserting hidden trailing newline characters. Even if the keytool command is able to use the password in the file, AM may not be able to open the keystore or the key aliases.

3. Make sure the password files have read-only permission for their owner. For example:

   $ chmod 400 .am_keystore_storepass
   $ chmod 400 .am_keystore_keypass

4. Acquire a new key from your certificate authority and add it to a new keystore, or generate a new self-signed key in a new keystore.

   This example creates a self-signed key alias in a new keystore file, am_keystore.jceks, with a new asymmetric RSA key alias, newkey. For an example of how to create ECDSA keys, see "Configuring Elliptic Curve Digital Signature Algorithms" in the Authentication and Single Sign-On Guide.

   $ cd /path/to/openam/openam
   $ keytool \
   -genkeypair \
   -alias newkey \
   -keyalg RSA \
   -keysize 2048 \
   -validity 730 \
   -storetype JCEKS \
   -keystore am_keystore.jceks
   Enter keystore password: Enter the password in the .am_keystore_storepass file.
   Reenter new password: Enter the password in the .am_keystore_storepass file.
   What is your first and last name?
   [Unknown]:  openam.example.com
   What is the name of your organizational unit?
   [Unknown]:  Eng
   What is the name of your organization?
   [Unknown]:  ForgeRock.com
   What is the name of your City or Locality?
   [Unknown]:  Grenoble
   What is the name of your State or Province?
   [Unknown]:  Isere
   What is the two-letter country code for this unit?
   [Unknown]:  FR
   Is CN=openam.example.com, OU=Eng, O=ForgeRock.com, L=Grenoble, ST=Isere,
   C=FR correct?
   [no]:  yes
   Enter key password for <newkey>
   (RETURN if same as keystore password): Enter the password in the .am_keystore_keypass file.
   Reenter new password: Enter the password in the .am_keystore_keypass file.

5. (Optional) If needed, share new self-signed key aliases as described in "To Share Self-Signed Certificates" in the Installation Guide. Note that self-signed keys are not automatically recognized by other entities.

6. Create any other keys and keystores required by your environment by repeating the steps in this procedure and/or following the steps in "To Create Key Aliases In an Existing Keystore".

7. Ensure that password files and keystores are maintained on every instance in your environment. Every AM instance has its own keystores and password files.

8. Configure the new keystore in AM:

   • To configure it as the new AM keystore, see "Configuring AM's Keystore".

   • To configure it as a keystore for any other feature, see "Features in AM That Use Key Aliases".

Perform the following steps to create new key aliases in an existing keystore, for example, the AM keystore:

1. Change directories to the keystore location, for example, /path/to/openam/openam.

2. Back up the existing keystore files, for example, /path/to/openam/openam/am_keystore.jceks, /path/to/openam/openam/.am_keystore_storepass, and /path/to/openam/openam/.am_keystore_keypass.

3. Acquire a new key from your certificate authority, or generate a new self-signed key.

   When you create or import a new key, the keytool command adds the new alias to the specified keystore if it exists, or creates a new keystore if it does not exist.

   This example creates a self-signed key alias in AM's keystore, am_keystore.jceks, with a new asymmetric RSA key alias called saml2key. For an example of how to create ECDSA key aliases, see "Configuring Elliptic Curve Digital Signature Algorithms" in the Authentication and Single Sign-On Guide.

   $ cd /path/to/openam/openam
   $ keytool \
   -genkeypair \
   -alias saml2key \
   -keyalg RSA \
   -keysize 2048 \
   -validity 730 \
   -storetype JCEKS \
   -keystore am_keystore.jceks
   Enter keystore password: Enter the password in the .am_keystore_storepass file.
   What is your first and last name?
   [Unknown]:  openam.example.com
   What is the name of your organizational unit?
   [Unknown]:  Eng
   What is the name of your organization?
   [Unknown]:  ForgeRock.com
   What is the name of your City or Locality?
   [Unknown]:  Grenoble
   What is the name of your State or Province?
   [Unknown]:  Isere
   What is the two-letter country code for this unit?
   [Unknown]:  FR
   Is CN=openam.example.com, OU=Eng, O=ForgeRock.com, L=Grenoble, ST=Isere,
   C=FR correct?
   [no]:  yes
   Enter key password for <saml2key>
   (RETURN if same as keystore password): Enter the password in the .am_keystore_keypass file.
   Reenter new password: Enter the password in the .am_keystore_keypass file.

4. (Optional) If needed, share new self-signed key aliases as described in "To Share Self-Signed Certificates" in the Installation Guide. Note that self-signed keys are not automatically recognized by other entities.

5. Ensure that password files and keystores are maintained on every instance in your environment. Every AM instance has its own keystores and password files.

6. Restart the AM instances affected by the configuration changes to use the new key aliases.

7. Configure the new key aliases in AM. For a list of features that use key aliases and links to their relevant sections, see "Features in AM That Use Key Aliases".

Use the keytool command to export the key from the source component's keystore. Install the result in AM's keystore, by performing the following steps:

1. From the source keystore, export the required key into a temporary keystore that can be transported to AM by executing the following keytool command:

   $ keytool -importkeystore -srcstoretype jceks -srcalias "myKeyAlias" \
   -deststoretype jceks -destalias "myKeyAlias" \
   -srckeystore "/path/to/openidm/security/keystore.jceks" \
   -destkeystore "/path/to/openidm/security/temp_keystore.jceks" \
   -srckeypass "changeit" \
   -srcstorepass "changeit" \
   -destkeypass "myT3mPK3yP4ssword" \
   -deststorepass "myT3mPK3yP4ssword"

   This command exports the myKeyAlias key alias, specified by the srcalias argument, to a temporary keystore file /path/to/openidm/security/temp_keystore.jceks. The store and key password is set to myT3mPK3yP4ssword. You need to use the temporary passwords when importing to the AM instance.

2. Move the temporary keystore file created in the previous step, in this example temp_keystore.jceks, to the filesystem of the target AM server.

3. On the target AM server, import the key alias into the AM keystore by executing the following keytool command:

   $ keytool -importkeystore -srcstoretype jceks -srcalias "myKeyAlias" \
   -deststoretype jceks -destalias "myKeyAlias" \
   -srckeystore "/path/to/openam/openam/temp_keystore.jceks" \
   -destkeystore "/path/to/openam/openam/am_keystore.jceks" \
   -srckeypass "myT3mPK3yP4ssword" \
   -srcstorepass "myT3mPK3yP4ssword" \
   -destkeypass:file "/path/to/openam/openam/.am_keystore_keypass" \
   -deststorepass:file "/path/to/openam/openam/.am_keystore_storepass"

   This command imports the key alias from the temporary keystore file /path/to/openam/openam/temp_keystore.jceks into the AM keystore, and sets the key password to match the password used by the default AM keystore.

4. (Optional) Repeat the previous steps to copy any additional key aliases from the source keystore to the destination keystore.

5. Restart the AM instance for the key change to take effect.

   The AM instance will now be able to correctly encrypt, decrypt, sign or verify data and share it with the source ForgeRock Identity Platform component.

This procedure assumes the AM bootstrap keystore and the AM keystore are not the same. For more information about changing the passwords of the strings contained in the bootstrap keystore, see "To Reconfigure the Bootstrap Keystore".

1. Change directories to the keystore location, for example, /path/to/openam/openam.

2. Back up the keystore files. For example, make a copy of the /path/to/openam/openam/am_keystore.jceks and /path/to/openam/openam/.am_keystore_keypass files.

3. Replace the old password in the .am_keystore_keypass file with the new one:

   $ echo -n newpassword > .am_keystore_keypass

   Important

   Use echo -n to avoid inserting hidden trailing newline characters. Even if the keytool command is able to use the password in the file, AM may not be able to use the key aliases if there are hidden trailing newline characters in the password file.

4. Make sure the .am_keystore_keypass file has read-only permissions for its owner:

   $ chmod 400 .am_keystore_keypass

5. List the keys and password strings contained in the keystore:

   $ keytool -list -storetype JCEKS -keystore am_keystore.jceks>

6. Use the keytool command to change the password of each of the key aliases, for example:

   $ keytool -keypasswd -storetype JCEKS -keystore am_keystore.jceks -alias test
   Enter keystore password: Enter the password in the .am_keystore_storepass file
   New key password for <test> Enter the password in the .am_keystore_keypass file
   Re-enter new key password for <test> Enter the password in the .am_keystore_keypass file

   Important

   Most of the key aliases in the AM keystore must have the same password. You need to change the passwords of all the key aliases in the keystore file to match the content of the .am_keystore_keypass file. For more information about features that may not use this password file, see "Features in AM That Use Key Aliases".

7. (Optional) If you also need to change the keystore password, see "To Change the Keystore Password".

8. (Optional) The name and path of the .am_keystore_keypass file is configured in the AM console for several features. If you have changed the name or the path to this file, you may need to adjust the configuration. For information about different configurations, see "Introducing Keystores".

9. Ensure that password files and keystores are maintained on every instance in your environment. Every AM instance has its own keystores and password files.

10. Restart the AM instances affected by the configuration changes.

This procedure assumes the AM bootstrap keystore and the AM keystore are not the same. If you need to change the bootstrap keystore's password, see "To Reconfigure the Bootstrap Keystore".

1. Change directories to the keystore location, for example /path/to/openam/openam.

2. Back up the keystore and keystore password files. For example, make a copy of the /path/to/openam/openam/am_keystore.jceks and /path/to/openam/openam/.am_keystore_storepass files.

3. Use the keytool command to change the password:

   $ keytool -storepasswd -storetype JCEKS -keystore am_keystore.jceks 
   Enter keystore password:Enter the password in the .am_keystore_storepass file.
   New keystore password:Enter the new password.
   Re-enter new keystore password:

4. Replace the old password in the .am_keystore_storepass file with the new one:

   $ echo -n newpassword > .am_keystore_storepass

   Important

   Use echo -n to store the keystore's password to avoid inserting hidden trailing newline characters. Even if the keytool command is able to use the password in the file, AM may not be able to open the keystore if there are hidden trailing newline characters in the password file.

5. Ensure the .am_keystore_storepass file has read-only permissions for its owner:

   $ chmod 400 .am_keystore_storepass

6. (Optional) If you also need to change the key aliases' password, see "To Change Key Alias Passwords".

7. Ensure that password files and keystores are maintained on every instance in your environment. Each AM instance has its own keystores and password files.

8. Restart the AM instance or instances affected by the configuration changes.

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.

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 Logger.jks keystore, by default %BASE_DIR%/%SERVER_URI%/Logger.jks. You must manually create the keystore and place it in this location. You can use a simple script to create your Java keystore: 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.

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

       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

       
       

    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.

1. Create tables in the relational database in which you will write the audit logs. The SQL for Oracle 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 the Oracle or MySQL audit.sql file 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.

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 Drive field, enter the classname of the driver to connect to the datbase. For example, oracle.jdbc.driver.OracleDriver or com.mysql.jdbc.Driver.

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 Drive field, enter the classname of the driver to connect to the database. For example, oracle.jdbc.driver.OracleDriver or com.mysql.jdbc.Driver.

    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 maximun number of batched statements the database can support per connection.

    6. Save your changes.

Perform the following steps to prepare an Elasticsearch instance for storing AM audit events.

1. Review the JSON file containing AM's audit schema. You can find the JSON file for the audit schema at the path /path/to/tomcat/webapps/openam/WEB-INF/template/elasticsearch/audit.json.

2. Copy the audit.json file to the system where you will create the Elasticsearch index for AM auditing.

   In this example, you create an Elasticsearch index by executing an Elasticsearch REST API call using the curl command. Copy the audit.json file to a location that is accessible to the curl command you will run in the next step.

3. Create an Elasticsearch index for AM auditing as follows:

   $ curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data @audit.json \
    http://elasticsearch.example.com:9200/my_openam_audit_index

   In this example, note the following:

   • elasticsearch.example.com is the name of the host on which Elasticsearch runs.

   • 9200 is the port number that you use to access Elasticsearch's REST API.

   • my_openam_audit_index is the name of the Elasticsearch index that you want to create.

   Tip

   For more information on connecting to Elasticsearch, see Talking to Elasticsearch in the Elasticsearch documentation.

1. If your Elasticsearch deployment uses Elasticsearch Shield configured for SSL, import the CA certificate used to sign Elasticsearch node certificates into the Java keystore on the host that runs AM. For example:

   $ keytool \
    -import \
    -trustcacerts \
    -alias elasticsearch \
    -file /path/to/cacert.pem \
    -keystore $JAVA_HOME/jre/lib/security/cacerts

   If you are running an AM site, import the CA certificate on all the servers in your site.

2. Log in to the AM console as an administrator, for example amadmin.

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

4. On the Secondary Configurations tab, select Add a Secondary Configuration. Choose Elasticsearch from the list.

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

5. Enter a name for the event handler. For example, Elasticsearch Audit Event Handler.

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

7. In the Server Port field, enter the port number to access Elasticsearch's REST API.

8. In the Elasticsearch Index field, specify the name of the index to be used for AM audit logging. The index you specify in this field must be identical to the index you created in "To Prepare for Elasticsearch Audit Logging".

9. Specify the name and password of an Elasticsearch user if you have configured Elasticsearch Shield for user authentication:

   1. In the Username field, enter the username to authenticate into the Elascticsearch server.

   2. In the Password field, enter the password of the user that authenticates into the Elasticsearch server.

   3. Save your changes.

   If you are not using Elasticsearch Shield for user authentication, you can leave these fields with their default values.

10. Enable or disable the Buffering option.

11. Select Create.

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

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

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

14. On the Elasticsearch Configuration tab, configure the main Elasticsearch event handler properties:

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

    2. In the Server Port field, enter the port number to access Elasticsearch's REST API.

    3. If SSL is enabled in your Elasticsearch deployment, select SSL Enabled.

    4. In the Elasticsearch Index field, specify the name of the index to be used for AM audit logging. The index you specify in this field must be identical to the index you created in "To Prepare for Elasticsearch Audit Logging".

    5. Save your changes.

15. On the Authentication tab, specify the name and password of an Elasticsearch user if you have configured Elasticsearch Shield for user authentication:

    1. In the Username field, enter the username to authenticate into the Elascticsearch server.

    2. In the Password field, enter the password of the user that authenticates into the Elasticsearch server.

    3. Save your changes.

    If you are not using Elasticsearch Shield for user authentication, you can leave these fields with their default values.

16. On the Buffering tab, configure whether log events should be buffered in memory before they are written to the Elasticsearch data store:

    1. Activate Buffering Enabled to start buffering audit messages.

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

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

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

    4. In the Write interval (in millis) field, specify how often AM should write buffered events to Elasticsearch.

    5. Save your changes.

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

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 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 select the +add button.

   4. In the JMS Topic 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. Activate Batch Enabled to start batch publishing of audit events. Audit events will be queued and published to the JMS message broker in batches.

      If batch publishing is not enabled, AM publishes audit events to the JMS message broker individually.

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

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

   4. In the Thread Count field, specify the number of worker threads AM should use to process the batch queue.

   5. Specify the batching timeout configuration as follows:

      • In the Insert Timeout field, specify the amount of time in seconds for queued events to be transmitted to the JMS message broker.

      • In the Polling Timeout field, specify the amount of time in seconds that worker threads wait for new audit events before becoming idle.

      • In the Shutdown Timeout field, specify the amount of time in seconds that worker threads wait for new audit events before shutting down.

   6. Save your changes.

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.

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.

1. Stop the AM instance or the container where it runs.

2. Download the AM 6.0.0.7 ZIP file from the BackStage website.

3. Extract the contents of the ZIP file.

4. Navigate to the /snmp folder, and run the jdmkrt.jar installer file. For example:

   $ java -jar jdmkrt.jar

5. Accept the License Agreement.

6. Select the install directory you want to install to. For example: /tmp/opendmk.

7. Copy the jdmkrt.jar file from the /lib folder of the extracted archive to the AM /WEB-INF/lib folder. For example:

   $ cp /tmp/opendmk/OpenDMK-bin/lib/jdmkrt.jar /path/to/openam.war/WEB-INF/lib

8. Restart the AM instance or the container in which it runs.

9. Navigate to Configure > Global Services > Monitoring.

10. Set the Monitoring Status to enabled.

11. Set the Monitoring SNMP interface status property to Enabled. By default, AM will be set to allow you to listen on port 8085 for SNMP monitoring.

12. Click Save Changes.

13. Restart the AM instance for the change to take effect.

Before enabling Prometheus access to monitoring metrics, make sure that you have enabled monitoring. To enable monitoring, navigate to Configure > Global Services > Monitoring. Set the Monitoring Status to enabled, and then click Save Changes.

1. Navigate to Configure > Global Services > Monitoring.

2. Select the Secondary Configurations tab, and click prometheus.

3. Set prometheus to Enabled.

4. Specify the Username and Password that Prometheus will use to authenticate when accessing the endpoint.

5. Click Save Changes.

Before enabling CREST access to monitoring metrics, make sure that you have enabled monitoring. To enable monitoring, navigate to Configure > Global Services > Monitoring. Set the Monitoring Status to enabled, and then click Save Changes.

1. Navigate to Configure > Global Services > Monitoring.

2. Select the Secondary Configurations tab, and click crest.

3. Set CREST to Enabled.

4. Click Save Changes.

Before enabling Graphite access to monitoring metrics, make sure that you have enabled monitoring. To enabled monitoring, navigate to Configure > Global Services > Monitoring. Set the Monitoring Status to enabled, and then click Save Changes.

1. Navigate to Configure > Global Services > Monitoring.

2. Select the Secondary Configurations tab, and click Add a Secondary Configuration.

3. Select Graphite Reporter.

4. Specify the Name and Hostname of the Graphite instance to which to push the metrics data.

5. Click Create.

Disabling caching can have a severe negative impact on performance. This is because when caching is disabled, AM must query a data store each time it needs data.

If, however, you have at least one user data store that does not support LDAP persistent search, then you must disable the global cache for user data. Otherwise user data caches cannot stay in sync with changes to user data entries:

1. In the AM console, navigate to Deployment > Servers > Server Name > Advanced.

2. Set the value of the com.iplanet.am.sdk.caching.enabled property to false to disable caching overall.

3. Set the value of thecom.sun.identity.sm.cache.enabled property to true to enable configuration data caching.

   All supported configuration data stores support LDAP persistent search, so it is safe to enable configuration data caching.

   You must explicitly set this property to true, because setting the value of the property com.iplanet.am.sdk.caching.enabled to false in the previous step disables both user and configuration data caching.

4. Save your work.

5. AM starts persistent searches on user data stores when possible ^[6] in order to monitor changes. With user data store caching disabled, AM still starts the persistent searches, even though it no longer uses the results.

   Therefore, if you disable user data store caching, you should also disable persistent searches on user data stores in your deployment to improve performance. To disable persistent search on a user data store, remove the value of the Persistent Search Base DN configuration property and leave it blank. Locate this property under Realms > Realm Name > Data Stores > Data Store Name > Persistent Search Controls.

With a large user data store and active user base, the number of user entries in cache can grow large.

1. In the AM console, navigate to Configure > Server Defaults > SDK.

2. Change the value of SDK Caching Maximum Size.

   There is no corresponding setting for configuration data, as the number of configuration entries in a large deployment is not likely to grow nearly as large as the number of user entries.