First boot

This howto will walk you through IAM appliance initialization. Initialization is the first thing you have to perform when you are deploying the appliance into your infrastructure.

This tutorial assumes that you received an OVA file to deploy into vmWare ESXi virtualization. Steps for other platforms are similar but they may differ in some details.

This howto is intended for IAM appliance images 20220921 (meaning YYYYmmdd). For other images, please see other versions of this document.

Read the howto carefully, do not just blindly copy code snippets.

Deploy the virtual server

  1. You have received a virtual machine in an OVA format which you imported using your vSphere admin interface. First, you need to configure the imported virtual machine.

    • Sizing requirements (CPU, RAM, drive) can be found here.

    • The supplied virtual drive is deliberately defined as smaller than required. You shall extend it once the virtual machine is imported into your virtualization platform.

    • You can define multiple network cards. The appliance supports separated networks for user traffic, management segment, or interconnect.

  2. Boot up the virtual machine and wait for the appliance to start.

    • If the appliance does not start, increase the version of the virtual HW and check that the virtual machine is defined as x86_64.

    • At this moment, the appliance contains default user and password. If your network has a DHCP server, the appliance may obtain address from it and it can be available over the network. Therefore, do not postpone the initial configuration which secures the appliance.

  3. Reset the password and encryption keys.

    • When the base appliance image is created, there are several pre-set passwords and keys. These need to be replaced after deploying the appliance into your infrastructure to prevent sharing passwords between different appliance deployments.

    • The reset described in this tutorial needs to be done before first start of appliance’s services.

  4. Change the appliance services configuration.

    • You need to configure the access to SW repositories which are protected by requiring credentials. You received those credentials along with the OVA image.

    • Some services need to know the hostname(s) they run on from the user’s perspective.

  5. Start the appliance services.

    • The appliance contains multiple services which are not started by default. Their start needs to be planned and activated.

  6. Update the appliance to the latest available version.

    • The appliance virtual drive has different release cycle than software components inside. After the initial configuration, we recommend you update the software.

Required ports

  • To access appliance services.

    • 22/tcp - SSHd remote access for administrators and external consultants.

    • 80/tcp, 443/tcp - The web interface for the appliance applications - dashboard, identity manager CzechIdM, access manager CAS, etc.

    • 636/tcp - LDAP interface of the appliance. Read-only, the LDAP content is managed via CzechIdM.

  • The appliance access to the surrounding infrastructure.

    • DHCP, DNS, NTP etc. access (based on your infrastructure).

    • The access to the internet server repo.iamappliance.com, ports 443/tcp and 8443/tcp. This server is maintained by the appliance manufacturer and it contains software repositories used by the appliance. The access needs to be given directly without the use of web proxy.

Required configuration information

For the initial configuration, you will need to gather some information about your network environment. If you use DHCP addressing, some of the following parameters are not required.

  • IP address and network mask given to the appliance.

  • Default network gateway.

  • IP addresses of DNS servers in the network.

  • A list of your DNS domains in the network (search domains).

  • NTP servers which will be used by the appliance.

    • If you use hypervisor propagation to synchronize time, skip the NTP configuration.

  • A strong password for the user root.

  • Hostname of the server.

  • Hostname which will be used by users to access the appliance services. It can be different than the server hostname.

  • Credentials for the appliance manufacturer repositories.

We will use the following values in this tutorial. Change them to reflect your deployment.

  • Server hostname: iam-01.appliance.tld.

  • Hostname from which the service is avaiable: iam.appliance.tld.

  • Repository login: iam_repo_u.

  • Repository password: iam_repo_p.

Initial configuration

  1. In the vSphere, open the local console of the virtual server.

  2. The server console will warn you that the appliance is not initialized. A part of the warning is the default login and password root:demodemo.

  3. Login with the default credentials.

  4. Run the iam-firstboot command which will guide you through the appliance network settings.

iam-firstboot

If you make a mistake (or you see an error) during configuration, you can run the command iam-firstboot again and reconfigure the settings. You don’t need to configure everything from scratch, already finished sections can be skipped by using the option 'n'.

The iam-firstboot tool helps you to set up networking, server hostname, time zone, time synchronization and root password. It also performs some tasks under the hood. If you follow instructions provided by the iam-firstboot, you should have no problem to get your appliance set up. However, networking configuration is provided by nmtui for which we also provide some guidance.

  1. Invoke the firstboot tool by running iam-firstboot command.

  2. Network configuration

    1. Once the TUI starts, select Edit a connection. There, you should see only Wired connection 1 interface.

      • It is possible to see multiple network interfaces, especially if you are setting up separate networks for users, administrators, interconnect, etc. If this is your case, look for MAC addresses - they will help you determine which network interface is which.

    2. Select Wired connection 1 interface and configure it to suit your network environment.

      • Example: IPv4 DHCP + IPv6 DHCP configuration.

        Example of DHCP configuration both for IPv4 and IPv6
        Figure 1. Example of DHCP configuration both for IPv4 and IPv6

      • Example: IPv4 static + disabled IPv6 configuration.

        Example of static IPv4 configuration and disabled IPv6
        Figure 2. Example of static IPv4 configuration and disabled IPv6

    3. When you are done, save changes by selecting OK.

    4. When you have configured all interfaces you need, leave the TUI by selecting Quit.

  3. Hostname configuration

    • Follow instructions on screen.

  4. NTP configuration

    • Follow instructions on screen.

  5. Timezone configuration

    • Follow instructions on screen.

  6. Root password

    • Follow instructions on screen.

  7. Reboot the machine as the firstboot tool told you to.

Password and encryption key reset

At this moment, the appliance is available over the network using SSH. Before starting its services, you need to reset secrets saved in the appliance.

If the appliance services were started at least once in the past, these steps may be followed. However, the result will be a complete loss of all data and disabling of the services.

  1. Start the Docker service

    [root@iam-01 ~]# systemctl enable --now docker

  2. Navigate to the directory /root/ and reset the appliance content. While the script is running, you may notice "No such container" errors. You can ignore them safely.

    [root@iam-01 ~]# cd /root/
[root@iam-01 ~]# ./factory-reset.sh reset-app-data-and-secrets 2>&1 | tee -a factory-reset.log
Stopping and disabling appliance services...
... abbreviated ...
Resetting app data and secrets...
... abbreviated ...
Deleting app data...
... abbreviated ...
Deleting app secrets...
... abbreviated ...
Reinitializing apps by running their %post scriptlets...
... abbreviated ...
Copying web proxy certificate to trusted certs...
... abbreviated ...
Resetting appliance's services done.

  3. If the script finished without errors, its logs and working directory can be removed. However, if some errors occurred, further information useful for debugging can be found in these files.

    [root@iam-01 ~]# ll
total 16
drwx------. 2 root root 4096 Nov 26 10:34 factory-reset.d7JH
-rw-r--r--. 1 root root 3288 Nov 26 10:34 factory-reset.log
-rwxr--r--. 1 root root 5207 Nov 24 14:57 factory-reset.sh

[root@iam-01 ~]# rm -rf factory-reset.log factory-reset.d7JH

  4. Enable the start of basic system services of the appliance which were turned off by the reset script in the previous step. Enable the service chronyd only if you previously configured time synchronization using NTP.

    [root@iam-01 ~]# systemctl enable --now docker sshd iptables ip6tables chronyd

Connecting software repositories

The appliance uses two repository types: RPM packages for the operating system, and a Docker registry for images of each application image.

You received the credentials from the supplier along with the virtual server image.

  1. Sign in to the RPM repository.

    1. The repository configuration is located in files /etc/yum/vars/iam_username and /etc/yum/vars/iam_password. You need to edit those two files, using either nano (more user friendly), or vim.

      Fill out your login in iam_username
      [root@iam-01 ~]# nano /etc/yum/vars/iam_username
iam_repo_u

    2. Confirm the change (ctrl+o, enter) and exit the editor (ctrl+x).

    3. Repeat the steps for file iam_password, fill out your password.

    4. Refresh the package manager cache. This will also test that the repository configuration is correct.

      Refresh the package manager cache
      [root@iam-01 ~]# dnf makecache

  2. Sign in to the Docker registry.

    1. Start the sign in process using following command and provide the same credentials you used for the RPM repository.

      Sign in to the Docker registry
      [root@iam-01 ~]# docker login repo.iamappliance.com:8443
Username: iam_repo_u
Password: iam_repo_p (<-- the password will not be visible when typing)
... abbreviated ...
Login Succeeded

Change the services configuration - CAS

The CAS application needs to know its own hostname and the protocol used.

  1. Edit the file /data/registry/node-active-config/docker-compose-cas.yml, using nano or vim and add the configuration items CAS_SERVER_NAME, and CAS_SERVER_SCOPE.

    • CAS_SERVER_NAME is the hostname which will clients (users, other applications) use to communicate with CAS. You have to specify hostname prepended with https:// .

    • CAS_SERVER_SCOPE is a SAML2 scope. Set it to the domain you are deploying the IAM appliance for. For example if you want the appliance to be IdP for the whole appliance.tld, set it to appliance.tld.

... abbreviated ...
      - CAS_SERVER_NAME=https://iam.appliance.tld
      - CAS_SERVER_SCOPE=appliance.tld
... abbreviated ...
The configured protocol must be https and the service hostname MUST NOT end with a forward slash.

Change the services configuration - CzechIdM

For security reasons, the CzechIdM application needs to know the hostname(s) on which it is available to users. This information is different in different environments, and therefore needs to be set up. There are several other changes you need to make.

  1. Edit the file /data/registry/node-active-config/docker-compose-czechidm.yml using nano or vim.

  2. Fill out the line CZECHIDM_ALLOWED_ORIGINS= as required.

    • We recommend to keep the item http://localhost for solvi possible operational issues that might need accessing application on the localhost.

    • Add other hostnames or IP addresses including the protocol. The protocol will always be https://. Separate each hostname with a comma, do not use spaces. No hostname may end with a forward slash.

    • This configuration is used to generate links in email notifications sent from CzechIdM. The address which should be used in notification must be the first one in this configuration property.

  3. Lines with configuration CZECHIDM_CAS_URL and CZECHIDM_CAS_IDM_URL should be filled out as follows.

    • Change the protocol from http to https.

    • Change localhost to the hostname on which users access the appliance.

  4. Confirm the changes (ctrl+o, enter) and exit the editor (ctrl+x).

An example of the CzechIdM service configuration
[root@iam-01 ~]# nano /data/registry/node-active-config/docker-compose-czechidm.yml
... abbreviated ...
    image: repo.iamappliance.com:8443/bcv-czechidm:12.2.0-r0
... abbreviated ...
      - CZECHIDM_ALLOWED_ORIGINS=https://iam.appliance.tld,http://localhost
      - CZECHIDM_CAS_URL=https://iam.appliance.tld/cas
      - CZECHIDM_CAS_IDM_URL=https://iam.appliance.tld/idm
... abbreviated ...

As a last step, you need to fill out the CzechIdM application registration in the CAS access manager.

  1. Edit the file /data/volumes-shared/cas-services/idm-200.json.

  2. Change the line with the property serviceId.

  3. Confirm the changes (ctrl+o, enter) and exit the editor (ctrl+x).

An example of the CzechIdM service registration
[root@iam-01 ~]# nano /data/volumes-shared/cas-services/idm-200.json
{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "https://iam.appliance.tld/idm.+",
  "name" : "CzechIdM",
  "id" : 200,
  "evaluationOrder" : 1
}

Deploy a HTTPS certificate

The IAM appliance needs to have a valid HTTPS certicate for the correct behavior of each individual component. You can use this tutorial to deploy a certificate but DO NOT RESTART the service at the end of the process.

If you use the same domain name as the server hostname to access the appliance services, the reset script generated a self-signed certificate with a correct name. In this case, you can postpone the HTTPS certificate deployment and finish this tutorial with a self-signed certificate.

Start the appliance services

The appliance services have a defined order in which they should be started. Because we are starting them for the first they, some of them need to initialize their data. This can take several minutes. To guarantee the correct order in which they are started, we need to start them one after the other manually.

  1. Start the service iam-czechidm-db. This is a PostgreSQL database used by the CzechIdM identity manager. A successful start looks like this

    [root@iam-01 ~]# systemctl start iam-czechidm-db
[root@iam-01 ~]# tail /data/logs/czechidm-db/czechidm-db.log
... abbreviated ...
Nov 26 10:51:59 iam-01.appliance.tld czechidm-db[1437]: PostgreSQL init process complete; ready for start up.
Nov 26 10:51:59 iam-01.appliance.tld czechidm-db[1437]: 2021-11-26 09:51:59.182 UTC [1] LOG:  starting PostgreSQL 12.5 (Debian 12.5-1.pgdg100+1) on x86_64-pc-linux-gnu, compiled by gcc (Debian 8.3.0-6) 8.3.0, 64-bit
Nov 26 10:51:59 iam-01.appliance.tld czechidm-db[1437]: 2021-11-26 09:51:59.183 UTC [1] LOG:  listening on IPv4 address "0.0.0.0", port 5432
Nov 26 10:51:59 iam-01.appliance.tld czechidm-db[1437]: 2021-11-26 09:51:59.183 UTC [1] LOG:  listening on IPv6 address "::", port 5432
Nov 26 10:51:59 iam-01.appliance.tld czechidm-db[1437]: 2021-11-26 09:51:59.188 UTC [1] LOG:  listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
Nov 26 10:51:59 iam-01.appliance.tld czechidm-db[1437]: 2021-11-26 09:51:59.258 UTC [80] LOG:  database system was shut down at 2021-11-26 09:51:59 UTC
Nov 26 10:51:59 iam-01.appliance.tld czechidm-db[1437]: 2021-11-26 09:51:59.267 UTC [1] LOG:  database system is ready to accept connections

  2. Start the iam-directory-server service of the directory server and let it initiale its data. The initialization will take several minutes since DH parameters for TLS are generated.

    [root@iam-01 ~]# systemctl start iam-directory-server
[root@iam-01 ~]# tail /data/logs/directory-server/directory-server.log
... abbreviated ...
Nov 26 10:53:55 iam-01.appliance.tld directory-server[1437]: *** Running runit daemon...
Nov 26 10:53:55 iam-01.appliance.tld directory-server[1437]: 61a0aeb3 @(#) $OpenLDAP: slapd 2.4.50+dfsg-1~bpo10+1 (May  4 2020 05:25:06) $
Nov 26 10:53:55 iam-01.appliance.tld directory-server[1437]: #011Debian OpenLDAP Maintainers <pkg-openldap-devel@lists.alioth.debian.org>
Nov 26 10:53:55 iam-01.appliance.tld directory-server[1437]: TLS: warning: no certificate loaded from CA certificate file `/container/service/slapd/assets/certs/chain.pem'.
Nov 26 10:53:55 iam-01.appliance.tld directory-server[1437]: 61a0aeb3 slapd starting
Nov 26 10:53:56 iam-01.appliance.tld directory-server[1437]: Nov 26 09:53:56 directory-server syslog-ng[590]: syslog-ng starting up; version='3.19.1'

  3. Start the iam-web-proxy service of the appliance web frontend.

    [root@iam-01 ~]# systemctl start iam-web-proxy.service
[root@iam-01 ~]# tail /data/logs/web-proxy/web-proxy.log
... abbreviated ...
Nov 26 10:55:05 iam-01.appliance.tld web-proxy[1437]: /docker-entrypoint.sh: Launching /docker-entrypoint.d/20-envsubst-on-templates.sh
Nov 26 10:55:05 iam-01.appliance.tld web-proxy[1437]: /docker-entrypoint.sh: Configuration complete; ready for start up
Nov 26 10:55:05 iam-01.appliance.tld web-proxy[1437]: 2021/11/26 09:55:05 [warn] 1#1: duplicate MIME type "text/html" in /etc/nginx/nginx.conf:56
Nov 26 10:55:05 iam-01.appliance.tld web-proxy[1437]: nginx: [warn] duplicate MIME type "text/html" in /etc/nginx/nginx.conf:56

  4. Start the iam-cas service of the CAS access manager.

    [root@iam-01 ~]# systemctl start iam-cas
[root@iam-01 ~]# tail /data/logs/cas/cas.log
... abbreviated ...
Nov 26 10:57:18 iam-01.appliance.tld cas[1437]: 26-Nov-2021 10:57:18.283 INFO [main] org.apache.catalina.startup.HostConfig.deployWAR Deployment of web application archive [/opt/tomcat/apache-tomcat-9.0.41/webapps/cas.war] has finished in [82,545] ms
Nov 26 10:57:18 iam-01.appliance.tld cas[1437]: 26-Nov-2021 10:57:18.288 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["http-nio-8080"]
Nov 26 10:57:18 iam-01.appliance.tld cas[1437]: 26-Nov-2021 10:57:18.399 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in [82918] milliseconds
Nov 26 10:57:18 iam-01.appliance.tld cas[1437]: #033[m#033[32m2021-11-26 10:57:18,636 INFO [org.apereo.cas.services.AbstractServicesManager] - <Loaded [3] service(s) from [JsonServiceRegistry].>

  5. Start the iam-czechidm service of the CzechIdM identity manager. The identity manager needs to be relinked, its start can take more than 10 minutes. To start, the server repo.iamappliance.com with the manufacturer repositories must be available.

    [root@iam-01 ~]# systemctl start iam-czechidm
[root@iam-01 ~]# tail -f /data/logs/czechidm/czechidm.log
... abbreviated ...
Nov 26 11:30:00 iam-01.appliance.tld czechidm[1437]: 2021-11-26 11:30:00.872  INFO 1135332 --- [base-task-executor-1] e.b.i.c.m.s.i.DefaultEntityEventManager.process : Publishing event [CoreEvent [type: UPDATE, content: eu.bcvsolutions.idm.core.scheduler.api.dto.IdmLongRunningTaskDto [id=2c344596-77a0-46f3-b2bf-cf8aa8af1973], properties: {idm:permission=[Leu.bcvsolutions.idm.core.security.api.domain.BasePermission;@178115e6}]]
Nov 26 11:30:00 iam-01.appliance.tld czechidm[1437]: 2021-11-26 11:30:00.873  INFO 1135333 --- [base-task-executor-1] e.b.i.c.a.e.AbstractEntityEventProcessor.onApplicationEvent : Processor [core-long-running-task-save-processor]([core]) start for [CoreEvent [type: UPDATE, content: eu.bcvsolutions.idm.core.scheduler.api.dto.IdmLongRunningTaskDto [id=2c344596-77a0-46f3-b2bf-cf8aa8af1973], properties: {idm:permission=[Leu.bcvsolutions.idm.core.security.api.domain.BasePermission;@178115e6}]] with order [0].
Nov 26 11:30:00 iam-01.appliance.tld czechidm[1437]: 2021-11-26 11:30:00.875  INFO 1135335 --- [base-task-executor-1] e.b.i.c.a.e.AbstractEntityEventProcessor.onApplicationEvent : Processor [core-long-running-task-save-processor]([core]) end for [CoreEvent [type: UPDATE, content: eu.bcvsolutions.idm.core.scheduler.api.dto.IdmLongRunningTaskDto [id=2c344596-77a0-46f3-b2bf-cf8aa8af1973], properties: {idm:permission=[Leu.bcvsolutions.idm.core.security.api.domain.BasePermission;@178115e6}]] with order [0].

  6. If all services started correctly, enable their autostart. After that, enable the autostart of the planned tasks for backups and cleaning.

    [root@iam-01 ~]# systemctl enable iam-czechidm-db iam-czechidm iam-web-proxy iam-cas iam-directory-server
Created symlink /etc/systemd/system/multi-user.target.wants/iam-czechidm-db.service → /usr/lib/systemd/system/iam-czechidm-db.service.
Created symlink /etc/systemd/system/multi-user.target.wants/iam-czechidm.service → /usr/lib/systemd/system/iam-czechidm.service.
Created symlink /etc/systemd/system/multi-user.target.wants/iam-web-proxy.service → /usr/lib/systemd/system/iam-web-proxy.service.
Created symlink /etc/systemd/system/multi-user.target.wants/iam-cas.service → /usr/lib/systemd/system/iam-cas.service.
Created symlink /etc/systemd/system/multi-user.target.wants/iam-directory-server.service → /usr/lib/systemd/system/iam-directory-server.service.

[root@iam-01 ~]# systemctl enable --now iam-czechidm-db-backup.timer iam-directory-server-backup.timer iam-docker-images-prune.timer
Created symlink /etc/systemd/system/multi-user.target.wants/iam-czechidm-db-backup.timer → /usr/lib/systemd/system/iam-czechidm-db-backup.timer.
Created symlink /etc/systemd/system/multi-user.target.wants/iam-directory-server-backup.timer → /usr/lib/systemd/system/iam-directory-server-backup.timer.
Created symlink /etc/systemd/system/multi-user.target.wants/iam-docker-images-prune.timer → /usr/lib/systemd/system/iam-docker-images-prune.timer.

  7. Restart the server.

    [root@iam-01 ~]# reboot

  8. After the server starts, wait several minutes for all services to start. Afterwards, access the appliance address in your browser. You will a be greeted by basic landing page.

  9. Log in to CzechIdM with the default login admin and password admin and change the password immediately.

Appliance update

Find the available appliance version in your default installation using the command dnf info iam-appliance. This command will show the newest currently available version. To use the command dnf, you must have working software repositories.

To find your version and the last available version of the IAM appliance, follow the specific Update Guide.

After updating the appliance itself, carry out a general update of the operating system using a relevant guide.