Ansible Keycloak Rolle

Diese Rolle ist dafür gedacht, Keycloak auf einem systemd-verwalteten System für Test- und Entwicklungszwecke bereitzustellen. Die Rolle installiert Keycloak aus einem offiziell heruntergeladenen Keycloak-Zip-Archiv auf dem Zielsystem.

Der Keycloak-Server wird als systemd-Dienst mit dem Namen keycloak konfiguriert, der als Systembenutzer keycloak ausgeführt wird. Die Rolle kümmert sich um die Erstellung des Systembenutzers und des Dienstes.

Diese Rolle übernimmt auch einige der initialen Konfigurationen des Keycloak-Servers. Dazu gehört die Konfiguration der zu hörenden Ports, die Erstellung eines initialen Administratorbenutzers und die Konfiguration von TLS über selbstsignierte oder bereitgestellte Zertifikate. Auch die Firewall-Konfiguration wird behandelt.

Verwendung

Wählen Sie ein Playbook für das gewünschte TLS-Szenario aus. Die folgenden Beispiel-Playbooks sind in diesem Repository enthalten:

• tls-self-signed.yml - TLS über selbstsigniertes Zertifikat
• tls-cert-key.yml - TLS über bereitgestellte Zertifikat/Schlüssel-Dateien
• tls-pkcs12.yml - TLS über bereitgestelltes PKCS12-Bundle

Alle Beispiel-Playbooks verwenden ansible-vault für sicherheitsrelevante Variablen. Die Beispiele verwenden password für alle Geheimnisse, einschließlich des Vault-Passworts selbst. Neue Geheimnisse sollten generiert und in den Playbooks aktualisiert werden, um zu vermeiden, dass das fest codierte Beispiel verwendet wird. Anweisungen hierfür finden Sie in den Kommentaren in den Beispiel-Playbooks.

Um Ihr gewähltes Playbook auszuführen, stellen Sie sicher, dass Sie die Option --ask-vault-pass hinzufügen, wie in diesem Beispiel:

ansible-playbook --ask-vault-pass -i <Inventar/Host-Liste> <Playbook>

Wenn bereits eine Bereitstellung der gleichen Version von Keycloak auf dem Zielsystem vorhanden ist, wird das Playbook fehlschlagen, um zu verhindern, dass Daten in der Keycloak-Datenbank verloren gehen. Eine Variabel kann gesetzt werden, um die bestehende Installation zu überschreiben. Dies kann entweder als Variable im Playbook oder in der Kommandozeile als extra-var hinzugefügt werden:

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

Steuerung des Speicherorts des Keycloak-Archivs

Standardmäßig wird das Keycloak-Archiv auf das lokale System heruntergeladen, von dem aus das Playbook ausgeführt wird. Es wird im Verzeichnis gespeichert, das durch die Variable keycloak_local_download_dest angegeben ist. Wenn das Archiv auf dem Zielsystem entpackt wird, wird das Archiv auf dem lokalen System gelesen und die Dateien werden am Zielort erstellt. Dieses Verhalten hat den Vorteil, dass das Archiv nur einmal heruntergeladen wird und nicht auf dem Ziel gespeichert wird, jedoch verursacht es einen Netzwerkaufwand, da der Inhalt des Archivs während des Entpackens erneut für jedes Ziel übertragen wird. Wenn Sie eine langsame Upload-Netzwerkverbindung auf dem Host haben, der das Playbook ausführt, könnte das nicht-lokale Entpacken unhaltbar sein.

Alternativ können Sie das Archiv direkt auf das Ziel herunterladen und es dort entpacken; dies wird durch die Variable keycloak_archive_on_target gesteuert. Dies hat den Vorteil, dass die Archivdaten nur einmal übertragen werden. Das Entpacken des Archivs wird schnell sein, da es während des Entpackens keinen Netzwerkverkehr gibt, da alle Daten lokal am Ziel sind. Es bleibt jedoch das Archiv nach dem Entpacken auf dem Ziel.

Um den Speicherort des Archivs in der Kommandozeile zu ändern, fügen Sie dieses Argument Ihrem Playbook-Befehl hinzu:

-e "{keycloak_archive_on_target: True}"

Variablen

Sie können die Version von Keycloak auswählen, die Sie installieren möchten, indem Sie die folgende Variable festlegen. Diese wird verwendet, um die Download-URL von https://www.keycloak.org/downloads.html zu bestimmen:

• keycloak_version (Standard: 4.8.2.Final)

Die folgende Variable muss immer angegeben werden, da die Rolle keinen Standardwert festlegt:

• keycloak_admin_password (verwenden Sie ansible-vault zum Schutz)

Sie können einen anderen Admin-Benutzernamen auswählen, indem Sie die folgende Variable festlegen:

• keycloak_admin_user (Standard: admin)

Um die Schnittstelle und die Ports zu konfigurieren, auf denen der Keycloak-Server hört, können die folgenden Variablen festgelegt werden:

• keycloak_bind_address (Standard: 0.0.0.0)
• keycloak_http_port (Standard: 8080)
• keycloak_https_port (Standard: 8443)

Für TLS über ein PKCS12-Bundle müssen die folgenden zusätzlichen Variablen angegeben werden:

• keycloak_tls_pkcs12 (Pfad zum PKCS12-Bundle)
• keycloak_tls_pkcs12_passphrase (verwenden Sie ansible-vault zum Schutz)
• keycloak_tls_pkcs12_alias (Name von Schlüssel/Zertifikat in keycloak_tls_pkcs12)

Für TLS über Zertifikat/Schlüssel-Dateien müssen die folgenden zusätzlichen Variablen bereitgestellt werden:

• keycloak_tls_cert (Pfad zur TLS-Server-Zertifikat-Datei)
• keycloak_tls_key (Pfad zur TLS-Server-Schlüssel-Datei)

HINWEIS: Die Quell-TLS-Dateien (keycloak_tls_pkcs12, keycloak_tls_cert, keycloak_tls_key), die zur Erstellung des Keycloak-Keystores verwendet werden, können sich entweder auf dem Ansible-Controller (d.h. lokal) oder auf dem Remote-Zielhost befinden. Standardmäßig geht die Rolle davon aus, dass sich die Quell-TLS-Dateien lokal befinden. Wenn sich jedoch die Quell-TLS-Dateien auf dem Remote-Ziel befinden, setzen Sie die Variable keycloak_tls_files_on_target auf True.

Sie können die Timeout-Werte mit den folgenden Variablen steuern:

keycloak_startup_timeout: Anzahl der Sekunden, die gewartet werden soll, bis Keycloak gestartet ist.

keycloak_jboss_config_connect_timeout: Anzahl der Millisekunden, die gewartet werden soll, bis das jboss-Konfigurationstool eine Verbindung zum Wildfly-Server herstellt.

keycloak_jboss_config_command_timeout: Anzahl der Sekunden, die gewartet werden soll, bis das jboss-Konfigurationstool jeden Befehl, der in der Konfigurationsdatei ausgeführt wird, abgeschlossen hat.

Siehe roles/keycloak/defaults/main.yml für eine Liste weiterer Standardvariablen, die möglicherweise überschrieben werden sollen.

Tests

In-tree-Tests werden bereitgestellt, die Molecule verwenden, um die Rolle gegen Docker-Container zu testen. Diese Tests sind für die CI gedacht, können jedoch auch lokal ausgeführt werden, um sie während der Entwicklung zu testen.

Problem mit der Rollenname

WARNUNG: Für das In-Tree-Testing muss der Verzeichnisname übereinstimmen mit dem Namen der Ansible Galaxy-Rolle

HINWEIS: In diesen Beispielen wird davon ausgegangen, dass das Repository in ~/src/ geklont wurde.

Ansible erwartet, dass eine Rolle eine vorgeschriebene Verzeichnisstruktur hat. Zum Beispiel, wenn die Rolle my_role heißt, wird Ansible erwarten, dass ein Verzeichnis mit dem Namen my_role im ANSIBLE_ROLES_PATH zu finden ist, mit Unterverzeichnissen, die ähnlich sind zu diesem:

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

Aus Gewohnheit werden die meisten Galaxy-Rollen in einem Git-Repository erstellt, dessen oberstes Verzeichnis die oben genannten Unterverzeichnisse enthält, sodass das Verzeichnis, das beim Klonen des Git-Repositories erstellt wird, den Rollennamen annimmt. Bei dem obigen Beispiel würde das Git-Repository my_role heißen. Die meisten Git-Repositories heißen jedoch nicht identisch wie ihr Galaxy-Rollenname. Wenn Sie versuchen, molecule test auf der obersten Ebene eines mit dem Standard-Repo-Namen geklonten Git-Tree auszuführen, erhalten Sie einen Rolle nicht gefunden Fehler wie folgt:

ERROR! die Rolle 'nkinder.keycloak' wurde nicht gefunden 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

Der Fehler scheint in '/home/$USER/src/ansible-keycloak/molecule/default/playbook.yml': Zeile 6, Spalte 7 aufgetreten zu sein, könnte jedoch je nach genauem Syntaxproblem auch anderswo in der Datei sein.

Die problematische Zeile scheint zu sein:

  roles:
    - role: nkinder.keycloak
      ^ hier

Die Lösung ist einfach: Geben Sie beim Klonen des Git-Repos einen Verzeichnisnamen an, der mit dem Rollennamen im molecule/default/playbook.yml übereinstimmt.

Um den Rollennamen zu bestimmen, den Molecule verwenden wird, finden Sie seine Definition in molecule/default/playbook.yml:

  roles:
    - role: nkinder.keycloak

Somit ist der Rollennamen, den Molecule verwenden wird, nkinder.keycloak.

Um dieses Repository zu klonen, tun Sie Folgendes:

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

Natürlich müssen Sie, wenn Sie von einem Fork bei Github klonen, die Repo-URL entsprechend anpassen.

Sie müssen in das geklonte Git-Repository wechseln:

$ cd nkinder.keycloak

Wenn Sie molecule test von der obersten Ebene des Git-Repos ausführen, erhält Molecule den aktuellen Arbeitsverzeichnispfad und findet von dort aus den übergeordneten Verzeichnispfad. Es wird dann den ANSIBLE_ROLES_PATH so einstellen, dass es das übergeordnete Verzeichnis des Rollen-Repos umfasst. Dadurch wird Ansible Ihre Rolle über den Verzeichnisnamen Ihres Git-Repos finden. Beispielsweise:

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

Da Ansible nach einer Rolle mit dem Namen nkinder.keycloak sucht, wird es in den Verzeichnissen suchen, die im ANSIBLE_ROLES_PATH aufgelistet sind, und die Dateien verwenden, die es in /home/$USER/src/nkinder.keycloak findet.

HINWEIS: Molecule wird einige Dateien in einem temporären Verzeichnis für die Dauer eines Testlaufs anlegen, dies ist das MOLECULE_EPHEMERAL_DIRECTORY und in unseren Beispielen ist es /tmp/molecule/ansible-keycloak/default, daher der erste Pfad im oben genannten ANSIBLE_ROLES_PATH.

HINWEIS: Git verlangt nicht, dass der Verzeichnisname des obersten Verzeichnisses im Repo mit dem Namen des Git-Repos übereinstimmt. Auch wenn der Verzeichnisname des geklonten Repos anders als der Repo-Name ist, funktionieren alle Git-Operationen wie erwartet, da die Repo-URL als remote in .git/config angegeben ist.

Tests sollten am besten durchgeführt werden, indem Sie Molecule in einer virtualenv installieren:

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

HINWEIS: Sie müssen das Verzeichnis der virtualenv .venv nennen, da Molecule dies erwartet.

WARNUNG: Wenn Sie das Repository bereits unter dem Repo-Namen anstelle des Rollennamens geklont haben, können Sie das Repo-Verzeichnis umbenennen. Wenn Sie jedoch .venv vor der Umbenennung erstellt haben, müssen Sie .venv entfernen und neu erstellen, da die virtualenv die alten Pfade eingebettet hat.

Standardmäßig verwendet Molecule Docker, um Test-Images zu erstellen und auszuführen. Sie müssen Docker installiert haben und der Docker-Daemon muss laufen:

# Um das Docker-Paket zu installieren
$ sudo dnf install docker

# Um den Docker-Dienst zu starten:
$ sudo systemctl start docker

# Überprüfen Sie, ob Docker korrekt installiert ist und läuft, indem Sie das Hello-World-Image von Docker ausführen.

$ sudo docker run hello-world

# Um den Docker-Daemon optional beim Booten zu starten
$ sudo systemctl enable docker

Es ist erforderlich, die Tests als Benutzer auszuführen, der berechtigt ist, den Befehl docker ohne Sudo auszuführen. Dies wird normalerweise erreicht, indem man seinen Benutzer zur 'docker'-Gruppe auf dem System hinzufügt.

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

# Die Gruppenmitgliedschaft wird ausgewertet, wenn Sie eine neue Anmeldesitzung erstellen.
# Es sei denn, Sie melden sich ab und wieder an, müssen Sie `newgrp`
# verwenden, um Ihre `docker`-Gruppenmitgliedschaft in der aktuellen Anmeldesitzung hinzuzufügen.
$ newgrp docker

Zusätzlich gibt es ein Problem mit python-libselinux auf Plattformen, die SELinux verwenden. Wenn Sie eine Virtualenv verwenden, müssen Sie sicherstellen, dass das SELinux-Python-Modul in der Virtualenv verfügbar ist. Auch wenn es auf Ihrem Ansible-Controller-Host und dem Zielhost installiert ist, verwenden einige der Aufgaben, die an den localhost delegiert werden, die Virtualenv. Das Selinux-Modul kann nicht über Pip installiert werden. Ein möglicher Lösungsansatz besteht darin, das gesamte selinux-Verzeichnis von Ihrem system-weiten Installationsort (z.B. /usr/lib64/$PY_VERSION/site-packages/selinux auf x86_64) in das site-packages-Verzeichnis der Virtualenv zu kopieren. Sie müssen auch die selinux.so-Binärdatei aus dem site-packages-Verzeichnis kopieren (sie befindet sich nicht im selinux-Verzeichnis). Der Name von selinux.so variiert zwischen Python2 und Python3.

In Python2 ist die Basisdatei von .so _selinux.so, für Python 2.7 auf x86_64 wäre dies diese .so:

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

In Python3 fügt der Basisname von .so cpython, die Python-Version, die Architektur und das Betriebssystem hinzu; für Python 3.7 auf x86_64 würde es wie folgt aussehen:

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

Sobald Ihre Virtualenv richtig eingerichtet ist, können die Tests mit diesen Befehlen ausgeführt werden:

$ cd nkinder.keycloak # Ihr Repo, dessen Verzeichnis mit dem Galaxy-Rollennamen übereinstimmt
$ molecule test

HINWEIS: Das Hinzufügen von --debug zu dem molecule-Befehl kann helfen, Probleme zu diagnostizieren sowie die Ausgabe in einer Protokolldatei zu erfassen; Sie möchten dies möglicherweise tun:

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

Standardmäßig wird das Testziel das neueste centos-Image von Docker Hub sein. Sie können gegen ein anderes Image/Tag testen, indem Sie Folgendes tun:

$ MOLECULE_DISTRO="fedora:28" molecule test

TODO

• Beispiel-Playbook hinzufügen, das ansible-freeipa verwendet, um den Keycloak-Dienst zu erstellen und das Zertifikat zu erhalten
• Beispiel-Playbook hinzufügen, das Realm/Client mit dem keycloak_client-Modul erstellt
• Möglichkeit hinzufügen, IdM als Identitäts-Backend für Keycloak über SSSD-Anbieter zu konfigurieren