Upgrade Smart ID Identity Manager from 23.10.19 to 5.1.0

This article describes how to upgrade Smart ID Identity Manager from 23.10.19 to 5.1.0.

New BPMN engine

With Smart ID Identity Manager 5.0.1, the BPMN engine powering the processes in Identity Manager will be Flowable as opposed to Activiti in older versions. The migration of the database will take place on the first startup of Identity Manager Admin or Identity Manager Operator. These applications must have the rights to change the database for the first startup after the migration.  

Uploaded configurations will be migrated automatically on the first startup. To make sure that all processes will run in Flowable V6 mode (and not activiti compatibility mode), export the configuration file after the upgrade and import again. It is not supported to upload configurations from other versions.

To convert configuration files, do the following:

1. Upload the configuration files to the version they have been exported from.

2. Upgrade the system.

3. Export the configuration files again. 

4. Upload the configuration files again.

Different behavior of multi-instance tasks in Flowable vs. Activiti

In a multi-instance task, a sub-process is executed multiple times. Even when it is a parallel multi-instance task, both Flowable and Activiti will run the sub-processes sequentially. There is a slight difference in how they do this:

• Activiti will execute the tasks within a sub-process one after the other, until it reaches a wait state.

• Flowable, on the other hand, will execute the same task for each instance before moving on to the next task.

This may lead to different behavior in processes if the sub-processes were not truly independent. 

Using custom service tasks implemented by class name

Due to the switch of the BPMN engine from Activiti to Flowable you have to make a small adjustment if you want to continue using custom service tasks implemented by class name. 

The JavaDelegate interface from the package org.activiti.engine.delegate was used with Activiti. In its place your beans now have to implement BpmnJavaDelegate from the package de.nexus.processexecution.bpmn.runtime.

How to migrate:

1. Change the interface from JavaDelegate to BpmnJavaDelegate. The import statement for the java package must also be adapted.

2. Search for the method execute(DelegateExecution execution) and change its signature to execute(DelegateExecution execution, MappedTask mappedTask) . You can ignore the parameter mappedTask, which is optional.

Sign and Encrypt engine bootstrap verification

Various checks of the Sign and Encrypt engine's configuration have been introduced with Identity Manager 5.0.0. Depending on the severity, failed checks will lead to log messages or even prevent the system from starting. If that happens, a new bootstrapping is necessary.

See Sign and Encrypt engine bootstrap verification for more information and Bootstrapping production systems for instructions. Dummy certificates are not delivered with Identity Manager. See Bootstrapping development and test systems for more information on how to set up development and test systems. 

Support for encodings of USB Tokens via Card SDK is discontinued

Existing configurations which use the Card SDK for USB tokens will suffer from the Java bug described in Identity Manager release note 5.0.1 (see CRED-13706) and are no longer officially supported. 

PKI encoding of USB tokens can be handled by Smart ID Desktop App instead, which is not using Java and thus not affected by the issue. 

These are the migration steps: 

• General preparation: make sure that the Smart ID Messaging server is deployed and configured in Identity Manager. 

• For card production tasks: set the production component on the Card object to Personal Desktop App/Smart ID Desktop App. 

• For card operation tasks: change Devices=8710 to Devices=8711 in the encoding description header. 

This setting makes the encoding description incompatible with Card SDK, you cannot use it on a Card object with the production component set to Card SDK. You might need to use two separate encoding descriptions with different headers. 

Support for OsVersionField and PackageInformationField in encoding descriptions discontinued 

Support for OsVersionField and PackageInformationField has been removed from encoding descriptions. This feature was specific to CardOS smartcards and APDU commands can be used to get the same result. 

Below is an example how how to adjust the encoding from the old mechanism.

Old mechanism:

old_encoding.dsc (extract) 
[Fields] 
CARDOS_VERSION= 
PACKAGE_INFO= 
[Description] 
PKCS11LibraryWindows32=cardos11.dll 
PKCS11LibraryWindows64=cardos11_64.dll 
PackageInformationField=PACKAGE_INFO 
OsVersionField=CARDOS_VERSION  

New mechanism:

new_encoding.dsc (extract) 
[Fields] 
APDU_RESPONSE_CODES_A= 
CARDOS_VERSION= 
PACKAGE_INFO= 
[Description] 
PKCS11LibraryWindows32=cardos11.dll 
PKCS11LibraryWindows64=cardos11_64.dll 
ApplicationList=A 
[Application_A] 
ApduFile=read_version_and_package_info.apdu 
ApduResponseCodesField=APDU_RESPONSE_CODES_A 

read_version_and_package_info.apdu 
RAW[CARDOS_VERSION]:00CA018202  # read CardOS version into field CARDOS_VERSION 
RAW[PACKAGE_INFO]:00CA0188FF # read package info into field PACKAGE_INFO  

Both the DSC and APDU files must be part of the same encoding.

Java 21 for war-file deployments

War-file deployments require Java 21 for IDM 5.1.0 and later versions. 

Changes to date formats 

The Unicode Common Locale Data Repository (CLDR) version 42 introduced several updates to date, time, and unit formatting to enhance consistency and readability across different locales. 

Regular spaces in these formats are now replaced with non-breaking or narrow non-breaking spaces to prevent unwanted line breaks, ensuring elements like dates and units stay together. Additionally, some date-time formats no longer include "at" between the date and time or time ranges, aligning with cultural norms in certain locales. 

 Read more here: Quality Outreach Heads-up - JDK 20-23: Support for Unicode CLDR Version 42 – Inside.java 

The impact of this change to several key areas of IDM was investigated and mitigated, where necessary: 

• UI date selectors 

• search filters 

• PDF export 

• CSV export 

• email containing dates 

Make sure to check if your customizations need adjustments as well. 

New default timeout for Java HttpClient 

 The Java HttpClient has updated its default idle connection timeout from 20 minutes (1200 seconds) to 30 seconds. This adjustment means that idle HTTP connections will now be closed after 30 seconds of inactivity, enhancing resource management and responsiveness. 

The new 30-second default timeout improves resource management and responsiveness for dynamic, high-turnover workloads but can introduce additional connection overhead for applications that depend on long-lived idle connections 

 The idle timeout can be customized using the following system properties: 

• jdk.httpclient.keepalive.timeout: Sets the idle timeout for both HTTP/1.1 and HTTP/2 connections. 

• jdk.httpclient.keepalive.timeout.h2: Specifically sets the idle timeout for HTTP/2 connections; if not set, the value of jdk.httpclient.keepalive.timeout is used. 

New URLs for applications 

Accessing the applications is done with a new URL: /idm-<app>/jsp.login.risc?<parameters> where <app> can be admin, operator or tenant. The old URLs are still valid for convenience and backward compatibility. 

New settings for certificate-based login 

For the certificate login we need the two new settings standardLoginPort and standardLoginScheme. The default values are  "8443" and "https". Make sure to adjust them to the settings of the corresponding connector in the  server.xml  of your Tomcat. 

 The new settings apply to Identity Manager Admin, Operator and Tenant. 

# Change this to the ports where your Client Certificate Authentication is configured on (in your Tomcat server.xml).
login.certificateLoginPort=8444 
login.standardLoginPort=8443 
login.standardLoginScheme=https 

See the following articles for more details:

• List of Identity Manager system properties

• Initial configuration of Identity Manager (WAR file)

• Initial configuration of Smart ID Identity Manager (docker)

New proxy setting when application is running inside a cluster 

 There is a new proxy setting, idmDeploymentWithoutProxy.

The new setting applies to Identity Manager Admin, Operator and Tenant.

• False: the application is running inside a trusted proxy, that is, inside a cluster. In this case any forwarded headers of an http request are ignored. The responsibility to only allow valid IPs is moved to the proxy. Use this option for the docker images. 

• True: the application is running without a proxy and handles forwarded headers in its own filter chain. Use this option when application is deployed as WAR file, for example in a development or test environment. 

#Application is running with a proxy, that is, in a cluster. Default is false. 
idmDeploymentWithoutProxy=true 

See List of Identity Manager system properties for more information.

Pre-login processes 

The configuration of the pre-login processes has changed. Make sure to adapt them in the custom-beans.xml as follows: 

<bean name="preLoginProcessManager" class="de.vps.act.frontend.login.prelogin.PreLoginProcessManager" parent="abstractPreLoginProcessManager" scope="prototype"> 

   <property name="temporaryUser" value="loginProcessUser"/> <!-- enter your user here --> 

   <property name="password" value="loginProcessUser"/> <!-- enter your password here --> 

   <property name="preLoginProcesses" ref="preLoginProcesses"/> 

</bean> 

<util:list id="preLoginProcesses" value-type="java.lang.String"> 

   <value>adhoc_ResetPassword</value> 

   <value>adhoc_ResetPasswordAndLogin</value> 

</util:list> 

The pre-login processes can be removed from the dashboard processes, since they no longer need to be configured in the dashboard processes. For more information, see:

• Configure dashboard processes in Smart ID Self-Service

• Configure pre-login processes for Smart ID Self-Service

Scheduler library change 

The libraryused for scheduled jobs is now dbScheduler. With the database update, all scheduled jobs set as disabled to allow checking all cron definitions as these may differ. The new scheduler library is using Spring 5.3 Cron expression ( https://spring.io/blog/2020/11/10/new-in-spring-5-3-improved-cron-expressions ).  

IDM scheduler jobs were defined in bean files with trigger definitions previously. Now you need to define them from UI. Also, there is a new possibility for using schedule with seconds.

Step-by-step instruction: 

1. In the system.properties file, change quartzScheduler.enable to idmScheduler.enable

2. Check all cron definitions and adjust according to Spring 5.3 Cron expression

3. Re-enable all scheduled jobs that you want enabled

See the following links for more details:
Set up scheduled jobs in Identity Manager
Install Identity Manager
Sign and encrypt engine descriptors
List of Identity Manager system properties

Using execution listeners referenced by class name

With the switch to the flowable BPMN engine some notable changes were made to execution listeners.

Renamed SetProcessMessageExecutionListener

The class de.vps.act.process.task.activiti.executionlistener.SetProcessMessageExecutionListener was moved to de.nexus.flowable.runtime.listeners.SetProcessMessageExecutionListener .

IDM 5.1.0 keeps compatibility with the old listener name, and additionally it makes the listener available via the delegate expression ${setProcessMessageExecutionListener}, which is the recommended way of referencing it going forward.

Referencing SetProcessMessageExecutionListener via class name in BPMN is deprecated in IDM 5.1.0.

How to migrate:

1. For each process referencing de.vps.act.process.task.activiti.executionlistener.SetProcessMessageExecutionListener by class name:

   1. Change all class-name references in BPMN:
      Java class: de.vps.act.process.task.activiti.executionlistener.SetProcessMessageExecutionListener
      <activiti:executionListener class="de.vps.act.process.task.activiti.executionlistener.SetProcessMessageExecutionListener" event="take">
      =>
      Delegate expression: ${setProcessMessageExecutionListener}
      <activiti:executionListener delegateExpression="${setProcessMessageExecutionListener}" event="take">

   2. Save the process.

2. Update process config in IDM Operator and clear cache.

Removed LogoutProcessExecutionListener

Logout process handling changed with the switch to the Flowable BPMN engine (this refers to a specially configured process intended to be run during logout of a user, set for example via the logoutProcessManager.logoutProcessName system property).

The class de.vps.act.process.task.activiti.executionlistener.LogoutProcessExecutionListener was removed, as it can be replaced by more generic means to achieve the same functionality.

How to migrate:

1. For each logout process:

   1. For each transition referencing de.vps.act.process.task.activiti.executionlistener.LogoutProcessExecutionListener:

      1. Note down the desired value of the field named active (we will later set this value via a task).

      2. Remove the listener from the transition.

      3. Insert the service task ${setValueOfVariableInProcessMapParameterizedTask} after the transition, which is configured with the following parameters:
         variableName: Process_Logout
         variableValue: true or false (string representation of the desired boolean value that used to be set by the listener)

Config format versioning

Upload of configuration files from older IDM versions are not possible anymore. This was never supported but will now also be enforced through the config format version.

Deprecated classes

The classes de.nexus.util.Objects and de.nexus.test.util.Objects are deprecated for removal. Java has offered a suitable replacement in the form of java.util.Objects since Java 7 - please use that one instead in any custom project code.

Removal of undocumented module “cryptovision_integration” 

The cryptovision_integration module has been removed from IDM. It consisted of an undocumented task and some classes. These were no official features of IDM but just in case they have been used in custom code, here is how to replace the task and classes: 

• referenceInjectingTask. In the unlikely event that your BPMN processes include the string "${referenceInjectingTask}", "${referenceInjectingAction}" or "de.nexus.cryptovision.integration.action.referenceinjecting.ReferenceInjectingAction", you have been using this task. This task was very project specific and can be replaced with the "Process: Set Value of Variable in Process Map" task, using the following JUEL expression, where "DeputyEmail" and "ChefEmail" must be replaced with the appropriate process variables: 

  ENCR_CERT_KEY_LIST_${DeputyEmail.split("@")[0].replace(".", "_").toUpperCase()},${ChefEmail.split("@")[0].replace(".", "_").toUpperCase()} 

• certificateTransformer i.e. de.nexus.cryptovision.integration.action.transfomer.X509Base64CertificateTransformer: If you have been using this and you must keep using it, consider replacing it with a script task. 

• certificateListsMergingStrategy i.e. de.nexus.cryptovision.integration.certificate.strategy.CertificateListsMergingStrategy: If you have been using it and you must keep using it, consider replacing it with a script task. 

• de.nexus.cryptovision.integration.CryptovisionIntegrationException: If you have custom code using it, you need to find an alternative.