Rôle Ansible Keycloak

Ce rôle est conçu pour déployer Keycloak sur un système géré par systemd à des fins de test et de développement. Le rôleinstallera Keycloak à partir d'une archive zip officielle téléchargée sur le système cible.

Le serveur Keycloak sera configuré comme un service systemd nommé keycloak, fonctionnant en tant qu'utilisateur système keycloak. Le rôle gérera la création de l'utilisateur système et du service.

Ce rôle s'occupe également de certaines configurations initiales du serveur Keycloak. Cela inclut la configuration des ports d'écoute, la création d'un utilisateur admin initial et la configuration TLS via des certificats auto-signés ou fournis. La configuration du pare-feu est également gérée.

Utilisation

Choisissez un playbook pour le scénario TLS qui vous intéresse. Les exemples de playbook suivants sont inclus dans ce dépôt :

• tls-self-signed.yml - TLS via un certificat auto-signé généré automatiquement
• tls-cert-key.yml - TLS via des fichiers certifs/clé fournis
• tls-pkcs12.yml - TLS via un bundle PKCS12 fourni

Tous les playbooks d'exemple utilisent ansible-vault pour les variables sensibles. Les exemples utilisent password pour tous les secrets, y compris le mot de passe de la vault elle-même. De nouveaux secrets doivent être générés et mis à jour dans les playbooks pour éviter d'utiliser l'exemple en dur. Les instructions pour cela se trouvent dans des commentaires dans les playbooks d'exemple.

Pour exécuter le playbook choisi, assurez-vous d'ajouter l'option --ask-vault-pass comme dans cet exemple :

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

Si un déploiement de la même version de Keycloak existe déjà sur le système cible, le playbook échouera pour éviter de perdre des données dans la base de données de Keycloak. Une variable de forçage peut être définie pour écraser le déploiement existant. Cela peut être défini comme une variable dans le playbook, ou ajouté en ligne de commande en tant qu'extra-var :

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

Contrôler l'emplacement de l'archive Keycloak

Par défaut, l'archive Keycloak sera téléchargée sur le système local depuis lequel le playbook est exécuté. Elle résidera dans le répertoire spécifié par la variable keycloak_local_download_dest. Lorsque l'archive est extraite sur le système cible, elle sera lue sur le système local et les fichiers seront créés sur la destination cible. Ce comportement a l'avantage de télécharger l'archive une seule fois et de ne pas la stocker sur la cible, mais cela entraîne un coût réseau de transfert à nouveau le contenu de l'archive pour chaque cible durant le processus d'extraction. Si vous avez une connexion réseau de téléchargement lente sur le système exécutant le playbook, l'extraction non locale peut être insoutenable.

Alternative, vous avez la possibilité de télécharger l'archive directement sur la cible et d'extraire l'archive sur celle-ci, cela est contrôlé par la variable keycloak_archive_on_target. Cela a l'avantage de transférer les données de l'archive une seule fois. L'extraction de l'archive sera rapide car il n'y a pas de trafic réseau durant l'extraction puisque toutes les données sont locales à la cible. Cependant, cela laissera l'archive sur la cible après extraction.

Pour changer l'emplacement de l'archive en ligne de commande, ajoutez cet argument à votre commande de playbook :

-e "{keycloak_archive_on_target: True}"

Variables

Vous pouvez choisir quelle version de Keycloak installer en définissant la variable suivante. Cela sera utilisé pour déterminer l'URL de téléchargement à partir de https://www.keycloak.org/downloads.html :

• keycloak_version (par défaut : 4.8.2.Final)

La variable suivante doit toujours être fournie, car le rôle ne codifie pas une valeur par défaut :

• keycloak_admin_password (utilisez ansible-vault pour protéger)

Vous pouvez choisir un nom d'utilisateur admin différent du nom par défaut en définissant la variable suivante :

• keycloak_admin_user (par défaut : admin)

Pour configurer l'interface et les ports sur lesquels le serveur Keycloak écoute, les variables suivantes peuvent être définies :

• keycloak_bind_address (par défaut : 0.0.0.0)
• keycloak_http_port (par défaut : 8080)
• keycloak_https_port (par défaut : 8443)

Pour le TLS via un bundle PKCS12, les variables supplémentaires suivantes doivent être fournies :

• keycloak_tls_pkcs12 (chemin vers le bundle PKCS12)
• keycloak_tls_pkcs12_passphrase (utilisez ansible-vault pour protéger)
• keycloak_tls_pkcs12_alias (nom de la clé/certificat dans keycloak_tls_pkcs12)

Pour le TLS via des fichiers clé/cert, les variables supplémentaires suivantes doivent être fournies :

• keycloak_tls_cert (chemin vers le fichier cert serveur TLS)
• keycloak_tls_key (chemin vers le fichier clé serveur TLS)

NOTE : les fichiers TLS source (keycloak_tls_pkcs12, keycloak_tls_cert, keycloak_tls_key) utilisés pour créer le magasin de clés Keycloak peuvent se trouver soit sur le contrôleur Ansible (c'est-à-dire local) soit sur le système cible distant. Par défaut, le rôle suppose que les fichiers TLS source sont locaux. Cependant, si les fichiers TLS source sont situés sur la cible distante, réglez la variable keycloak_tls_files_on_target sur True.

Vous pouvez contrôler les valeurs de délai d'attente avec les variables suivantes :

keycloak_startup_timeout : Nombre de secondes à attendre que Keycloak démarre.

keycloak_jboss_config_connect_timeout : Nombre de millisecondes à attendre que l'utilitaire de configuration jboss se connecte au serveur wildfly.

keycloak_jboss_config_command_timeout : Nombre de secondes à attendre que l'utilitaire de configuration jboss complète chaque commande exécutée dans le fichier de configuration.

Voir roles/keycloak/defaults/main.yml pour une liste d'autres valeurs par défaut des variables que l'on peut vouloir remplacer.

Test

Des tests en interne sont fournis qui utilisent molecule pour tester le rôle contre des conteneurs docker. Ces tests sont conçus pour être utilisés par CI, mais ils peuvent également être exécutés localement pour les tester lors du développement.

Problème de nom de rôle

AVERTISSEMENT : Pour les tests en interne, le nom du répertoire doit correspondre au nom du rôle Ansible Galaxy

NOTE : Dans ces exemples, il est supposé que le dépôt a été cloné dans ~/src/

Ansible s'attend à ce qu'un rôle ait une structure de répertoire prescrite. Par exemple, si le rôle est nommé my_role, Ansible s'attendra à trouver un répertoire nommé my_role dans le ANSIBLE_ROLES_PATH avec des sous-répertoires semblables à ceci :

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

Par convention, la plupart des rôles Galaxy sont créés dans un dépôt git dont le répertoire de niveau supérieur contient les sous-répertoires de rôle ci-dessus, ce qui signifie que le répertoire créé lors du clonage du dépôt git devient le nom du rôle. En utilisant l'exemple ci-dessus, le dépôt git serait nommé my_role. Cependant, la plupart des dépôts git ne sont pas nommés identiquement au nom de leur rôle Galaxy. Si vous essayez d'exécuter molecule test au niveau supérieur d'un arbre git cloné avec le nom de dépôt par défaut, vous obtiendrez une erreur rôle non trouvé comme ceci :

ERROR! le rôle 'nkinder.keycloak' n'a pas été trouvé dans /home/$USER/src/ansible-keycloak/molecule/default/roles:/tmp/molecule/ansible-keycloak/default/roles:/home/$USER/src:/home/$USER/src/ansible-keycloak/molecule/default

L'erreur semble avoir été dans '/home/$USER/src/ansible-keycloak/molecule/default/playbook.yml': ligne 6, colonne 7, mais peut être ailleurs dans le fichier selon la syntaxe exacte.

La ligne fautive semble être :

  roles:
    - role: nkinder.keycloak
      ^ ici

La solution à cela est simple, lors du clonage du dépôt git, fournissez un nom de répertoire qui correspond au nom du rôle dans le fichier molecule/default/playbook.yml.

Pour déterminer le nom du rôle que molecul utilisera, trouvez sa définition dans molecule/default/playbook.yml :

  roles:
    - role: nkinder.keycloak

Ainsi, le nom du rôle que molecul utilisera est nkinder.keycloak.

Donc, pour cloner ce dépôt, faites ceci :

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

Bien sûr, si vous clonez depuis un fork GitHub, vous devrez ajuster l'URL du dépôt en conséquence.

Vous devrez vous déplacer dans le dépôt git cloné :

$ cd nkinder.keycloak

Lorsque vous exécutez molecule test depuis le répertoire de niveau supérieur du dépôt git, molecule obtiendra le chemin du répertoire de travail actuel et à partir de cela, trouvera le chemin du répertoire parent, alors il définira le ANSIBLE_ROLES_PATH pour inclure le répertoire parent du dépôt de rôle. Ainsi, lorsque Ansible s'exécutera, il trouvera votre rôle via le nom du répertoire de votre dépôt git. Par exemple :

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

Comme ansible recherche un rôle nommé nkinder.keycloak, il recherchera dans les répertoires répertoriés dans ANSIBLE_ROLES_PATH et utilisera les fichiers trouvés dans /home/$USER/src/nkinder.keycloak.

NOTE : molecul mettra en stage certains fichiers dans un répertoire temporaire pendant la durée d'un test, c'est le MOLECULE_EPHEMERAL_DIRECTORY et dans nos exemples, c'est /tmp/molecule/ansible-keycloak/default, d'où le premier chemin dans le ANSIBLE_ROLES_PATH ci-dessus.

NOTE : git ne nécessite pas que le nom du répertoire de niveau supérieur du dépôt corresponde au nom du dépôt git. Même si le nom du répertoire du dépôt cloné sera différent du nom du dépôt, toutes les opérations git fonctionneront comme prévu, car l'URL du dépôt est spécifiée en tant que remote dans .git/config.

Les tests se font de préférence en installant molecul dans un virtualenv :

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

NOTE : Vous devez nommer le répertoire du virtualenv .venv car molecul s'attend à cela.

AVERTISSEMENT : Si vous avez déjà cloné le dépôt sous le nom du dépôt au lieu du nom du rôle, vous pouvez renommer le répertoire du dépôt, mais si vous avez créé le .venv avant le renaming, vous devez supprimer .venv et la recréer car le virtualenv aura intégré les anciens chemins.

Par défaut, molecul utilise docker pour construire et exécuter les images de test. Vous aurez besoin de docker installé et d'avoir le démon docker en marche :

# Pour installer le package docker
$ sudo dnf install docker

# Pour démarrer le service Docker :
$ sudo systemctl start docker

# Vérifiez que Docker a été correctement installé et fonctionne en lançant
# l'image hello-world de Docker.

$ sudo docker run hello-world

# Pour démarrer éventuellement le démon Docker au démarrage
$ sudo systemctl enable docker

Il est nécessaire d'exécuter les tests en tant qu'utilisateur autorisé à exécuter la commande docker sans utiliser sudo. Cela se fait généralement en ajoutant votre utilisateur au groupe 'docker' sur votre système.

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

# L'appartenance au groupe est évaluée lors de la création d'une nouvelle session de connexion.
# À moins que vous ne vous déconnectiez et vous reconnectiez, vous devrez utiliser `newgrp`
# pour ajouter votre appartenance au groupe `docker` dans la session de connexion actuelle.
$ newgrp docker

De plus, il y a un défi autour de python-libselinux sur les plateformes qui utilisent SELinux. Si vous utilisez un virtualenv, vous devez vous assurer que le module python selinux est disponible dans le virtualenv. Même s'il est installé sur votre hôte contrôleur ansible et le hôte cible, certaines des tâches déléguées à l'hôte local utiliseront le virtualenv. Le module selinux ne peut pas être installé via pip. Une solution à cela est de copier le répertoire entier selinux de votre emplacement site-packages système (/usr/lib64/$PY_VERSION/site-packages/selinux sur x86_64) dans le répertoire site-packages du virtualenv. Vous devrez également copier le fichier binaire selinux.so à partir du répertoire site-packages (il n'est pas situé à l'intérieur du répertoire selinux). Le nom de selunux.so varie entre Python2 et Python3.

Sous Python2, le nom de base du .so est _selinux.so, pour Python 2.7 sur x86_64, cela serait ce .so :

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

Sous Python3, le nom de base du .so ajoute cpython, la version python, l'architecture et l'OS, pour Python 3.7 sur x86_64, cela ressemblerait à cela :

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

Une fois votre virtualenv correctement configuré, les tests peuvent être exécutés avec ces commandes :

$ cd nkinder.keycloak # Votre dépôt dont le répertoire correspond au nom du rôle Galaxy
$ molecule test

ASTUCE : Ajouter --debug à la commande molecule peut aider à diagnostiquer des problèmes ainsi que capturer la sortie dans un fichier de log, vous voudrez peut-être faire ceci :

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

Par défaut, la cible de test sera la dernière image centos de Docker Hub. Vous pouvez tester contre une image/tag différente comme ceci :

$ MOLECULE_DISTRO="fedora:28" molecule test`

À FAIRE

• Ajouter un playbook d'exemple qui utilise ansible-freeipa pour créer le service keycloak et obtenir le cert
• Ajouter un playbook d'exemple qui crée un realm/client en utilisant le module keycloak_client
• Ajouter la capacité de configurer IdM en tant que backend d'identité pour keycloak via le fournisseur SSSD