První spuštění

Tato kapitola vás provede prvním spuštěním IAM appliance.

Předpokládáme nasazení VMDK souboru do virtualizace vmWare ESXi. Pro jiné platformy je tento postup obdobný, ale může se lišit v detailech.

Nasazení virtuálního serveru

  1. Máte k dispozici virtuální disk ve formátu VMDK, který jste naimportovali do storage a lze ho v administraci ESXi používat.

  2. Vytvořte nový virtuální server s potřebnými parametry a minimálně jednou ethernet síťovou kartou. Jako jeho pevný disk použijte dodaný VMDK.

    • Požadavky na prostředí (CPU, RAM, disk) najdete zde.

    • Dodaný virtuální disk je schválně definován menší, než stanovují doporučené požadavky. Bude potřeba ho v administraci virtualizace zvětšit.

    • Síťových karet můžete definovat i více. Appliance počítá s možností mít oddělené sítě pro uživatelský provoz, management segment nebo interconnect.

  3. Spusťte virtuální stroj a počkejte než appliance nastartuje.

    • Pokud appliance nestartuje, povyšte verzi virtuálního HW a zkontrolujte, zda je virtuální stroj definován jako x86_64.

    • Appliance v tuto chvíli obsahuje výchozího uživatele a heslo. Pokud máte v síti DHCP server, appliance si z něj načte adresu a může být dostupná po síti. Proto neodkládejte prvotní konfiguraci, která appliance zabezpečí.

  4. Resetujte hesla a šifrovací klíče.

    • Při vzniku základního VMDK image appliance se vygeneruje několik hesel a klíčů, které je nutné po nasazení na konkrétní prostředí vyměnit. Jinak budou různá nasazení appliance sdílet stejná hesla.

    • Reset popsaný v tomto návodu je nutné provést před prvním spuštěním služeb appliance.

  5. Upravte konfiguraci služeb appliance.

    • Je potřeba nakonfigurovat přístup k SW repozitářům, který je chráněn přihlášením. Přihlašovací údaje vám byly předány spolu s VMDK imagem.

    • Některé služby potřebují znát hostname (hostnamy), na kterém běží z pohledu uživatele.

  6. Spusťte služby appliance.

    • Appliance sestává z různých služeb, které se ve výchozím stavu nespouští. Je potřeba naplánovat jejich spuštění a oživit je.

  7. Aktualizujte appliance na poslední dostupnou verzi.

    • Virtuální disk appliance má jiný release cyklus než její softwarové komponenty. Po základním zprovoznění doporučujeme provést softwarovou aktualizaci.

Potřebné síťové prostupy

  • Přístup na služby appliance.

    • 22/tcp - SSHd vzdálený přístup pro administrátory a dodavatele.

    • 80/tcp, 443/tcp - Webové rozhraní aplikací v appliance - dashboard, identity manager CzechIdM, access manager CAS, aj.

    • 636/tcp - LDAP rozhraní appliance. Read-only, obsah LDAPu je spravován přes CzechIdM.

  • Přístup appliance do okolní infrastruktury.

    • Přístup na DHCP, DNS, NTP, apod. dle konkrétní infrastruktury.

    • Přístup na server na internetu repo.iamappliance.com, na porty 443/tcp a 8443/tcp. Tento server je pod správou výrobce a jsou na něm vystaveny softwarové repozitáře, které appliance využívá. Přístup je nutné povolit napřímo, není možné použít webovou proxy.

Potřebné údaje pro konfiguraci

Pro prvotní konfiguraci budete potřebovat informace o svém síťovém prostředí. Pokud budete používat DHCP adresaci, není nutné některé tyto parametry uvádět.

  • IP adresu a masku, kterou applianci přidělíte.

  • Výchozí gateway sítě.

  • IP adresy DNS serverů v síti.

  • Seznam vašich DNS domén v síti (tzv. "search domains").

  • NTP servery, které má appliance používat.

    • Pokud synchronizaci času řešíte propagací z hypervizoru, konfiguraci NTP přeskočte.

  • Silné heslo na uživatele root.

  • Hostname pro pojmenování serveru.

  • Hostname, na kterém budou služby appliance dostupné uživatelům. Může být jiný než hostname serveru.

  • Přihlašovací údaje do repozitářů autora appliance.

Pro účel tohoto tutoriálu budeme používat následující hodnoty. Přizpůsobte v tomto smyslu tutoriál svému prostředí.

  • Hostname serveru: iam-01.appliance.tld.

  • Hostname, na kterém je služba dostupná: iam.appliance.tld.

  • Login k repozitářům: iam_repo_u.

  • Heslo k repozitářům: iam_repo_p.

Prvotní konfigurace

  1. V administraci ESXi si otevřete lokální konzoli virtuálního serveru.

  2. Konzole serveru zobrazí varování, že appliance není inicializovaná. Součástí tohoto varování je i výchozí login a heslo root:demodemo.

  3. Přihlašte se výchozími přihlašovacími údaji.

  4. Spusťte příkaz iam-firstboot, který vás provede usazením appliance do sítě.

Pokud se při konfiguraci spletete (nebo obdržíte chybu), stačí příkaz iam-firstboot spustit znovu a opakovat dané nastavení. Není nutné konfigurovat vždy vše znovu, již dokončené sekce lze přeskakovat pomocí volby 'n'.

Reset hesel a šifrovacích klíčů

V tuto chvíli je appliance dostupná po síti přes SSH. před reálným spuštěním jejích služeb, je potřeba resetovat tajemství v ní uložená.

V případě, že služby appliance už alespoň jednou nastartovaly, lze tento postup použít. Dojde ale ke kompletní ztrátě dat a disablování služeb.

  1. Spusťte službu Docker

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

  2. Přejděte do adresáře /root/ a resetujte obsah appliance. Během běhu skriptu se mohou objevit hlášení "No such container", která lze bezpečně ignorovat.

    [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...
... zkráceno ...
Resetting app data and secrets...
... zkráceno ...
Deleting app data...
... zkráceno ...
Deleting app secrets...
... zkráceno ...
Reinitializing apps by running their %post scriptlets...
... zkráceno ...
Copying web proxy certificate to trusted certs...
... zkráceno ...
Resetting appliance's services done.

  3. Pokud skript proběhl bez chyb, lze smazat jeho logy a pracovní adresář. V těchto souborech lze případně najít ladící informace z běhu skriptu.

    [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. Povolte spouštění základních systémových služeb appliance, které resetovací skript v předchozím kroku vypnul. Službu chronyd povolte pouze pokud jste konfigurovali synchronizaci času pomocí NTP.

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

Napojení softwarových repozitářů

Appliance využívá dva typy repozitářů - RPM balíčky pro operační systém a Docker registry pro image kontejnerů jednotlivých aplikací.

Přihlašovací údaje vám byly předány dodavatelem spolu s imagem virtuálního server.

  1. Přihlášení do RPM repozitáře.

    1. Konfigurace repozitáře se nachází v souborech /etc/yum/vars/iam_username a /etc/yum/vars/iam_password, které je potřeba editovat. K editaci můžete použít programy nano (uživatelsky přívětivější) nebo vim.

      V souboru iam_username je potřeba doplnit login
      [root@iam-01 ~]# nano /etc/yum/vars/iam_username
iam_repo_u

    2. Potvrďte editaci (ctrl+o, enter) a ukončete editor (ctrl+x).

    3. Stejně postupujte pro soubor iam_password, kde vyplňte heslo.

    4. Občerstvěte cache správce balíčků. Tím zároveň otestujete správnou konfiguraci repozitáře.

      Provedení refreshe balíčků
      [root@iam-01 ~]# dnf makecache

  2. Přihlášení do Docker repozitáře.

    1. Vyvolejte přihlášení pomocí příkazu a zadejte stejné přihlašovací údaje jako pro RPM repozitář.

      Přihlášení do Docker registry
      [root@iam-01 ~]# docker login repo.iamappliance.com:8443
Username: iam_repo_u
Password: iam_repo_p (<-- heslo nebude při zadávání vidět)
... zkráceno ...
Login Succeeded

Úprava konfigurace služeb - CAS

Aplikace CAS potřebuje znát svůj hostname a používaný protokol.

  1. Editujte soubor /data/registry/node-active-config/docker-compose-cas.yml, opět pomocí nano nebo vim, a doplňte nastavení CAS_SERVER_NAME a JAVA_OPTS_ADD.

... zkráceno ...
      - CAS_SERVER_NAME=https://iam.appliance.tld
      - JAVA_OPTS_ADD="-Dlog4j2.formatMsgNoLookups=true"
... zkráceno ...
Uvedený protokol MUSÍ být https a hostname služby NESMÍ končit lomítkem.

Úprava konfigurace služeb - CzechIdM

Aplikace CzechIdM potřebuje z bezpečnostních důvodů znát hostname (nebo hostnamy), na nichž je dostupná uživatelům. Tato informace se liší na každém prostředí, proto je nutné ji doplnit. Dále je nutné provést několik dolaďovacích úprav.

  1. Editujte soubor /data/registry/node-active-config/docker-compose-czechidm.yml, opět pomocí nano nebo vim.

  2. Řádek image: repo.iamappliance.com:8443/bcv-czechidm:10.8.2-r1 změňte na image: repo.iamappliance.com:8443/bcv-czechidm:10.8.2-r2.

  3. Doplňte do konfigurace proměnnou - JAVA_OPTS_ADD="-Dlog4j2.formatMsgNoLookups=true".

  4. Řádek s konfigurací CZECHIDM_ALLOWED_ORIGINS= vyplňte dle potřeby.

    • Doporučujeme ponechat záznam http://localhost pro případ řešení provozních potíží.

    • Doplňte další hostnamy nebo IP adresy včetně protokolu. Protokol bude vždy https://. Záznamy oddělujte čárkou a nedělejte mezery. Jednotlivé záznamy nesmí končit lomítkem.

    • Z této konfigurace se generují i klikatelné odkazy v mailových oznámeních, které IdM odesílá. Adresu, kterou chcete mít uvedenou v klikatelných odkazech, uveďte jako první.

  5. Řádky s konfigurací CZECHIDM_CAS_URL, CZECHIDM_CAS_IDM_URL a CZECHIDM_CAS_HEADER_PREFIX vyplňte následovně.

    • Změňte protokol z http na https.

    • Změňte localhost na hostname pod kterým je appliance dostupná uživatelům.

  6. Potvrďte editaci (ctrl+o, enter) a ukončete editor (ctrl+x).

Příklad konfigurace služby CzechIdM
[root@iam-01 ~]# nano /data/registry/node-active-config/docker-compose-czechidm.yml
... zkráceno ...
    image: repo.iamappliance.com:8443/bcv-czechidm:10.8.2-r2
... zkráceno ...
      - 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=
... zkráceno ...

Jako poslední krok je nutné vyplnit registraci aplikace CzechIdM v access manageru CAS.

  1. Editujte soubor /data/volumes-shared/cas-services/idm-200.json.

  2. Upravte řádek s nastavením serviceId.

  3. Přidejte nový řádek se záznamem redirectUrl. Nezapomeňte na jemu předcházející řádek přidat čárku na konec. Výsledný soubor musí být validní JSON dokument.

  4. Potvrďte editaci (ctrl+o, enter) a ukončete editor (ctrl+x).

Příklad registrace služby CzechIdM
[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"
}

Nasazení HTTPS certifikátu

Pro správnou funkci jednotlivých komponent appliance je nutné nasadit validní HTTPS certifikát.Pro nasazení certifikátu využijte tohoto návodu, ale na jeho konci NEPROVÁDĚJTE restart služeb.

Pokud používáte pro přístup ke službám appliance stejné doménové jméno jako je hostname serveru, resetovací skript sám vygeneroval self-signed certifikát s odpovídajícím záznamem. V takovém případě lze nasazení korektního HTTPS certifikátu odložit a tento postup dokončit se self-signed certifikátem.

Spuštění služeb appliance

Služby appliance mají definované pořadí spouštění. Protože je startujeme poprvé, některé musí inicializovat svá data - to může trvat i několik minut. Aby nedošlo k předběhnutí jejich startu, spustíme je jednu po druhé ručně.

  1. Nastartujte službu iam-czechidm-db. Jde o PostgreSQL databázi pro CzechIdM identity manager. Úspěšný start vypadá takto.

    [root@iam-01 ~]# systemctl start iam-czechidm-db
[root@iam-01 ~]# tail /data/logs/czechidm-db/czechidm-db.log
... zkráceno ...
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. Spusťte službu iam-directory-server adresářového serveru a nechte ji inicializovat. Inicializace bude trvat několik minut, protože se generují DH parametry pro TLS.

    [root@iam-01 ~]# systemctl start iam-directory-server
[root@iam-01 ~]# tail /data/logs/directory-server/directory-server.log
... zkráceno ...
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. Spusťte službu iam-web-proxy webového frontendu appliance.

    [root@iam-01 ~]# systemctl start iam-web-proxy.service
[root@iam-01 ~]# tail /data/logs/web-proxy/web-proxy.log
... zkráceno ...
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. Spusťte službu iam-cas access manageru CAS.

    [root@iam-01 ~]# systemctl start iam-cas
[root@iam-01 ~]# tail /data/logs/cas/cas.log
... zkráceno ...
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. Spusťte službu iam-czechidm identity manageru CzechIdM. Identity manager se musí relinkovat, jeho start může trvat i více než 10 minut a je podmíněn dostupností serveru repo.iamappliance.com s repozitáři výrobce.

    [root@iam-01 ~]# systemctl start iam-czechidm
[root@iam-01 ~]# tail -f /data/logs/czechidm/czechidm.log
... zkráceno ...
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. Pokud všechny služby nastartovaly korektně, povolte jejich autostart. Zároveň povolte autostart naplánovaných úloh zálohování a čištění.

    [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. Restartujte server.

    [root@iam-01 ~]# reboot

  8. Po startu serveru počkejte několik minut až všechny služby naběhnou. Pak přistupte ve svém webovém prohlížeči na adresu appliance, kde uvidíte základní rozcestník.

  9. Přihlašte se do CzechIdM výchozím loginem admin a heslem admin a heslo ihned změňte.

Aktualizace appliance

Zjistěte dostupnou verzi appliance ve vaší výchozí instalaci pomocí příkazu dnf info iam-appliance. Tento příkaz zobrazí i nejvyšší aktuálně dostupnou verzi. Pro použití příkazu dnf musíte mít funkční softwarové repozitáře.

Po zjištění vaší a poslední dostupné verze IAM appliance postupujte podle konkrétního Update Guide.

Po aktualizaci appliance samotné proveďte ještě plošnou aktualizaci operačního systému dle příslušného návodu.