The certificates used for signing and verification need to be valid for digital signatures. Otherwise Identity Manager will fail on writing to the database.

The keys and certificates used for signing and verification are configured in the encrypt and sign engine's configuration, typically found under engineSignEncryptConfig.xml. 

1. Configure the key used for the chained signature via the property descriptorName of the bean historyServiceSigner. Add the following to system.properties:

   Add key for chained signature

   historyServiceSigner.descriptorName=<name of the descriptor>

2. If the chained signature is not configured, Tomcat startup will fail with an error message like:
   

   Error message from Tomcat

   Error accessing the sign and encrypt engine (5, No descriptor found with name: overwriteMe)

   
   

1. Verify the chained signatures with a REST service call to this url: 
   

   URL for manual verification of chained signature

   <prime-explorer>/ws/objecthistory/verify[?tenantId=<tenant for login>]

   where the tenantId is optional.

2. The login can be done via basic authentication. For example, if you log in as admin/admin the following header is added, where YWRtaW46YWRtaW4= is the "admin:admin" Base64-encoded:
   

   Authorization: Basic YWRtaW46YWRtaW4=

   
   

3. Some REST service clients support convenient entry of basic authentication with fields. If preemptive authentication is offered, you should use that, since the REST service do not ask for authentication, but rather just fail if no authentication is offered.
4. The result is either 'true' if everything is fine or 'false' if a verification failed. Details about verification errors are listed in a log file.

A scheduled job regularly checks the signature chain of the object history. If an error is found, it will send an email to configurable recipients.

As the object history signature spans over all history entries, regardless of the tenant, the verification on a multi tenant system should be done by a dedicated user that belongs to no tenant (that is, it has a null tenantId), but who performs this task for the whole system. Use the Identity Manager Tenant application to create such a user:

1. In system.properties, add the following:

   Add user for scheduled task in system.properties

   # System user for scheduled tasks. Executes tasks relevant to ALL tenants.
   # Username
   cronUsername.encrypted=admin
   # Password
   cronPassword.encrypted=admin

2. Configure the SMTP server in Identity Manager. See Set up email template in Identity Manager.

3. Several attributes can be configured in system.properties. Note that a property may span over several lines by ending intermediate lines with a backslash. At the very least, you must configure a recipient.
   This is an example of system.properties:

   system.properties

   # When to execute. Fields: Seconds Minutes Hours Day-of-Month Month Day-of-Week Year(optional)
   historyVerificationTrigger.cronExpression = 0 30 0 * * ?
   # Email address of users to be notified by scheduling jobs.
   # Next line is mandatory!
   #schedulingReporter.to =
   #schedulingReporter.cc =
   # Subject and contents of the mail to send on verification errors
   historyVerificationJobDetail.jobDataMap[subject] = Error verifying object history signature
   historyVerificationJobDetail.jobDataMap[text] = Hi there,\n\
   something has gone wrong with the object history signature.\n\
   For more details, please have a look at the server log.\n\
   \n\

4. After successful verification, the task deletes any history entries no longer needed for verification of the current verification window, see below how to configure the verification window. On failure, or if no verification window is configured, nothing is deleted.

To allow deletion of older entries, the verification of object history can be limited to a window of the most recent N months, with N being >= 12. Smaller values will be overridden by 12.

If no interval is specified, the entire history is validated (default).

1. Enter this in system.properties to specify 12 months timeframe:

   Specify timeframe in system.properties

   commonHistoryService.verificationIntervalMonths=12

Note that if a verification window is set, the following applies:

• verification will fail if the oldest entry of any chain within the verification window points to a deleted predecessor
• if verification fails for entries outside the verification window, this will be logged

The periodically running HistoryVerificationJob deletes history entries that are no longer needed for verification in the current verification window.

The following applies:

• A history entry is deleted after each successful, scheduled verification only. Manual verification through the REST service will not trigger deletion.
• If no verification window is configured, nothing is deleted.

In a clustered environment there is a separate chain per cluster node. With the default configuration, the chain's name is derived from the cluster node, that is, the jvmRoute attribute of the engine tag found in the server.xml. The implementation uses only the primary engine and does not support any special cases.

If there is a special cluster configuration, or if a cluster is not based on a unique jvmRoute per node, the attribute commonHistoryService.chainName needs to be provided. If this attribute is not found, like typically in single node environments, PRIME1 is used as default name.

Each history entry corresponds to an action that was performed on a core object in Identity Manager. Thus it belongs to a single tenant. The chained signature of the history on the other hand is global: there's exactly one chain for each cluster node, that spans over all history entries, regardless of the tenant. The signature ensures that no history entry of a Identity Manager cluster node has been manipulated.

For this reason it is recommended that the signature verification is performed by an administrator that is not bound to a tenant, that is, with an tenantId of null. The scheduled task that performs history verification should, in case of an error, be configured to send an email to a global user that administers Identity Manager for all tenants. It is still possible to verify the signatures with a user belonging to a tenant, but this should only be done on single tenant systems.