First boot

This chapter presents steps needed when the IAM appliance is started for the very first time.

This tutorial assumes that a VMDK file is deployed is a vmWare ESXi virtualization. The steps for other platforms are similar but they may differ in some details.

Deploy the virtual server

  1. You have received a virtual drive in a VMDK format which you imported into your storage and can use in the ESXi administration.

  2. Create new virtual server with required parameters and at least one ethernet network card. Configure the supplied VMDK as its hard drive.

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

    • The supplied virtual drive is deliberately defined as smaller than required. It will need to be extended once it is imported in your virtualization platform.

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

  3. 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 a 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.

  4. Reset the password and encryption keys.

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

    • The reset described in this tutorial need to be done before the first start of the appliance services.

  5. 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 VMDK image.

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

  6. Start the appliance services.

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

  7. Update the appliance to the last available version.

    • The appliance virtual drive has a different release cycle than its software components. 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 have 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.

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'.

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 the 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 were found, 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 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 a command and fill out 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 JAVA_OPTS_ADD.

... abbreviated ...
      - CAS_SERVER_NAME=https://iam.appliance.tld
      - JAVA_OPTS_ADD="-Dlog4j2.formatMsgNoLookups=true"
... 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. Change the line image: repo.iamappliance.com:8443/bcv-czechidm:10.8.2-r1 to image: repo.iamappliance.com:8443/bcv-czechidm:10.8.2-r2.

  3. Add a property - JAVA_OPTS_ADD="-Dlog4j2.formatMsgNoLookups=true" to the configuration.

  4. Fill out the line CZECHIDM_ALLOWED_ORIGINS= as required.

    • We recommend you leave the item http://localhost to solve possible operational issues.

    • 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 hostname in this configuration property.

  5. The lines with configuration CZECHIDM_CAS_URL, CZECHIDM_CAS_IDM_URL, and CZECHIDM_CAS_HEADER_PREFIX should be filled out as follows.

    • Change the protocol from http to https.

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

  6. 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:10.8.2-r2
... 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/
      - CZECHIDM_CAS_HEADER_PREFIX=https://iam.appliance.tld/idm/?ticket=
... 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. Add a new line with the property redirectUrl. Do not forget to add a comma to the end of the preceding line. The resulting file must be a valid JSON document.

  4. 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,
  "redirectUrl": "https://iam.appliance.tld/idm/#/login"
}

Deploy a HTTPS certificate

The IAM appliance needs to have a valid HTTPS certicate for the correct behavior of each individual component. Use 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.