Update the IAM appliance to version 0.6

There are three new services in the IAM appliance 0.6: the LDAP directory server, the access manager, and the connector server. Because of these large changes, you will need to follow this specific upgrade guide (see below).

  • LDAP directory server

    • This component is an mandatory part of the appliance and it must always be running. Otherwise, users will not be able to authenticate to the appliance services (not even administrators).

    • This component uses port 636/tcp to expose its interface. It can be used as a data source for other infrastructure parts (e. g., RADIUS server, Linux OS, etc.)

  • Access manager

    • This component is an mandatory part of the appliance and it must always be running. Otherwise, users will not be able to authenticate to the appliance services (not even administrators).

    • The access manager is available via the HTTPS interface of the appliance, behind a /cas/ fragment.

    • The access manager can be used for centralized authentication to other applications in the infrastructure.

  • Connector server

    • An optional component; it is not installed by default

    • A standalone container for identity connectors, this service is used to deploy the WinRM+AD connector.

This version of the IAM appliance moves to using the access manager service for authentication. This means that logging-in into CzechIdM will no longer be done by CzechIdM.

As a result, you need to set new password to every user who already uses the appliance and distribute it to them.

Prerequisites

Upgrade prerequisites.

Ports

The appliance communicates with the server repo.iamappliance.com using ports 443/tcp and 8443/tcp via the Internet. This communication must be functional.

Verify that the communication is functional using the tcptraceroute too
[root@localhost ~]# tcptraceroute repo.iamappliance.com 443
traceroute to repo.iamappliance.com (87.236.196.108), 30 hops max, 60 byte packets
... abbreviated ....
 7  neon.bcvsolutions.eu (87.236.196.108) <syn,ack>  2.728 ms  3.013 ms  2.160 ms

[root@localhost ~]# tcptraceroute repo.iamappliance.com 8443
traceroute to repo.iamappliance.com (87.236.196.108), 30 hops max, 60 byte packets
... abbreviated ...
 7  neon.bcvsolutions.eu (87.236.196.108) <syn,ack>  1.995 ms  2.427 ms  2.235 ms

Connect the Docker repositories

Check that the configuration of the Docker repository repo.iamappliance.com:8443 is functional. Download any image, e. g., the busybox:latest image. You can remove the image immediately after the download.

Download a small image to check the configuration
[root@localhost ~]# docker pull repo.iamappliance.com:8443/busybox
Using default tag: latest
latest: Pulling from busybox
9ea23c65b705: Pull complete
Digest: sha256:540f2e917216c5cfdf047b246d6b5883932f13d7b77227f09e03d42021e98941
Status: Downloaded newer image for repo.iamappliance.com:8443/busybox:latest
repo.iamappliance.com:8443/busybox:latest
Remove the downloaded image
[root@localhost ~]# docker rmi repo.iamappliance.com:8443/busybox:latest
Untagged: repo.iamappliance.com:8443/busybox:latest
Untagged: repo.iamappliance.com:8443/busybox@sha256:540f2e917216c5cfdf047b246d6b5883932f13d7b77227f09e03d42021e98941
Deleted: sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749
Deleted: sha256:8ac8bfaff55af948c796026ee867448c5b5b5d9dd3549f4006d9759b25d4a893

Upgrade the software repository configuration

Verify that the RPM repository definition in your appliance is at least version 0.3. If it is not, update it using these steps.

Check the iam-appliance-repos package version
[root@localhost ~]# rpm -qi iam-appliance-repos
Name        : iam-appliance-repos
Version     : 0.1
Release     : 1.el8
Architecture: noarch
... abbreviated ...

Check the appliance hostname and the HTTPS certificate

Starting with this version, the appliance services use a central access manager to authenticate users. They communicate with it via HTTPS on the domain name on which the appliance is available to users.

  • The appliance domain name must be present in the DNS.

  • The appliance must be able to resolve its domain name to IP address in the DNS.

  • The domain name in the HTTPS certificate must correspond to the DNS name. Otherwise, trusted communication via HTTPS cannot be established.

Ping the IAM appliance DNS name (correct result)
[root@localhost ~]# ping -c1 my-appliance.bcv
PING appliance (172.31.255.123) 56(84) bytes of data.
64 bytes from appliance (172.31.255.123): icmp_seq=1 ttl=64 time=0.141 ms

--- appliance ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.141/0.141/0.141/0.000 ms
Ping the IAM appliance DNS name (incorrect result)
[root@localhost ~]# ping -c1 doesnotexist.tld
ping: doesnotexist.tld: Name or service not known
List the HTTPS certificate to verify CN and subjectAltName
[root@localhost ~]# openssl x509 -in /data/volumes/web-proxy/secrets/current_web_cert.crt -text -noout
Certificate:
    Data:
... abbreviated ...
        Subject: CN = my-appliance.bcv
... abbreviated ...
        X509v3 extensions:
            X509v3 Subject Alternative Name:
                DNS:my-appliance.bcv

Upgrade

Turn off the appliance

Turn off the appliance the usual way, e.g., using the command poweroff, or using ACPI shutdown.

Create a snapshot

Create a snapshot of the turned off virtual server.

Turn on the appliance

Turn on the appliance the usual way. After startup, check that all services are running.

Stop the services

The appliance consists of several standalone services which need to be stopped before the update.

Stop all services including containerization
[root@localhost ~]# systemctl stop czechidm
[root@localhost ~]# systemctl stop czechidm-db web-proxy
[root@localhost ~]# systemctl stop docker

Update the RPM packages

Update the RPM packages which belong to the IAM appliance.

Update the IAM appliance packages
[root@localhost ~]# dnf update iam-*

Handle the configuration conflicts like you do during standard updates. Beware that new software versions may contain new configuration items; you cannot simply leave the original configuration files in place.

Reconfigure the environment

Since the appliance contains new applications, you need to perform further configuration.

Firewall configuration

If you have encountered the warning NOTICE: Firewall rules were updated. This change requires restart of the firewall and Docker. during the installation of the update, you need the restart the appliance firewall to apply configuration changes.

The firewall restart should not (but may, especially if there is a mistake in its configuration) cause the SSH access to become unavailable. Make sure you can access the local server console (via OOB, etc.).
Status prior to the firewall restart
[root@localhost ~]# iptables -nL INPUT | grep 443
(no output)
Firewall restart
[root@localhost ~]# systemctl restart iptables
Status after the firewall restart
[root@localhost ~]# iptables -nL INPUT | grep 443
ACCEPT     tcp  --  0.0.0.0/0            0.0.0.0/0            state NEW tcp dpt:443

Access manager configuration

Edit the /data/registry/node-active-config/docker-compose-cas.yml file (using the nano or vim editor) and set the parameter CAS_SERVER_NAME. New value of the parameter consists of the protocol and the hostname on which the appliance is available to users. The value must not end with forward slash.

Setting CAS_SERVER_NAME
      - CAS_SERVER_NAME=https://my-appliance.bcv

Edit the /data/volumes-shared/cas-services/idm-200.json file and add parameter redirectUrl with value https://HOSTNAME/idm/#/login where HOSTNAME is the domain name on which the appliance is available to users.

The file is in the JSON format and it must be syntactically correct. Enclose both the keys and values in quotation marks ". Notice the comma , at the end of the line which precedes the added line.
The resulting idm-200.json file for hostname my-appliance.bcv
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "https://.+/idm.+",
  "name" : "CzechIdM",
  "id" : 200,
  "evaluationOrder" : 1,
  "redirectUrl": "https://my-appliance.bcv/idm/#/login"
}

CzechIdM configuration

Edit the file /data/registry/node-active-config/docker-compose-czechidm.yml (using the nano or vim editor) and set the following parameters. New value of the parameter consists of the protocol and hostname on which the appliance is available to users. Values need to be added, but, in general, it is only necessary to replace http with https and localhost with the DNS name of the appliance.

These settings are sensitive to typos and extra or missing characters. Please, pay attention to the syntax. The word HOSTNAME always refers to the domain name on which the appliance is available to users.

  • CZECHIDM_CAS_URL - Lets CzechIdM know the location where the access manager is running.

  • CZECHIDM_CAS_IDM_URL - The identification that CzechIdM uses when communicating with the access manager.

  • CZECHIDM_CAS_HEADER_PREFIX - The prefix of the session tickets given by the access manager.

An example of the parameters for a DNS name my-appliance.bcv
      - CZECHIDM_CAS_URL=https://my-appliance.bcv/cas/
      - CZECHIDM_CAS_IDM_URL=https://my-appliance.bcv/idm/
      - CZECHIDM_CAS_HEADER_PREFIX=https://my-appliance.bcv/idm/?ticket=

Import the IAM appliance certificate as a trusted certificate

Since the appliance components are standalone containerized services, we must ensure that they mutually trust their SSL certificates. Therefore, you need to import the web proxy certificate (or the root certificate from its trust chain) as a trusted certificate.

If you have already imported the root certificate as trusted, you can skip this step.
Copy the certificate chain
[root@localhost ~]# cp /data/volumes/web-proxy/secrets/current_web_cert.crt /data/volumes-shared/cacerts/

After that, edit the file and only leave the root certificate in it.

Edit the chain file
[root@localhost ~]# nano /data/volumes-shared/cacerts/current_web_cert.crt

Start services in controlled way

Start the containerization platform. Use the command restart instead of start.

Start the Docker service
[root@localhost ~]# systemctl restart docker

After the update, new service configurations may use new Docker images which must be downloaded by the system during the first start of the service.

Since it is impossible to say with certainty how long the Docker image download will take, there is a risk that services will not start in the correct order. To avoid the issue, we will start them in a controlled way.

Note that we are also starting new services - iam-directory-server and iam-cas.
Controlled start of the independent services
[root@localhost ~]# systemctl start czechidm-db web-proxy iam-directory-server

If a new Docker image is being downloaded, the log file /var/log/messages will contain a line such as this one.

The system is downloading a new container image
Jan 28 09:42:32 localhost docker-compose[5967]: 12-r1: Pulling from bcv-postgres

After the image is downloaded, the container is automatically created and the service is started. Check that the service started correctly in its logfile /data/logs/SERVICENAME/SERVICENAME.log.

Start of remaining services
[root@localhost ~]# systemctl start czechidm iam-cas

Check that a service started successfully in its logs.

The czechidm service will take a relatively long time to start because it will have to relink the CzechIdM application. Make sure that the appliance has access to the repo.iamappliance.com repository. Otherwise, the relink will fail. The entire operation can take more than ten minutes, depending on the system resources available.

Enable the autostart of the new services

You need the enable the automatic start of new services after the operating system startup.

Enable the autostart of the new services
[root@localhost ~]# systemctl enable iam-directory-server iam-cas

Enable the backup creation

The directory server service has its own database which needs to be backed up regularly. Enable and start the scheduled task.

Enable the backup creation for the directory server
[root@appliance ~]# systemctl start iam-directory-server-backup.timer
[root@appliance ~]# systemctl enable iam-directory-server-backup.timer

Validate the functionality and security

Access the appliance web the same way you always do. If you were previously logged in to the CzechIdM and you will be let directly to the application without having to log in, log out.

You will be redirected to a log-in dialog which will be different than it was before. This is intentional since this is a log-in dialog of the access manager. Log-in here as user admin with password admin, the application will authenticate you and redirect you back to CzechIdM.

Secure the application by changing the administrator password!

By switching the authentication to the access manager, the password of the user admin was reset. Set a new one for the user, log out, and verify that you can log in with the new password.

A new password is generated for users and saved to the directory server of the appliance. As a result, they will be unable to log in to the appliance services. The only exception is if they are authenticated via external database (e. g., AD, AD via Kerberos, etc.).

If the authentication to the CzechIdM using the access manager works correctly, the update was successful. We recommend you restart the server and verify that each service started correctly.

Post-upgrade steps

We recommend you create a new snapshot of the server. You should keep the "before update" snapshot for at least one week.