Wstęp

1. Podział strukturalny
   System PASK jest możliwy do zainstalowania na serwerach linux. Aby lepiej zrozumieć proces instalacji i działanie samego systemu przedstawiamy podział strukturalny systemu ze względu na serwery.

2. Wymagania sprzętowe
   Poniżej przedstawiamy minimalne wymagania sprzętowe dla PASK

3. Potrzebne informacje oraz pliki
   Aby poprawnie zainstalować PASK potrzebujemy kilku informacji oraz plików, które należy przygotować przed przystąpieniem do instalacji.

   1. Użytkownik z uprawnieniami root na obu serwerach

   2. Udrożnione połączenie sieciowe między serwerami ( potrzeba komunikacji na wielu portach poprzez sieć LAN )

   3. Udrożnione połączenie sieciowe z serwerów na których będzie instalowany PASK do WAN w celu pobrania repozytorium oraz obrazów docker

   4. FQDN dla PASK skierowany na serwer main - pod tym FQDN będzie dostępny PASK po zakończonym procesie instalacji. Może być lokalny jeśli PASK ma działać jedynie w sieci LAN lub globalny jeśli PASK ma być dostępny z sieci WAN

   5. Certyfikat oraz klucz prywatny SSL w formacie PEM tożsamy z FQDN ( wildcard dla domeny jest dopuszczalny )

   6. Konto oraz dane dostępowe SMTP w celu konfiguracji wysyłki powiadomień e-mail

   7. Jeśli istnieje potrzeba integracji z AD stworzyć użytkownika w domenie z uprawnieniami read-only

4. Wymagania systemowe

   1. Instalacja pakietów
      Dodatkowo na serwerach należy zainstalować poniższe pakiety aplikacyjne aby instalacja przebiegła bez problemu. Część aplikacji powinna być już zainstalowana w systemie, natomiast z racji różnic wynikających z różnych wersji systemu podajemy pełną listę aplikacji potrzebnych do instalacji w formie skryptu instalacyjnego “kopiuj - wklej”

      apt-get update && apt-get upgrade -y
      apt-get install -y apt-transport-https ca-certificates curl software-properties-common python3-pip virtualenv python3-setuptools cloud-guest-utils jq git
      sudo apt-get update
      sudo apt-get install -y ca-certificates curl
      sudo install -m 0755 -d /etc/apt/keyrings
      sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
      sudo chmod a+r /etc/apt/keyrings/docker.asc
      
      # Add the repository to Apt sources:
      echo \
        "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
        $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
        sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
      sudo apt-get update
      
      sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
      docker compose version

   2. Konfiguracja katalogów
      Kolejnym krokiem jest konfiguracja struktury katalogów potrzebnych do poprawnej instalacji i działania PASK

      cd /opt
      mkdir pask pask/data
      chmod 777 pask/data
      mkdir composer
      cd composer

      Po poprawnym wykonaniu poleceń układ katalogów na serwerach powinien wyglądać następująco

      /opt/
      ├── composer
      └── pask
          └── data

   3. Wgranie plików instalacyjnych PASK
      Ostatnim krokiem wstępu jest wgranie plików systemu PASK na srewery. Pliki należy skopiować włącznie z katalogiem iamu-composer do katalogu /opt/composer . Po poprawnym wgraniu plików w katalogu powinniśmy otrzymać taki widok po wydaniu polecenia ll /opt/composer/iamu-composer

Instalacja

1. Kroki do wykonania na obu serwerach.

1.2.  Zalogować się do docker registry uniteamprod.azurecr.io ( dane logowania zostaną przesłane w bezpieczny sposób )

docker login uniteamprod.azurecr.io 

1.3.  Jeśli posiadacie Sswoje certyfikaty SSL należy ich zawartość skopiować do katalogu /opt/composer/iamu-composer/proxy

1.4.  Podmienić dane w pliku iamu-composer/variables.env
UWAGA!!! Niektóre holdery pojawiają się więcej niż raz w pliku variables.env np. [UTILS_IP]
Dodatkowo wartości w tabeli oznaczone na pomarańczowo są opcjonalne w zależności od wybranego dostawcy AD. PASK umożliwia utworzenie lokalnego AD (OpenLDAP) w przypadku gdy firma nie posiada własnego AD.
Wszystkie i secrety muszą się składać wyłącznie z dużych i małych liter oraz cyfr, zabronione są znaki specjalne. Minimalna długość to 18 znaków.
 

1.5.  W pliku nginx.conf dostarczonym w iamu-composer/proxy  podmienić wszystkie frazy „ utils ” na adres IP serwera utils.

2. Serwer Utils

2.1. 

 cd /opt/composer/iamu-composer 

2.2.  W zależności od tego czy pask ma być uruchomiony z openldap czy nie: 

2.2.1.      Z openldap wykonać polecenie 

docker compose -f utils-compose.yml --profile utils-prod-ldap --env-file variables.env up -d

2.2.2.      Bez openldap wykonać polecenie 

docker compose -f utils-compose.yml --profile utils-prod --env-file variables.env up -d

2.3.  Aby weryfikować poprawność działania serwisów możemy wykonać komendę docker ps -a 

2.4.  UWAGA! Poprawne działanie oznacza że kontenery posiadające status healtcheck mają status healthy a nie starting/unhealthy. Wyjątkiem są kontenery liquibase które restartują się tak długo aż wszystkie usługi nie zostaną poprawnie zaimplementowane, o czym przechodzą w status exited

3. Serwer Main 

3.1. 

mkdir -p /opt/pask/data/keycloak/conf/truststores

3.2. 

cd /opt/composer/iamu-composer

3.3.  W zależności od tego czy pask ma być uruchomiony z openldap czy nie: 

3.3.1.            Z openldap wykonać polecenie 

docker compose -f main-compose.yml --profile main-prod-ldap --env-file variables.env up -d

3.3.2.      Bez openldap wykonać polecenie 

docker compose -f main-compose.yml --profile main-prod --env-file variables.env up -d

3.4. Zmienić uprawnienia w katalogu /opt/pask/data po wykonaniu się polecenia docker compose

chmod -R 777 /opt/pask/data

3.4.  Aby weryfikować poprawność działania serwisów możemy wykonać komendę 

docker ps -a 

3.5.  UWAGA! Poprawne działanie oznacza że kontenery posiadające status healtcheck mają status healthy a nie starting/unhealthy. Wyjątkiem są kontenery keycloak-manager które restartują się tak długo aż wszystkie usługi nie zostaną poprawnie zaimplementowane, o czym przechodzą w status exited

4. (Krok dodatkowy na serwerze main) Instalacja własnego certyfikatu CA do PASK
   WAŻNE!!! Jeśli instalujemy własny certyfikat  CA, jest on zapisany w PASK do kolejnej aktualizacji serwisów. Oznacza to że od tego momentu co aktualizację PASK należy wykonywać ten krok, certyfikat pozostanie w /opt/pask/data/… natomiast samo polecenie należy wykonać przy każdej aktualizacji. Wynika to z tego iż rootCA dostawców globalnych stale są zmieniane/odświeżane w związku z czym przy każdej wersji PASK w kontenerze dostarczony jest świeży plik z rootCA.

4.1.  Jeśli posiadasz własny certyfikat CA który powinien znaleźć się w PASK (np. do połączenia ldaps) możesz go dodać w następujący sposób

4.2.  Skopiuj certyfikat do /opt/pask/data/tenant-service/config
oraz do /opt/pask/data/keycloak/conf/truststores

4.3.  Podmień w poleceniu poniżej wartości „cert_alias” oraz „cert_name_in_config_directory”
(polecenie wykonujemy tylko dla tenant-service, instalacja certyfikatu w keycloak odbywa się poprzez skopiowanie certyfikatu do katalogu i restart kontenera)

docker exec tenant-service keytool -storepass changeit -noprompt -trustcacerts -importcert  -alias cert_alias -keystore /opt/java/openjdk/lib/security/cacerts -file /app/config/cert_name_in_config_directory

4.4.  Zrestartuj kontener keycloak oraz proxy (uwaga restart kontenerów może potrwać nawet kilka minut)

docker restart keycloak proxy

5. Inicjalizacja

5.1.  Uruchomić ponownie kontenery gateway oraz proxy 

docker restart gateway proxy 

5.2.  Uruchomić ponownie kontener frontend 

docker restart frontend 

5.3.  Zainicjalizować środowisko poprzez wykonanie metod POST na serwerze main
podmienić zmienne wg wzorów
${URL_from_variables.env} – pask.uniteam.pl

curl -k -d "client_id=pask" -d "client_secret=${AUTH_PASK_CLIENT_SECRET_from_variables.env}" -d "grant_type=client_credentials" https://${URL_from_variables.env}/keycloak/realms/${ON_PREMISE_TENANT_ID_from_variables.env}/protocol/openid-connect/token

{{ access_token_from_previous_POST }} – eyJhbGc…BwBRpWQ

curl -X POST http://localhost:8301/init-on-premise -H "Authorization: Bearer {{ access_token_from_previous_POST }}" -H "Content-Type: application/json" -d '{"email":"pask@pask.id","timeZone":"Europe/Warsaw","language":"pl/PL"}' -k

6. Konfiguracja Keycloak

Następnym krokiem będzie konfiguracja narzędzia keycloak tak aby przenieść zadanie uwierzytelniania oraz przypisywania ról właśnie na te narzędzie.  Do wyboru są dwie ścieżki postępowania.
Konfigurację należy dobrać adekwatnie do posiadanego środowiska oraz typu mapowania które dzielimy następująco:

AD (Microsoft)

               Konfiguracja federacji – 6.1

               Federacja z grupami AD – 6.2

OpenLDAP

               Konfiguracja federacji – 6.3

               Federacja z grupami AD – 6.4

6.1.  Konfiguracja keycloak, AD (Microsoft) Konfiguracja federacji

6.1.1.      Logujemy się do PASK danymi lokalnego administratora, rozwijamy menu w prawym górnym rogu klikając na okrągłą ikonkę postaci -> „Konta użytkowników” ( otworzy się nowa karta )

6.1.2.      Przechodzimy w menu po lewej stronie do zakładki „Federacja użytkowników” -> „Dodaj dostawcę” ( kafelek po prawej stronie UWAGA! Oba kafelki mają te same nazwy )

6.1.3.      Uzupełniamy według tabelki poniżej, pola nie zawarte w tabelce pozostawiamy bez zmian
UWAGA pola „Atrybut LDAP nazwy użytkownika”  oraz „Atrybut RDN LDAP”  są domyślnie uzupełnione wartościami, niestety w wyniku błędu w WebGUI należy usunąć te wartości i jeszcze raz ręcznie wpisać aby zostały poprawnie zapisane

UWAGA 2 jeśli OU w polu „DN użytkowników” jest dokładnie tam gdzie są użytkownicy nie musimy robić nic. Jeśli natomiast OU jest w drzewie AD wyżej niż znajduje się OU z użytkownikami należy edytować opcje Zakres wyszukiwania ( kilka pozycji niżej) na „poddrzewo” aby pozwolić keycloakowi wyszukiwać rekurencyjnie danych

UWAGA 3  jeśli OU jest zapięte bardzo wysoko istnieje ryzyko wyszukania i zmapowania przez keycloak danych w innych poddrzewach których nie chcielibyśmy zmapować. Dodatkowo wysokie zapięcie OU ma wpływ na wydajność rozwiązania z racji potrzeby przeszukiwania większej ilości danych za każdym razem

6.1.4.      Testujemy połączenie przyciskami kolejno „Testuj połączenie” oraz „Testowanie autentykacji”, jeśli oba testy zakończą się powodzeniem klikamy „Zapisz” na dole strony

6.1.5.      Następnie wchodzimy w zapisanego właśnie dostawcę i wykonujemy pierwszą synchronizację, klikając w prawym górnym rogu listę rozwijaną „Akcja” i wybierając pozycję „Synchronizuj wszystkich użytkowników”

6.1.6.      Po poprawnej synchronizacji sprawdzamy czy użytkownicy zostali poprawnie zsynchronizowani potwierdzając obecność wpisów w zakładce „Użytkownicy” w menu po lewej stronie i wpisując * (słownie: gwiazdka) w pole wyszukiwania i klikamy enter. Pola adresów e-mail będą miały obok siebie czerwony znaczek, jest to pożądane zachowanie.

6.2.  Konfiguracja keycloak, AD (Microsoft) Federacja z grupami AD

6.2.1.      Logujemy się do PASK danymi lokalnego administratora, rozwijamy menu w prawym górnym rogu klikając na okrągłą ikonkę postaci -> „Konta użytkowników” ( otworzy się nowa karta )

6.2.2.      Przechodzimy w menu po lewej stronie do zakładki „Federacja użytkowników” -> „Dodaj dostawcę” ( kafelek po prawej stronie UWAGA! Oba kafelki mają te same nazwy )

6.2.3.      Uzupełniamy według tabelki poniżej, pola nie zawarte w tabelce pozostawiamy bez zmian
UWAGA pola „Atrybut LDAP nazwy użytkownika”  oraz „Atrybut RDN LDAP”  są domyślnie uzupełnione wartościami, niestety w wyniku błędu w WebGUI należy usunąć te wartości i jeszcze raz ręcznie wpisać aby zostały poprawnie zapisane

UWAGA 2 jeśli OU w polu „DN użytkowników” jest dokładnie tam gdzie są użytkownicy nie musimy robić nic. Jeśli natomiast OU jest w drzewie AD wyżej niż znajduje się OU z użytkownikami należy edytować opcje Zakres wyszukiwania ( kilka pozycji niżej) na „poddrzewo” aby pozwolić keycloakowi wyszukiwać rekurencyjnie danych

UWAGA 3  jeśli OU jest zapięte bardzo wysoko istnieje ryzyko wyszukania i zmapowania przez keycloak danych w innych poddrzewach których nie chcielibyśmy zmapować. Dodatkowo wysokie zapięcie OU ma wpływ na wydajność rozwiązania z racji potrzeby przeszukiwania większej ilości danych za każdym razem

6.2.4.      Testujemy połączenie przyciskami kolejno „Testuj połączenie” oraz „Testowanie autentykacji”, jeśli oba testy zakończą się powodzeniem klikamy „Zapisz” na dole strony

6.2.5.      Następnie wchodzimy w zapisanego właśnie dostawcę i wykonujemy pierwszą synchronizację, klikając w prawym górnym rogu listę rozwijaną „Akcja” i wybierając pozycję „Synchronizuj wszystkich użytkowników”

6.2.6.      Po poprawnej synchronizacji sprawdzamy czy użytkownicy zostali poprawnie zsynchronizowani potwierdzając obecność wpisów w zakładce „Użytkownicy” w menu po lewej stronie i wpisując * (słownie: gwiazdka) w pole wyszukiwania i klikamy enter. Pola adresów e-mail będą miały obok siebie czerwony znaczek, jest to pożądane zachowanie.

6.2.6.1.      Konfiguracja mapera grup w keycloak. Logujemy się do PASK i przechodzimy do „Konta użytkowników” ( otworzy się nowa karta )

6.2.6.2.      Przechodzimy w menu po lewej stronie do zakładki „Federacja użytkowników” -> klikamy w federację którą wcześniej utworzyliśmy -> „Mapery” w zakładkach u góry -> „Dodaj mapowanie”

6.2.6.3.      Uzupełniamy według tabelki poniżej, pola nie zawarte w tabelce pozostawiamy bez zmian

6.2.6.4.    Po wypełnieniu i zapisaniu formularza należy w prawym górnym rogu kliknąć w listę rozwijaną „Akcja” i wybrać pozycję „Synchronizuj grupy LDAP z Keycloak”
UWAGA! Kliknięcie innego przycisku może spowodować nadpisanie pustych grup do aktualnego AD

6.2.6.5.    Po zmapowaniu grup należy sprawdzić poprawność mapowania. W tym celu przechodzimy w menu po lewej stronie do zakładki „Grupy”. Jeśli grupy w AD mają inne nazwy niż te które już znajdują się w keycloak, należy do odpowiednich grup przypisać mapowania oryginalnych. Na przykład w keycloak grupa "PASK ADMIN" posiada role administracyjne a jej odpowiednikiem zmapowanym z AD jest grupa o nazwie "Administrators PASK" to po zmapowaniu grupy z AD należy skopiować uprawnienia z grupy "PASK ADMIN" do grupy "Administrators PASK"

6.3.  Konfiguracja keycloak, OpenLDAP Konfiguracja federacji

6.3.1.      Logujemy się do PASK danymi lokalnego administratora, rozwijamy menu w prawym górnym rogu klikając na okrągłą ikonkę postaci -> „Konta użytkowników” ( otworzy się nowa karta )

6.3.2.      Przechodzimy w menu po lewej stronie do zakładki „Federacja użytkowników” -> „Dodaj dostawcę” ( kafelek po prawej stronie UWAGA! Oba kafelki mają te same nazwy )

6.3.3.      Uzupełniamy według tabelki poniżej, pola nie zawarte w tabelce pozostawiamy bez zmian
UWAGA pola „Atrybut LDAP nazwy użytkownika”  oraz „Atrybut RDN LDAP”  są domyślnie uzupełnione wartościami, niestety w wyniku błędu w WebGUI należy usunąć te wartości i jeszcze raz ręcznie wpisać aby zostały poprawnie zapisane

UWAGA 2 jeśli OU w polu „DN użytkowników” jest dokładnie tam gdzie są użytkownicy nie musimy robić nic. Jeśli natomiast OU jest w drzewie AD wyżej niż znajduje się OU z użytkownikami należy edytować opcje Zakres wyszukiwania ( kilka pozycji niżej) na „poddrzewo” aby pozwolić keycloakowi wyszukiwać rekurencyjnie danych

UWAGA 3  jeśli OU jest zapięte bardzo wysoko istnieje ryzyko wyszukania i zmapowania przez keycloak danych w innych poddrzewach których nie chcielibyśmy zmapować. Dodatkowo wysokie zapięcie OU ma wpływ na wydajność rozwiązania z racji potrzeby przeszukiwania większej ilości danych za każdym razem

6.3.4.      Testujemy połączenie przyciskami kolejno „Testuj połączenie” oraz „Testowanie autentykacji”, jeśli oba testy zakończą się powodzeniem klikamy „Zapisz” na dole strony

6.3.5.      W przypadku synchronizacji z naszego rozwiązania LDAP ( dołączonego do PASK ) należy dodatkowo wejść w zakładkę "mappery" -> "first name" i podmienić "LDAP Attribute" na wartość "givenName"

6.3.6.      Następnie wchodzimy w zapisanego właśnie dostawcę i wykonujemy pierwszą synchronizację, klikając w prawym górnym rogu listę rozwijaną „Akcja” i wybierając pozycję „Synchronizuj wszystkich użytkowników”

6.3.7.      Po poprawnej synchronizacji sprawdzamy czy użytkownicy zostali poprawnie zsynchronizowani potwierdzając obecność wpisów w zakładce „Użytkownicy” w menu po lewej stronie i wpisując * (słownie: gwiazdka) w pole wyszukiwania i klikamy enter. Pola adresów e-mail będą miały obok siebie czerwony znaczek, jest to pożądane zachowanie.

6.4.  Konfiguracja keycloak, OpenLDAP Mapowanie poprzez grupy AD

6.4.1.      Logujemy się do PASK danymi lokalnego administratora, rozwijamy menu w prawym górnym rogu klikając na okrągłą ikonkę postaci -> „Konta użytkowników” ( otworzy się nowa karta )

6.4.2.      Przechodzimy w menu po lewej stronie do zakładki „Federacja użytkowników” -> „Dodaj dostawcę” ( kafelek po prawej stronie UWAGA! Oba kafelki mają te same nazwy )

6.4.3.      Uzupełniamy według tabelki poniżej, pola nie zawarte w tabelce pozostawiamy bez zmian
UWAGA pola „Atrybut LDAP nazwy użytkownika”  oraz „Atrybut RDN LDAP”  są domyślnie uzupełnione wartościami, niestety w wyniku błędu w WebGUI należy usunąć te wartości i jeszcze raz ręcznie wpisać aby zostały poprawnie zapisane

UWAGA 2 jeśli OU w polu „DN użytkowników” jest dokładnie tam gdzie są użytkownicy nie musimy robić nic. Jeśli natomiast OU jest w drzewie AD wyżej niż znajduje się OU z użytkownikami należy edytować opcje Zakres wyszukiwania ( kilka pozycji niżej) na „poddrzewo” aby pozwolić keycloakowi wyszukiwać rekurencyjnie danych

UWAGA 3  jeśli OU jest zapięte bardzo wysoko istnieje ryzyko wyszukania i zmapowania przez keycloak danych w innych poddrzewach których nie chcielibyśmy zmapować. Dodatkowo wysokie zapięcie OU ma wpływ na wydajność rozwiązania z racji potrzeby przeszukiwania większej ilości danych za każdym razem

6.4.4.      Testujemy połączenie przyciskami kolejno „Testuj połączenie” oraz „Testowanie autentykacji”, jeśli oba testy zakończą się powodzeniem klikamy „Zapisz” na dole strony

6.4.5.      W przypadku synchronizacji z naszego rozwiązania LDAP ( dołączonego do PASK ) należy dodatkowo wejść w zakładkę "mappery" -> "first name" i podmienić "LDAP Attribute" na wartość "givenName"

6.4.6.      Następnie wchodzimy w zapisanego właśnie dostawcę i wykonujemy pierwszą synchronizację, klikając w prawym górnym rogu listę rozwijaną „Akcja” i wybierając pozycję „Synchronizuj wszystkich użytkowników”

6.4.7.      Po poprawnej synchronizacji sprawdzamy czy użytkownicy zostali poprawnie zsynchronizowani potwierdzając obecność wpisów w zakładce „Użytkownicy” w menu po lewej stronie i wpisując * (słownie: gwiazdka) w pole wyszukiwania i klikamy enter. Pola adresów e-mail będą miały obok siebie czerwony znaczek, jest to pożądane zachowanie.

6.4.7.1.    Konfiguracja mapera grup w keycloak. Logujemy się do PASK i przechodzimy do „Konta użytkowników” ( otworzy się nowa karta )

6.4.7.2.    Przechodzimy w menu po lewej stronie do zakładki „Federacja użytkowników” -> klikamy w federację którą wcześniej utworzyliśmy -> „Mapery” w zakładkach u góry -> „Dodaj mapowanie”

6.4.7.3.    Uzupełniamy według tabelki poniżej, pola nie zawarte w tabelce pozostawiamy bez zmian

6.4.7.4.     Po wypełnieniu i zapisaniu formularza należy w prawym górnym rogu kliknąć w listę rozwijaną „Akcja” i wybrać pozycję „Synchronizuj grupy LDAP z Keycloak”
UWAGA! Kliknięcie innego przycisku może spowodować nadpisanie pustych grup do aktualnego AD

6.4.7.5.     Po zmapowaniu grup należy sprawdzić poprawność mapowania. W tym celu przechodzimy w menu po lewej stronie do zakładki „Grupy”. Jeśli grupy w AD mają inne nazwy niż te które już znajdują się w keycloak, należy do odpowiednich grup przypisać mapowania oryginalnych. Na przykład w keycloak grupa "PASK ADMIN" posiada role administracyjne a jej odpowiednikiem zmapowanym z AD jest grupa o nazwie "Administrators PASK" to po zmapowaniu grupy z AD należy skopiować uprawnienia z grupy "PASK ADMIN" do grupy "Administrators PASK"