Versions Compared

Version Old Version 2 New Version 3
Changes made by

Ylva Andersson

Ylva Andersson

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Info

This article is valid for Smart ID 20.06.1 and later.

...

Expand
titlePrerequisites

This is a summary of what must be in place before the migration starts.

  • A Windows host.
  • The same Java version as for the corresponding Identity Manager release is installed and its java.exe in your PATH. See Identity Manager requirements and interoperability.
  • Java has the Unlimited Strength Jurisdiction Policy Files installed.
  • The new keypair has been generated.
  • For every tenant on the system have access to:
    • tenant ID
    • administrative username + password

...

Expand
titleSet up database connection
  1. Extract the zip archive containing the Secret Fields Key Updater.
  2. Go to the extracted Secret Fields Key Updater directory.
  3. Edit the file database.properties as appropriate. For more information on this file, see Install Identity Manager.
The
Code Block
titleIdentity Manager database
dataSourceType=H2
dataSource.jdbcUrl=jdbc:sqlserver://<HOST_NAME>:<DB_PORT>;instance=<INSTANCE_NAME>;databaseName=<DB_NAME>;AUTO_SERVER=TRUE
dataSource.user=<USER_NAME>
dataSource.password=<USER_PASSWORD>
Note


Note: The database user must have read/write access to the Identity Manager database.



Expand
titleData Encryption key set up
  1. Open the file config/encryption-config.xml.
  2. Update the EncryptedFields and NewEncryptedFields field descriptors and their referenced keys as described below. For more information on this file, see 24.R1: Sign and encrypt engine in Identity Manager.
    1. EncryptedFields is the old, to be replaced, descriptor. Adapt its values to match the ones that are currently set up in Identity Manager.
      In this example, EncryptedFields references oldEncCert as its key. Change the referenced key to match the one that is currently referenced in Identity Manager.
    2. NewEncryptedFields is the new descriptor, holding the information of the replacement key. Change its values accordingly.
      In this example, NewEncryptedFields references newEncCert as its key. Change the referenced key to match the key that will replace the old one in Identity Manager.
Code Block
languagexml
titleExample : encryption-config.xml
collapsetrue
<?xml version="1.0" encoding="UTF-8"?>
<engineSignEncrypt>
  <descriptors>
    <descriptor name="EncryptedFields" version="1">
      <type algorithm="AES/CBC/PKCS7Padding" size="256" result="NX02" key="oldEncCert" asymCipher="RSA/None/OAEPWithSHA384AndMGF1Padding"/>
    </descriptor>
    <descriptor name="NewEncryptedFields" version="1">
      <type algorithm="AES/CBC/PKCS7Padding" size="256" result="NX02" key="newEncCert" asymCipher="RSA/None/OAEPWithSHA384AndMGF1Padding"/>
    </descriptor>
  </descriptors>
  <keys>
    <key name="oldEncCert">
      <type name="pkcs12" locationValue="classpath:oldEncKeypair.p12" pin="1234567"/>
    </key>
    <key name="newEncCert">
      <type name="pkcs12" locationValue="classpath:newEncKeypair.p12" pin="1234"/>
    </key>
  </keys>
</engineSignEncrypt>


...

Expand
titleShutdown and backup

Before you start the migration:

  1. Stop the Identity Manager applications (shut down Tomcat or the respective docker containers by running docker compose down from within docker/compose/identitymanager/<webappname>/).
  2. Create a backup of the respective databases.

Migration per tenant

title
Warning

The secret field store in the database is tenant-aware, even though the descriptors and keys are not.
Therefore migration has to be executed separatelyfor every single tenant before changing keys and descriptors in Identity Manager.

Expand


Configure migration for a tenant

  1. Edit migrate_general.properties and set the following values:
AttributeValueDescription
username
Name of the administrator of the respective tenant. This user will be used to perform the update.
password
The administrator's password.
tenantId
The Tenant ID.



If

Note: If the application is interrupted or fails, it can not continue at a later time. Instead, the database needs to be restored to the state it had before running the Secret Fields Key Updater. Use the database dump created earlier. The process can then be restarted at a later point, but it will process all entries again, starting at the very beginning.

Expand
titleExecute migration for a tenant
  1. Double-check that all preparation steps were executed, especially a database update of the state before migrating the first tenant.
  2. Start the Secret Fields Key Updater by executing the batch file start_migration.bat on Windows.
Note


Expand
titleLog file

During the migration, log files are created in the filelogs/idm_migration.log.

If necessary, edit log4j.xml to customize the path of the log messages. 

...

Expand
titleSet up Identity Manager to use the new keypair
  1. For docker:
    Open docker/compose/identitymanager/config/signencrypt.xml for editing.
    or:
    For WAR file deployment: 
    Open WEB-INF/classes/engineSignEncrypt.xml in Identity Manager Operator, Identity Manager Admin and Identity Manager Tenant for editing.
  2. Change the attributes of the EncryptedFields descriptor and its referenced key to the values needed for the new keypair, as you set them for the NewEncryptedFields descriptor in the migration application. Note that the descriptor's name must still be EncryptedFields and not NewEncryptedFields for Identity Manager.
  3. For docker:
    Run docker compose up from within  docker/compose/identitymanager/<webappname>/ for all Identity Manager applications (Admin, Operator and Tenant) to recreate the docker containers.
    or:
    For WAR file deployment:
    Start Identity Manager.