Shibboleth IdP wersja 5, instalacja w środowisku dockerowym
Opis
W tym podejściu przygotowywane są trzy środowiska dockerowe:
- baza mysql - zawiera bazę i tablice używane przez Shibboleth v. 5
- baza LDAP - zawiera prostą bazę danych użytkowników w celu zobrazowania procesu uwierzytelniania i dostarczania atrybutów w Shibboleth IdP; docelowo instalacja IdP może korzystać z dowolnej bazy danych użytkowników
- środowisko działania Shibboleth IdP: jetty jako serwer WWW i aplikacja Shibboleth IdP
Wymagania systemowe
- zainstalowany silnik dockerowy https://docs.docker.com/engine/install/
- zainstalowany docker compose https://docs.docker.com/compose/install/
Paczka instalacyjna i uruchomieniowa serwera IdP
Pobranie aktualnej paczki pionier-id-idp.tar.gz
Paczka jest dostępna pod adresem https://box.pionier.net.pl/f/9341d70f47c04d3b9ed1/?dl=1
Rozpakowanie paczki
np. w katalogu /opt
cd /opt tar xfv pionier-id-idp.tar.gz cd /opt/PIONIER.Id-IdP
Opis zawartości paczki
- w podkatalogu jetty/credentials/ jest umieszczony plik jetty.p12 zawierający testowy certyfikat serwera, wystawiony na nazwę aai.example.pl przez niezaufane CA; w tym katalogu należy umieścić plik jetty.p12 zawierający certyfikat przeznaczony dla instalowanego serwera (wskazówki umieszczono poniżej)
- trzy pliki docker-compose-init.yaml, docker-compose-upgrade.yaml, docker-compose.yaml służą uruchamianiu środowiska w trybie inicjalizacji (docker-compose-init.yaml), upgrate'u (docker-compose-upgrade.yaml) oraz gotowej usługi (docker-compose.yaml)
- w pliku docker-compose.yaml jest zdefiniowany start poszczególnych usług, definicja współdzielonych wolumnenów oraz definicja zmiennych środowiskowych (sekcja environment):
- usługa mariadb - start serwera mysql, tworzona jest baza shibboleth_pionier i potrzebne tablice
- usługa openldap - start serwera openLDAP - serwer dostępny jest na portach 1389 i 1636, korzysta ze schematów znajdujących się w podkatalogu ldap-schemas, inicjowana jest zawartość bazy zgodnie z plikiem w podkatalogu ldifs
- idp - start serwera jetty oraz aplikacji Shibboleth IdP
- wspólne wolumeny są zdefiniowane dla usług mariadb oraz openldap i gwarantują trwałość baz danych
- dla usługi idp w atrybucie environment są podawane ustawienia:
- - JETTY_IP_ADDR to adres IP serwera IdP
- - JETTY_HTTP to port nasłuchu http, domyślnie 8081
- - JETTY_HTTPS to port nasłuchu https, domyślnie 9444
- - JETTY_PASS to hasło dla pliku jetty/credentials/jetty.p12
Przygotowanie obrazów
Po dostosowaniu zawartości plików wykonujemy tworzymy obraz Shibboleth IdP:
cd /opt/PIONIER.Id-IdP docker compose build
Po poprawnym zakończeniu sprawdzamy za pomocą polecenia:
docker images
że istnieje obraz pionier-idp-5
Zainicjowanie instalacji Shibboleth IdP
Przeprowadzamy instalację inicjującą. Na głównej maszynie zostanie utworzony katalog /opt/shibboleth-idp-pionier, w którym będzie umieszczona instalowana wersja Shibboleth IdP (plik uruchomieniowy oraz cała konfiguracja). Instalacja odbywa się w trybie interakcyjnym, należy odowiedzieć na zadane pytania lub potwierdzić wybór przez Enter. Uruchamiamy:
docker compose -f ./docker-compose-init.yaml run idp-init
Interakcja wygląda następująco:
- Installation Directory
- [/opt/shibboleth-idp] ?
- Enter
- Host Name
- [973fd3996aaa] ?
- Podajemy pełną nazwę hosta, np. idp.uczelnia.pl
- SAML EntityID
- [ https://idp.uczelnia.pl/idp/shibboleth ] ?
- Enter
Attribute Scope: [uczelnia.pl] ?
- Enter
Następuje instalacja pluginów, na którą należy wyrazić zgodę odpowiadając dwukrotnie Y
Po zakończeniu instalacji w katalogu /opt/shibboleth-idp-pionier znajduje się instalacja i wstępna konfiguracja Shibboleth IdP. Proces dockera związany z inicjalizacją Shibboleth IdP zostaje zakończony, ale zaleca się wykonanie polecenia:
docker compose -f ./docker-compose-init.yaml down --remove-orphans
Ponowna inicjalizacja Shibboleth IdP
Jeśli „coś poszło nie tak” i potrzebna jest ponowna inicjalizacja środowiska Shibboleth IdP:
- zatrzymujemy usługę
cd /opt/PIONIER.Id-IdP docker compose down
- usuwamy zawartość katalogu /opt/shibboleth-idp-pionier
- jeśli jest potrzebne wyczyszczenie bazy mysql czy openLDAP
- - sprawdzamy, jakie są nazwy wolumenów i wykonujemy:
docker volume rm nazwa_wolumenu
- przechodzimy przez fazę inicjalizacji usługi
Uruchomienie Shibboleth IdP
Aby uruchomić usługę serwera IdP należy wykonać polecenie:
docker compose up -d
Przy pierwszym uruchomieniu zostanie pobrany obraz mariadb oraz openldap, zostaną utworzone wolumeny wspólne i następnie jest uruchamiany obraz pionierid-id, czyli startowany jest serwer webowy jetty i w ramach tego serwera jest udostępniana aplikacja Shibboleth IdP.
W pliku docker-compose.yaml odpowiedzialnym za przebieg uruchamiania usługi jest umieszczony wpis:
restart: always
co oznacza, że system dockerowy będzie samodzielnie startował usługę - nie są potrzebne żadne dodatkowe działania, by zapewnić startowanie po reboocie maszyny podstawowej.
Aktualizacja konfiguracji Shibboleth IdP
Po zainicjowaniu usługi Shiiboleth IdP w katalogu w katalogu /opt/shibboleth-idp-pionier serwera podstawowego znajdują się wszystkie pliki usługi IdP. Aktualizacja konfiguracji odbywa się poprzez modyfikację potrzebnych plików, np. /opt/shibboleth-idp-pionier/conf/idp.properties. Po dokonanych zmianach należy zrestartować obraz dockera:
docker compose restart
Zmiana certyfikatu serwera jetty
Zmiana certyfikatu polega na:
- przygotowaniu nowego pliku jetty.p12 zawierającego nowy certyfikat (wskazówki poniżej) i wgraniu go do katalogu jetty/credentials/
- modyfikacji zmiennej środowiskowej JETTY_PASS w pliku docker-compose.yaml, jeśli do utworzenia pliku p12 użyto innego hasła niż podane w tym pliku
- wykonanie restartu obrazu
docker compose restart
Udostępnienie usługi IdP na porcie 443
Po uruchomieniu dockera serwer jetty będący silnikiem webowym udostępniającym usługę IdP nasłuchuje na porcie https o numerze 9444. Ponieważ serwer jetty działa z uprawnieniami użytkownika jetty nie jest możliwe użycie portu 443 w konfiguracji dockera. Aby serwer był dostępny pod standardowym portem 443 należy wykonac odpowiednie przekierowanie w usłudze firewalla.
Przykładowym rozwiązaniem jest użycie polecenia iptables
iptables -t nat -A PREROUTING -p tcp -m tcp --dport 443 -d ip_serwera_głównego -j REDIRECT --to-ports 9444
Przygotowanie certyfikatu na potrzeby serwera jetty
Certyfikat serwera musi spełniać standardowe wymagania dot. certyfikatu serwera WWW. Konfiguracja jetty wymaga, by certyfikat był przygotowany w postaci p12.
Załóżmy, że w pliku serwer.pem mamy certyfikat serwera, w pliku serwer.key klucz prywatny, a w ca-chain.pem łańcuch certyfikatów pośrednich. Przygotowanie pliku p12 odbywa się następująco:
cat serwer.pem ca-chain.pem > jetty-chain.pem openssl pkcs12 -export -inkey test.key -in jetty-chain.pem -out jetty.p12
Plik ca-chain.pem zawiera certyfikaty pośrednie, czyli wszystkie poza certyfikatem nadrzędnego CA. Np. jeśli certyfikat serwera został wystawiony przez C=GR, O=Hellenic Academic and Research Institutions CA, CN=HARICA DV TLS RSA, to w pliku ca-chain.pem umieszczamy:
- certyfikat C=GR, O=Hellenic Academic and Research Institutions CA, CN=HARICA DV TLS RSA
- certyfikat C=GR, O=Hellenic Academic and Research Institutions CA, CN=HARICA TLS RSA Root CA 2021 (ponieważ on jest wystawcą powyższego certyfikatu), którego wystawcą jest C=GR, L=Athens, O=Hellenic Academic and Research Institutions Cert. Authority, CN=Hellenic Academic and Research Institutions RootCA 2015
Certyfikat C=GR, L=Athens, O=Hellenic Academic and Research Institutions Cert. Authority, CN=Hellenic Academic and Research Institutions RootCA 2015 nie jest już potrzebny, bo jest to certyfikat nadrzędnego CA, umieszczony w magazynach systemowych.
Polecenie pkcs12 będzie wymagało podania hasła klucza prywatnego (jeśli klucz jest zaszyfrowany) oraz hasła przeznaczonego do utworzenia pliku p12 i używanego następnie do odczytania tego pliku.
Aktualizacja wersji Shibboleth IdP
Przygotowany obraz dockerowy instaluje wersję 5.1.4 Shibboleth IdP.
Aktualizacja wersji Shibboleth IdP, po pojawieniu się nowej wersji, udostępnianej na stronie https://shibboleth.net/downloads/identity-provider/, odbywa się w następujący sposób:
- zamykamy usługę:
cd /opt/PIONIER.Id-IdP docker compose down
- dostosowujemy plik docker-compose-upgrade.yaml, by zmienna środowiskowa UPGRADE wskazywała nową wersję Shibboleth IdP, dostępną na stronie https://shibboleth.net/downloads/identity-provider/
- wykonujemy polecenie aktualizacji, w trakcie wykonywania pojawi się pytanie o katalog instalacyjny, należy nasisnąć Enter
docker compose -f ./docker-compose-upgrade.yaml run idp-upgrade
- uruchamiamy ponownie usługę IdP, dodając opcję czyszczenia kontenerów uruchamianych poprzednio
docker compose up -d --remove-orphans