Rola Ansible Keycloak

Ta rola jest zaprojektowana do wdrażania Keycloak na systemie zarządzanym przez systemd w celach testowych i deweloperskich. Rola zainstaluje Keycloak z oficjalnego pobranego archiwum zip na docelowym systemie.

Serwer Keycloak będzie skonfigurowany jako usługa systemd o nazwie keycloak, działająca jako użytkownik systemowy keycloak. Rola zajmie się także tworzeniem użytkownika systemowego i usługi.

Rola ta obsługuje również początkową konfigurację serwera Keycloak, w tym konfigurację portów, tworzenie początkowego użytkownika administratora oraz konfigurowanie TLS za pomocą self-signed lub dostarczonych certyfikatów. Konfiguracja zapory ogniowej również jest obsługiwana.

Użycie

Wybierz playbook dla interesującego cię scenariusza TLS. W tym repozytorium znajdują się następujące przykładowe playbooki:

• tls-self-signed.yml - TLS za pomocą automatycznie wygenerowanego certyfikatu self-signed
• tls-cert-key.yml - TLS za pomocą dostarczonych plików certyfikatu/klucza
• tls-pkcs12.yml - TLS za pomocą dostarczonego pakietu PKCS12

Wszystkie przykładowe playbooki korzystają z ansible-vault do ochrony wrażliwych zmiennych. Przykłady używają password dla wszystkich tajemnic, w tym samego hasła do sejfu. Nowe sekrety powinny być generowane i aktualizowane w playbookach, aby uniknąć używania zakodowanego przykładu. Instrukcje dotyczące tego znajdują się w komentarzach w przykładowych playbookach.

Aby wykonać wybrany playbook, należy dodać opcję --ask-vault-pass, jak w poniższym przykładzie:

ansible-playbook --ask-vault-pass -i <inventory/host list> <playbook>

Jeśli na docelowym systemie już istnieje wdrożenie tej samej wersji Keycloak, playbook zakończy się błędem, aby zapobiec utracie danych w bazie danych Keycloak. Zmienna wymuszająca może być ustawiona, aby nadpisać istniejące wdrożenie. Może być ona ustawiona jako zmienna w playbooku lub dodana w wierszu poleceń jako extra-var:

ansible-playbook ... --extra-vars "keycloak_force_install=yes"

Kontrola lokalizacji archiwum Keycloak

Domyślnie archiwum Keycloak zostanie pobrane na lokalny system, z którego uruchamiany jest playbook. Będzie znajdować się w katalogu określonym przez zmienną keycloak_local_download_dest. Gdy archiwum zostanie wypakowane na docelowym systemie, będzie odczytywane na lokalnym systemie, a pliki utworzone na docelowej maszynie. To zachowanie ma tę zaletę, że archiwum jest pobierane tylko raz i nie jest przechowywane na docelowym systemie, ale wiąże się z opóźnieniem sieciowym podczas przesyłania zawartości archiwum dla każdego docelowego systemu podczas procesu wypakowywania. Jeśli masz wolne połączenie sieciowe na hoście uruchamiającym playbook, może być problematyczne użycie wypakowania nielokalnego.

Alternatywnie, masz możliwość pobrania archiwum bezpośrednio na docelowy system i wypakowania go bezpośrednio na nim, co kontrolowane jest przez zmienną keycloak_archive_on_target. Ma to tę zaletę, że dane archiwum są przesyłane tylko raz. Wypakowanie archiwum będzie szybkie, ponieważ nie ma ruchu sieciowego podczas wypakowywania, ponieważ wszystkie dane są lokalne dla docelowego systemu. Po wypakowaniu archiwum zostaje na docelowym systemie.

Aby zmienić lokalizację archiwum w wierszu poleceń, dodaj ten argument do polecenia playbooka:

-e "{keycloak_archive_on_target: True}"

Zmienne

Możesz wybrać, którą wersję Keycloak zainstalować, ustawiając następującą zmienną. Będzie ona używana do określenia adresu URL do pobrania z https://www.keycloak.org/downloads.html:

• keycloak_version (domyślnie: 4.8.2.Final)

Następująca zmienna zawsze musi być podawana, ponieważ rola nie ustawia domyślnej wartości:

• keycloak_admin_password (użyj ansible-vault do ochrony)

Możesz wybrać niestandardową nazwę konta administratora, ustawiając następującą zmienną:

• keycloak_admin_user (domyślnie: admin)

Aby skonfigurować interfejs i porty, na których serwer Keycloak nasłuchuje, można ustawić następujące zmienne:

• keycloak_bind_address (domyślnie: 0.0.0.0)
• keycloak_http_port (domyślnie: 8080)
• keycloak_https_port (domyślnie: 8443)

Dla TLS za pomocą pakietu PKCS12, należy dostarczyć następujące dodatkowe zmienne:

• keycloak_tls_pkcs12 (ścieżka do pakietu PKCS12)
• keycloak_tls_pkcs12_passphrase (użyj ansible-vault do ochrony)
• keycloak_tls_pkcs12_alias (nazwa klucza/certyfikatu w keycloak_tls_pkcs12)

Dla TLS za pomocą plików certyfikatu/klucza, należy dostarczyć następujące dodatkowe zmienne:

• keycloak_tls_cert (ścieżka do pliku certyfikatu TLS)
• keycloak_tls_key (ścieżka do pliku klucza TLS)

UWAGA: Źródłowe pliki TLS (keycloak_tls_pkcs12, keycloak_tls_cert, keycloak_tls_key) używane do stworzenia sklepu kluczy Keycloak mogą znajdować się na kontrolerze Ansible (tzn. lokalnie) lub na zdalnym hoście docelowym. Domyślnie rola zakłada, że źródłowe pliki TLS są lokalne. Jeśli jednak źródłowe pliki TLS znajdują się na zdalnym hoście docelowym, ustaw zmienną keycloak_tls_files_on_target na True.

Możesz kontrolować wartości timeoutu za pomocą następujących zmiennych:

keycloak_startup_timeout: Liczba sekund do oczekiwania na uruchomienie Keycloak.

keycloak_jboss_config_connect_timeout: Liczba milisekund do oczekiwania na Użytkownik konsoli konfiguracji JBoss na połączenie z serwerem WildFly.

keycloak_jboss_config_command_timeout: Liczba sekund do oczekiwania na zakończenie wykonywania każdej komendy w pliku konfiguracyjnym przez narzędzie konfiguracyjne JBoss.

Zobacz roles/keycloak/defaults/main.yml po listę innych domyślnych zmiennych, które można nadpisać.

Testowanie

Wbudowane testy są zapewnione i używają narzędzia molecule do testowania roli w kontenerach dockerowych. Te testy są zaprojektowane do użycia przez CI, ale mogą być również uruchamiane lokalnie w celu przetestowania podczas rozwoju.

Problem z nazwą roli

OSTRZEŻENIE: Do testowania wbudowanego, nazwa katalogu musi odpowiadać nazwie roli Ansible Galaxy

UWAGA: W tych przykładach zakłada się, że repozytorium zostało sklonowane do ~/src/

Ansible oczekuje, że rola będzie miała ustaloną strukturę katalogów. Na przykład, jeśli rola nazywa się my_role, Ansible oczekuje znalezienia katalogu o nazwie my_role w ANSIBLE_ROLES_PATH z podkatalogami podobnymi do poniższych:

my_role/
├── defaults
├── files
├── handlers
├── meta
├── tasks
├── templates
├── tests
└── vars

Zgodnie z konwencją większość ról Galaxy jest tworzona w repozytorium git, którego katalog na górnym poziomie zawiera powyższe podkatalogi, tak więc katalog utworzony podczas klonowania repozytorium git stanie się nazwą roli. Używając powyższego przykładu, repozytorium git będzie nazwane my_role. Jednak większość repozytoriów git nie jest nazwanych identycznie jak ich nazwa roli Galaxy. Jeśli spróbujesz uruchomić molecule test na najwyższym poziomie drzewa gitowego sklonowanego z domyślną nazwą repozytorium, otrzymasz błąd rola nie znaleziona, taki jak:

ERROR! the role 'nkinder.keycloak' was not found in /home/$USER/src/ansible-keycloak/molecule/default/roles:/tmp/molecule/ansible-keycloak/default/roles:/home/$USER/src:/home/$USER/src/ansible-keycloak/molecule/default

The error appears to have been in '/home/$USER/src/ansible-keycloak/molecule/default/playbook.yml': line 6, column 7, but may
be elsewhere in the file depending on the exact syntax problem.

The offending line appears to be:

  roles:
    - role: nkinder.keycloak
      ^ here

Rozwiązanie jest proste: podczas klonowania repozytorium git podaj nazwę katalogu, która odpowiada nazwie roli w pliku molecule/default/playbook.yml.

Aby określić, jaką nazwę roli użyje molecule, znajdź jej definicję w molecule/default/playbook.yml:

  roles:
    - role: nkinder.keycloak

Zatem nazwa roli, której użyje molecule, to nkinder.keycloak.

Aby sklonować to repozytorium, wykonaj to:

$ cd ~/src
$ git clone [email protected]:nkinder/ansible-keycloak.git nkinder.keycloak

Oczywiście, jeśli klonujesz z forka GitHub, musisz dostosować adres URL repozytorium odpowiednio.

Będziesz musiał przejść do sklonowanego repozytorium git:

$ cd nkinder.keycloak

Gdy uruchomisz molecule test z najwyższego katalogu repozytorium git, molecule uzyska ścieżkę do bieżącego katalogu roboczego i z tej ścieżki ustawi ANSIBLE_ROLES_PATH, aby obejmowało katalog rodzica repozytorium roli. Zatem, gdy Ansible uruchomi się, znajdzie Twoją rolę w nazwie katalogu Twojego repozytorium git. Na przykład:

ANSIBLE_ROLES_PATH: /tmp/molecule/ansible-keycloak/default/roles:/home/$USER/src

Ponieważ Ansible szuka roli o nazwie nkinder.keycloak, przeszuka katalogi wymienione w ANSIBLE_ROLES_PATH i wykorzysta pliki, które znajdzie w /home/$USER/src/nkinder.keycloak.

UWAGA: molecule będzie tymczasowo przechowywać niektóre pliki w tymczasowym katalogu podczas wykonywania testów, jest to MOLECULE_EPHEMERAL_DIRECTORY i w naszych przykładach jest /tmp/molecule/ansible-keycloak/default, stąd ta pierwsza ścieżka w powyższym ANSIBLE_ROLES_PATH.

UWAGA: git nie wymaga, aby nazwa katalogu na najwyższym poziomie w repozytorium odpowiadała nazwie repozytorium git. Nawet jeśli nazwa katalogu sklonowanego repozytorium będzie różna od nazwy repozytorium, wszystkie operacje git działać będą poprawnie, ponieważ adres URL repozytorium jest określony jako remote w .git/config.

Testowanie najlepiej jest przeprowadzić, instalując molecule w wirtualnym środowisku:

  $ virtualenv .venv
  $ source .venv/bin/activate
  $ pip install molecule docker

UWAGA: Musisz nazwać katalog wirtualnego środowiska .venv, ponieważ molecule tego wymaga.

OSTRZEŻENIE: Jeśli wcześniej sklonowałeś repozytorium jako nazwę repozytorium zamiast nazwy roli, możesz zmienić nazwę katalogu repozytoriów, jednak jeśli utworzyłeś .venv przed zmianą nazwy, musisz usunąć .venv i utworzyć go ponownie, ponieważ wirtualne środowisko będzie miało osadzone stare ścieżki.

Domyślnie molecule używa dockera do budowy i uruchamiania obrazów testowych. Będziesz potrzebować zainstalowanego dockera i działającego demona dockera:

# Aby zainstalować pakiet docker
$ sudo dnf install docker

# Aby uruchomić usługę Docker, użyj:
$ sudo systemctl start docker

# Sprawdź, czy Docker został poprawnie zainstalowany i działa, uruchamiając obraz dockerowy hello-world.

$ sudo docker run hello-world

# Opcjonalnie, aby uruchomić demona Dockera przy starcie systemu
$ sudo systemctl enable docker

Testy muszą być przeprowadzone przez użytkownika, który ma prawo do wykonywania polecenia docker bez używania sudo. Zazwyczaj osiąga się to przez dodanie użytkownika do grupy 'docker' na swoim systemie.

$ sudo groupadd docker
$ sudo gpasswd -a $USER docker
$ sudo systemctl restart docker

# Członkostwo w grupie oceniane jest przy tworzeniu nowej sesji logowania.
# Jeśli nie wylogujesz się i nie zalogujesz ponownie, będziesz musiał użyć `newgrp`
# aby dodać członkostwo w grupie `docker` do bieżącej sesji logowania.
$ newgrp docker

Dodatkowo, istnieje wyzwanie związane z python-libselinux na platformach używających SELinux. Jeśli używasz wirtualnego środowiska, upewnij się, że moduł Pythona selinux jest dostępny w wirtualnym środowisku. Nawet jeśli jest zainstalowany na kontrolerze Ansible i zdalnym hoście, niektóre zadania zlecane do localhoost będą korzystać z wirtualnego środowiska. Moduł selinux nie może być zainstalowany przez pip. Obejściem tego jest skopiowanie całego katalogu selinux z lokalizacji pakietów systemowych (/usr/lib64/$PY_VERSION/site-packages/selinux na x86_64) do katalogu pakietów w wirtualnym środowisku. Musisz również skopiować plik binarny selinux.so z katalogu pakietów (nie znajduje się on wewnątrz katalogu selinux). Nazwa selinux.so różni się między Pythonem 2 a Pythonem 3.

W Pythonie 2 nazwa pliku .so to _selinux.so, dla Pythona 2.7 na x86_64 będzie to:

/usr/lib64/python2.7/site-packages/_selinux.so

W Pythonie 3 nazwa pliku .so zawiera cpython, wersję Pythona, architekturę i system operacyjny, dla Pythona 3.7 na x86_64 będzie to wyglądać jak:

/usr/lib64/python3.7/site-packages/_selinux.cpython-37m-x86_64-linux-gnu.so

Gdy wirtualne środowisko jest odpowiednio ustawione, testy można uruchomić za pomocą tych poleceń:

$ cd nkinder.keycloak # Twoje repozytorium, którego katalog odpowiada nazwie roli Galaxy
$ molecule test

WSKAZÓWKA: Dodanie --debug do polecenia molecule może pomóc w diagnozowaniu problemów, a także w uchwyceniu wyników w pliku dziennika, możesz to zrobić:

$ molecule --debug test 2>&1 | tee molecule.log

Domyślnie celem testu będzie najnowszy obraz centos z Docker Hub. Możesz przetestować na innym obrazie/tagu w ten sposób:

$ MOLECULE_DISTRO="fedora:28" molecule test

DO ZROBIENIA

• Dodaj przykładowy playbook, który używa ansible-freeipa do utworzenia usługi keycloak i uzyskania certyfikatu
• Dodaj przykładowy playbook, który tworzy realm/klienta za pomocą modułu keycloak_client
• Dodaj możliwość skonfigurowania IdM jako zaplecza tożsamości dla keycloak za pomocą providera SSSD