Upgrade from CAS 6.2.x to CAS 6.5.x

This guide describes the generational upgrade of the CAS access manager which is a part of the IAM appliance. The update process contains several specifics.

This guide does not describe changes which may be needed in the registration of applications connected to CAS. If you use the access manager for integrations that are not an integral part of the IAM appliance, we strongly recommend that you perform the upgrade in the test environment first.
Find the iam-app-cas package version
[root@localhost ~]# dnf info iam-app-cas
Installed Packages
Name         : iam-app-cas
Version      : 0.3
Release      : 0.el8
Architecture : noarch
Size         : 37 k
Source       : iam-app-cas-0.3-0.el8.src.rpm
Repository   : @System
From repo    : bcv-iam-development
Summary      : IAM appliance CAS support
License      : MIT
Description  : Support and files for running CAS.
... abbreviated ...

The package is installed in version 0.3. To use CAS 6.5.x, a package version 0.4 or higher is needed.

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

services:
  cas:
    image: repo.iamappliance.com:8443/bcv-cas:6.2.8.4-r1
    container_name: cas
... abbreviated ...

At the end of the line which starts with image:, we find the installed version of CAS. In the example above, the installed version is 6.2.8.4 (CAS version 6.2.8 with the BCV overlay .4).

Update to iam-app-cas 0.4

Before the update, we need to stop the CAS service. No data backup is necessary. After that, we can update the iam-app-cas package. During the update of iam-app-cas, the iam-app-web-proxy might be updated as well.

[root@localhost ~]# systemctl stop iam-cas
[root@localhost ~]# dnf update iam-app-cas

Edit the CAS configuration

After the package is updated, new configuration file appears in /data/registry/node-active-config/docker-compose-cas.yml.rpmnew. The original configuration file remains as-is in the /data/registry/node-active-config/docker-compose-cas.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 image version:

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

services:
  cas:
    image: repo.iamappliance.com:8443/bcv-cas:6.5.2.0-r0
    container_name: cas
... abbreviated ...

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

  1. The line image: repo.iamappliance.com:8443/bcv-cas:6.2.8.4-r1 (or equivalent, 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-cas:6.5.2.0-r0.

  2. Add a line with the environment property CAS_SERVER_SCOPE.

    • This property defines the web domain for which the access manager is an authentication authority. For example, if the access manager runs with the domain name am.company.com, fill in - CAS_SERVER_SCOPE=company.com.

  3. Remove the line - CAS_LDAP_0_USE_SSL.

  4. Add the line - CAS_LDAP_0_PRINCIPAL_ATTR_LIST=…​ with the same content as is defined in the .rpmnew file.

  5. Change the line - CAS_CUSTOM_FRONTEND=true to CAS_CUSTOM_FRONTEND=iamappliance.

  6. Add the missing mounted volumes from the .rpmnew file.

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-cas.yml.rpmnew

IF YOU ARE USING AN EXTERNAL CAS CONFIGURATION, you need to make further changes and move the custom configuration to different location.

The external configuration is a custom change of the IAM appliance and is not done by default.

Main points to consider:

  • You no longer need to use the externally mounted server.xml for Tomcat (for RemoteIpValve configuration).

  • You no longer need to use the external cas.properties file.

    • All configuration options of the internal LDAP of the IAM Appliance are generated from the compose file.

    • Additional configuration can be be placed in files in the /data/volumes/cas/cas.properties.d/ directory. Files therein are automatically appended to the end of the cas.properties file during the application start. The file name must end with .properties.

    • If you explicitely define encryption and signing keys you need to move them to the /data/volumes/cas/cas.properties.d/000_keys.properties file.

  • SpringBoot framework was upgraded between CAS 6.2 and 6.5. As a result, the property name format changed from the camel-case (cas.etcEtc.someConfigProperty) to the kabob-case (cas.etc-etc.some-config-property).

  • Some configuration properties were changed or removed. Observe the application log during its start as the application notifies about invalid configuration and suggests necessary changes.

Edit the web proxy configuration

Together with access manager update, the web proxy configuration in the file /data/volumes/web-proxy/config/reverse_proxy.conf will be updated as well. If you use the default IAM Appliance installation, the update will likely be performed automatically without any need for manual changes.

However, if a conflict during the update installation occurs, the installation program will create a file /data/volumes/web-proxy/config/reverse_proxy.conf.rpmnew. Solve the configuration conflict in the same way as any other.

Start the services

Restart the web proxy service and then start the CAS access manager service. Both updated services use new container images. Therefore, a short outage will occur because the system needs to download them.

[root@localhost ~]# systemctl restart iam-web-proxy
[root@localhost ~]# systemctl start iam-cas