Upgrade from CzechIdM 10.x/11.x to CzechIdM 12

In CzechIdM 12.x, the CAS authentication implementation was moved from a standalone module directly to the application. As a result, you need to make several changes in the configuration when upgrading from CzechIdM 11.x (or older) to version 12.x

This tutorial does not cover potential changes which need to be done in the CzechIdM application itself. During update, you should always refer to the CzechIdM changelog as well!
Find the iam-app-czechidm package version
[root@localhost ~]# dnf info iam-app-czechidm
Installed Packages
Name         : iam-app-czechidm
Version      : 0.5
Release      : 0.el8
Architecture : noarch
Size         : 354 k
Source       : iam-app-czechidm-0.5-0.el8.src.rpm
Repository   : @System
From repo    : iam-centos8
Summary      : IAM appliance CzechIdM application container support
License      : MIT
Description  : Support and files for running CzechIdM application container.
... abbreviated ...

Installed package version is 0.5. To use CzechIdM 12.x, you need package version 0.6 or higher.

Find the CzechIdM version
[root@localhost ~]# less /data/registry/node-active-config/docker-compose-czechidm.yml
version: '3.2'

services:
  czechidm:
    image: repo.iamappliance.com:8443/bcv-czechidm:11.2.1-r0
    container_name: czechidm
... abbreviated ...

At the end of the line which starts with image:, we will find the installed version of CzechIdM. In the example above, the installed version is 11.2.1.

Update to iam-app-czechidm 0.6

Before performing the update, we have to stop the CzechIdM service and create a database backup (this can take tens of minutes, depending on the database size). Once the backup is done, we can update the iam-app-czechidm package:

[root@localhost ~]# systemctl stop iam-czechidm
[root@localhost ~]# systemctl start iam-czechidm-db-backup.service
[root@localhost ~]# dnf update iam-app-czechidm

Edit the CzechIdM configuration

After the package is updated, new configuration file created in /data/registry/node-active-config/docker-compose-czechidm.yml.rpmnew. The original configuration file remains as is in the /data/registry/node-active-config/docker-compose-czechidm.yml file. It is usually easier to edit the original configuration file than configure the application from scratch.

If you have some experience using the terminal, you can use vimdiff to merge configuration changes quickly and comfortably.

From the new file, you only need to copy the used version of the image:

[root@localhost ~]# less /data/registry/node-active-config/docker-compose-czechidm.yml.rpmnew
version: '3.2'

services:
  czechidm:
    image: repo.iamappliance.com:8443/bcv-czechidm:12.0.1-r0
    container_name: czechidm
... abbreviated ...

We will copy the item starting with image:. In this example repo.iamappliance.com:8443/bcv-czechidm:12.0.1-r0. After that, we will edit the file /data/registry/node-active-config/docker-compose-czechidm.yml as follows:

  1. The line image: repo.iamappliance.com:8443/bcv-czechidm:11.2.1-r0 (or equivalent for IdM 10.x; there is only one line like this in the file).

    • Replace it with the value we have copied, e. g., image: repo.iamappliance.com:8443/bcv-czechidm:12.0.1-r0.

  2. The line - CZECHIDM_CAS_URL=https://iam.appliance.tld/cas/.

    • Remove the forward slash at the end of the line. The result should look like this: - CZECHIDM_CAS_URL=https://iam.appliance.tld/cas

  3. The line - CZECHIDM_CAS_IDM_URL=https://iam.appliance.tld/idm/.

    • Remove the forward slash at the end of the line. The result should look like this: - CZECHIDM_CAS_IDM_URL=https://iam.appliance.tld/idm

  4. Remove the line - CZECHIDM_CAS_LOGIN_SUFFIX=login?service=.

  5. Remove the line - CZECHIDM_CAS_LOGOUT_SUFFIX=logout?service=.

  6. Remove the line - CZECHIDM_CAS_HEADER_PREFIX=https://iam.appliance.tld/idm/?ticket=.

Save the file. Remove the configuration file with the suffix .rpmnew created during the package update.

[root@localhost ~]# rm /data/registry/node-active-config/docker-compose-czechidm.yml.rpmnew

Edit the CzechIdM service definition in CAS

Edit the file which registers the CzechIdM service into the CAS. Edit the file /data/volumes-shared/cas-services/idm-200.json and remove the line containing redirectUrl and the comma on its preceding line. The original file:

{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "https://iam.appliance.tld/idm.+",
  "name" : "CzechIdM",
  "id" : 200,
  "evaluationOrder" : 1,
  "redirectUrl": "https://iam.appliance.tld/idm/#/login"
}

should now look like:

{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "https://iam.appliance.tld/idm.+",
  "name" : "CzechIdM",
  "id" : 200,
  "evaluationOrder" : 1
}

Start the CzechIdM service

Start the CzechIdM service.

[root@localhost ~]# systemctl start iam-czechidm

Known issues

After the upgrade from CzechIdM 11.x (and older) to version 12.x, the user interface may "freeze" during the first attempt at accessing the application webpage. The issue is related to changes in the CAS access manager authentication implementation which required some changes in the application frontend.

  1. To mitigate this, the affected user must access a specific URL where the CzechIdM application will log out the user and reset all locally cached objects in the user’s browser.

  2. Once the browser cached objects are reset, the issue will disappear.