Page Comparison

• The certificates used for signing and verification need to be valid for digital signatures. Otherwise Identity Manager will fail on writing to the database.
  
  
• Upgrade to 22.04 (or later) from an earlier version:
  
  1. The parameter commonHistoryService.verificationIntervalMonths in the system properties part of the docker-compose.yml file for Identity Manager Operator was renamed to commonHistoryService.historyCutOffDuration in Smart ID 22.04. Make sure you rename it accordingly in your configuration. See also List of Identity Manager system properties.
  2. Add/update the following section and configure it as desired (explained further down in this document).
     The default CRON expression for the history cleaning task has been added to be executed on Fridays only. This is a new property added for the history cleaning task:
     

  Code Block
  # History cleaning task historyCleaningTrigger.cronExpression = 0 30 0 ? * FRI *

  Furthermore, the default CRON expression for the history verification task has changed, so it executes only on Sundays, not daily:

  Code Block
  # History verification task historyVerificationTrigger.cronExpression = 0 30 0 ? * SUN *

  See also Upgrade Smart ID Identity Manager from 21.10 to 22.04

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 in the system properties part of the docker-compose.yml file:

   Code Block
   title 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:
   

   Code Block
   title 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: 
   

   Panel
   title 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:
   

   Code Block
   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 cleans the signature chain of the object history. 

As the object history signature spans over all history entries, regardless of the tenant, the cleaning 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 the docker-compose.yml file, set the following system property: (also needed "scheduled verification" above):

   Code Block
   title System property: Add user for scheduled task
   # System user for scheduled tasks. Executes tasks relevant to ALL tenants. # Username cronUsername.encrypted=admin # Password cronPassword.encrypted=admin

   
   

2. Several attributes can be configured with system properties. Note that a property may span over several lines by ending intermediate lines with a backslash. 
   This is an example of a configuration of the system property:

   Code Block
   title Configure a system property for object history cleaning
   # When to execute. Fields: Seconds Minutes Hours Day-of-Month Month Day-of-Week Year(optional) historyCleaningTrigger.cronExpression = 0 30 0 ? * FRI *

   
   

3. Also see "Define Cut-Off For Verification / Cleanup Window" below.

To be able to delete history entries when deleting a core object, you must add theobjectHistoryRemovalStrategy.removeWhenDeletingCoreObject property to the system properties part of the docker-compose.yml file for Identity Manager Operator. This property is intentionally not provided by default.

1. Inthe system properties part of the docker-compose.yml file, add the property below and set it to true:

   Code Block
   title Add system property
   # Delete object history entries together with the entities objectHistoryRemovalStrategy.removeWhenDeletingCoreObject = true

   Now the history entries will be deleted together with the core object itself.

By default the verification windows spans the entire history. You can limit it to the last N >= 12 months. This will enable deletion of older entries outside the verification window. Smaller values will be overridden by 12.

This will enable cleanup of older entries outside the verification window to reduce the amount of stored data.

If no cut-off is specified, the entire history is validated (default), and cleanup has no effect.

1. In the system properties part of the docker-compose.yml file, enter this to specify a window starting 12 months in the past and ending at the current time:

   Code Block
   title Specify timeframe in system properties
   # new parameter name in IDM 2204 (used to be "commonHistoryService.verificationIntervalMonths") commonHistoryService.historyCutOffDuration=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