...
On se place ici dans le cadre d'un établissement qui fonctionne avec la version 2.3 de Grouper et qui souhaite opérer une mise à jour de celui-ci.
| Avertissement |
|---|
Cette documentation et les procédures qui s'y rapportent sont en cours de développement et mise au point. |
| Sommaire |
|---|
Apports de Grouper 5.x par rapport à la 2.3
Par rapport à la version 2.3 que l'on avait documentée en 2017, la dernière version de Grouper (5.13.0 à l'heure où l'on débute cette documentation) profite d'un certain nombre d'améliorations :
...
Dans le fork esup, nous proposons ces fichiers d'exemple à modifier pour s'adapter à votre ldap notamment :
- grouper/conf/grouper-loader.properties
- grouper/conf/grouper.hibernate.properties
- grouper/conf/grouper.properties
- grouper/conf/morphString.properties
- grouper/conf/subject.properties
Base de données
Un dump et restore postgresql de la base grouper doit pouvoire pouvoir fonctionner.
Voir ci-après pour la mise à jour via DDL.
...
Avec un gsh fonctionnel on pourra lancer le grouper dameon daemon via un systemd ainsi configuré - fichier /etc/systemd/system/grouper-loader-daemon.service
...
Cependant le packaging sous maven n'est pas clair, il apparait apparaît en effet que tout est pensé pour une exploitation depuis les images Docker.
...
Migration vers une installation sous Docker
Cf l'expérimentaion l’expérimentation ci-dessus de la mise en place de Grouper depuis les sources et si on suit la documentation officielle, il est très fortement recommandé de faire fonctionner Grouper sous docker.
...
De notre installation précédente, on conserve le apache avec le mod_shib sur le host ainsi que la base de données postgresql.
On fait en sorte d'avoir un minimum de configurations sous forme de fichiers de configurations à plat ; dit autrement, on importe toutes les configurations dans la base de données.
On fait cela via l'interface graphique.
Depuis Home > Miscellaneous > Configure > Configuration files on importe les fichiers de notre répertoire conf
Seul le fichier morphString.properties restera en fichier à plat pour y indiquer une clef de chiffrement ; en plus de cette configuration, le grouper n'a besoin en configuration docker que des paramètres de connexion à la base de donnéesOn fait donc tourner sous docker les services grouper à proprement parler, avec un container par usage : 1 pour l'interface web, 1 pour le web-service et 1 pour le daemon.
Nous proposons ici l'usage d'un simple docker-compose.yml afin de tout consolider dans un seul fichier (mais on aurait pu se contenter d'appeler directement du docker simplement), un établissement ayant une infrastructure de conteneurisation se passera du docker-compose pour privilgier privilégier son orchestrateur en place.
...
permet de regrouper et mutualiser les configurations à la base de données notamment pour les 3 container containers grouper
| Bloc de code | ||
|---|---|---|
| ||
GROUPER_DATABASE_PASSWORD=esup
GROUPER_DATABASE_USERNAME=grouper
GROUPER_DATABASE_URL=jdbc:postgresql://grosville:5432/grouper
GROUPER_AUTO_DDL_UPTOVERSION=v5.*.*
GROUPER_TOMCAT_HTTPS_PORT=-1
GROUPER_WS_GROUPER_AUTH=true
GROUPER_LOG_TO_HOST=true
GROUPER_UI_CONFIGURATION_EDITOR_SOURCEIPADDRESSES=192.168.0.3 |
slashRoot/opt/grouper/grouperWebapp/WEB-INF/classes/morphString.properties
...
Si vous êtes passés par l'étape d'installation de grouper depuis les sources, vous avez pu mettre à jour la base deonnées données via l'IHM avant de passer en docker ; sinon, vous êtes confrontés au fait qu'il faut configurer dans l'IHM les sources de données pour pouvoir s'authentifier dans l'application... mais que pour s'authentifier, il faut aoir avoir au préalable configuré les sources de données.
...
- https://github.com/EsupPortail/grouper-esup/blob/grouper-esup-5/grouper/conf/grouper-loader.properties
- https://github.com/EsupPortail/grouper-esup/blob/grouper-esup-5/grouper/conf/subject.properties
Dès que vous aurez accés accès à l'interface web vous pourrez importer directement les configurations de ces fichiers en base et ne plus avoir besoin de monter ces configurations en tant que volume .(pour l'import, votre IP doit référencée dans la variable d'environnement GROUPER_UI_CONFIGURATION_EDITOR_SOURCEIPADDRESSES - cf le fichier grouper.env donné ci-dessus).
Dans la Dans la phase de migration, pensez au passage à ne démarrer que grouper-ui pour tout mettre au point, et ne lancez le daemon qu'une fois que tout est bien (re)paramétré en base.
Ldap Provisionning
Passage de PSP au Ldap Provisionning
Une partie des configurations Ldap sont données dans les fichiers (à importer en base de données)
- https://github.com/EsupPortail/grouper-esup/blob/grouper-esup-5/grouper/conf/grouper-loader.properties
- https://github.com/EsupPortail/grouper-esup/blob/grouper-esup-5/grouper/conf/subject.properties
Comme dit ci-dessus, la logique des nouvelles versions de Grouper est de privilégier les configurations en base de données (permettant ainsi de tout avoir en base et de faciliter les montées de version en passant d'un container docker à un autre proposant une version plus à jour de grouper).
Aussi l'interface graphique permet de saisir l'ensemble des configurations permettant cette synchro grouper→ldap depuis le menu Home > Miscellaneous > Provisioning.
La configuration est cependant assez ardue, même en utilisant la facilité du "Ldap 'start with'" lorsqu'on ajoute un provisionner.
Si vous avez une configuration qui suit les recommandations supann et ce qu'on présentatit dans la documentation à propos de la version de grouper 2.3 (usage de groupOfNames, groupes à plat, overlay pour le memberOf, ...), le "start with" avec "flatGroupsWithMembershipDNs" aide grandement mais quelques subtilités restent à préciser.
Aussi nous proposons ici une configuration que l'on a exportée et que vous pouvez importer via l'interface web depuis Home > Configure > Configuration files : grouper-loader.properties
Une fois le group-loader.properties importée, vous retrouvez dans Home > Miscellaneous > Provisioning le provisionner ldapGroups.
N'hésitez pas alors à lancer l'outil de "Dignostics".
Daemons de synchro → ldap
2 daemons doivent être définis : CHANGE_LOG_consumer_ldapGroupgSyncInc et OTHER_JOB_ldapGroupgSyncFull - si ce n'est pas le cas ajoutez les
- le premier, de type edu.internet2.middleware.grouper.app.provisioning.ProvisioningConsumer, permet de faire la synchro régulière toutes les minutes ;
- le deuxième, de type edu.internet2.middleware.grouper.app.provisioning.GrouperProvisioningFullSyncJob, permet de consolider au besoin l'ensemble.
Configuration des dossiers à provisionner
Pour chaque dossier 'racine', vous pouvez indiquer que l'ensemble de leurs groupes enfant doivent être reversés dans votre LDAP.
Copies d'écran d'interfaces indiquant que les daemons jobs ldap sont fonctionnels
Purges
La purge des utilisateurs qui ne sont plus présents dans le ldap et qui doivent être supprimés de Grouper ne se fait plus par gsh mais par un daemon de manière automatique
Le premier démarrage va passer toutes les DDL de manière automatique, grâce à la variable d'environnement GROUPER_AUTO_DDL_UPTOVERSION=v5.. ; vous devrez aussi ensuite lancer la mise à jour de la base de données via l'interface web.
| Bloc de code | ||
|---|---|---|
| ||
docker ps
docker exec -it dc48872f813a bash
sudo -u tomcat /bin/bash
./bin/gsh.sh
new GrouperPasswordSave().assignApplication(GrouperPassword.Application.WS).assignUsername("monGrouperWsUser").assignPassword("monGrouperWsPassword").save(); |
Ldap Provisionning
Passage de PSP au Ldap Provisionning
Une partie des configurations Ldap sont données dans les fichiers (à importer en base de données)
- https://github.com/EsupPortail/grouper-esup/blob/grouper-esup-5/grouper/conf/grouper-loader.properties
- https://github.com/EsupPortail/grouper-esup/blob/grouper-esup-5/grouper/conf/subject.properties
Comme dit ci-dessus, la logique des nouvelles versions de Grouper est de privilégier les configurations en base de données (permettant ainsi de tout avoir en base et de faciliter les montées de version en passant d'un container docker à un autre proposant une version plus à jour de grouper).
Aussi l'interface graphique permet de saisir l'ensemble des configurations permettant cette synchro grouper→ldap depuis le menu Home > Miscellaneous > Provisioning.
La configuration est cependant assez ardue, même en utilisant la facilité du "Ldap 'start with'" lorsqu'on ajoute un provisionner.
Si vous avez une configuration qui suit les recommandations supann et ce qu'on présentait dans la documentation à propos de la version de grouper 2.3 (usage de groupOfNames, groupes à plat, overlay pour le memberOf, ...), le "start with" avec "flatGroupsWithMembershipDNs" aide grandement mais quelques subtilités restent à préciser.
Aussi nous proposons ici une configuration que l'on a exportée et que vous pouvez importer via l'interface web depuis Home > Miscellaneous > Configure > Configuration files, Config actions > Import config file : grouper-loader.properties
Une fois le group-loader.properties importée, vous retrouvez dans Home > Miscellaneous > Provisioning le provisionner ldapGroups.
N'hésitez pas alors à lancer l'outil de "Diagnostics".
Daemons de synchro → ldap
2 daemons doivent être définis : CHANGE_LOG_consumer_ldapGroupgSyncInc et OTHER_JOB_ldapGroupgSyncFull - si ce n'est pas le cas ajoutez les
- le premier, de type edu.internet2.middleware.grouper.app.provisioning.ProvisioningConsumer, permet de faire la synchro régulière toutes les minutes (en production, nous avons finalement opté pour toutes les 10sec.) ;
- le deuxième, de type edu.internet2.middleware.grouper.app.provisioning.GrouperProvisioningFullSyncJob, permet de consolider au besoin l'ensemble.
Configuration des dossiers à provisionner
Pour chaque dossier 'racine', vous pouvez indiquer que l'ensemble de leurs groupes enfant doivent être reversés dans votre LDAP.
Attention, suivant la configuration de votre provisioning, ne pas indiquer de groupes à 'provisioner' peut revenir à dire à grouper de supprimer tous les groupes du ldap (cf la propriété provisioner.ldapGroups.deleteGroupsIfNotExistInGrouper=true donnée dans le fichier grouper-loader.properties ).
Copies d'écran d'interfaces indiquant que les daemons jobs ldap sont fonctionnels
SCIM
Client SCIM pour peuplement d'applications
Grouper est nativement, et sans configuration supplémentaire, client SCIM.
Il permet donc de configurer des applications à peupler (provisioning) tout comme il peut peupler les groupes LDAP.
SCIM permet de pousser les utilisateurs et groupes de Grouper vers une application en utilisant le protocole HTTP. Ça permet à l'application de s'affranchir par exemple d'une connexion LDAP qui peut poser problème si l'application est proposée en SAAS à l'établissement utilisateur.
Nous avons validé le bon fonctionnement de SCIM par Grouper 5.14.0 via un outil qu'on a nommé esup-scim-tools et qui est disponible ici :
https://github.com/EsupPortail/esup-scim-tools
Application "laboratoire" pour l'usage de SCIM, cet outil peut permettre de se familiariser avec SCIM, notamment avec pour client Grouper.
Les congiguration SCIM sont à réaliser dans l'interface web de Grouper. Comme pour ldap, elles peuvent être relativement complexes, aussi on partage ici 2 exports (grouper-laoder.properties) de ces configurations :
- la première configuration permet uniquement de peupler les Users ; on sélectionnera donc un seul groupe côté grouper pour peupler l'application via les users de ce groupe uniquement : scim-users-only-grouper-loader.properties
- la deuxième configuration permet de peupler les Users et les Groupes ; aussi on pourra ici sélectionner tout un dossier (avec sous-dossiers et sous-groupes) pour que grouper puisser peupler à la fois les Users et les Groups : scim-users-and-groups-grouper-loader.properties
Serveur SCIM pour créations de groupes dans Grouper depuis une application tierce...
Cf https://spaces.dev.at.internet2.edu/display/GrIntDev/Grouper+TIER+SCIM+server#
Non testé à ce jour (18/12/2024)
Purges
La purge des utilisateurs qui ne sont plus présents dans le ldap et qui doivent être supprimés de Grouper ne se fait plus par gsh mais par le daemon de manière automatique via une tâche dédiée.
Des vues permettent de visualiser le listing des utilisateurs notés comme non présents dans le ldap (et le nombre de jours durant lesquels grouper les a noté comme non présent) ou encore de forcer la purge manuellement de ces mêmes utilisateurs.
Des configurations dans la section "grouper.properties < Unresolvable Subject Deletion Utility" permettent d'ajuster le comportement de la tâche dédiée à ces purges.
→ à vérifier
Debug
Si vous avez besoin de faire du debug pour détecter un comportement suspect ou un problème, le grouperdaemon peut se lancer en mode debug comme toute application Java, à vous ensuite d'utiliser un IDE (eclipse ou idea) permettant de positionner des breakpoints et autres.
Exemple d'arguments java à ajouter au daemon :
| Bloc de code | ||||
|---|---|---|---|---|
| ||||
-Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=4000,suspend=n | ||||
| ||||
-Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=4000,suspend=n |
Sous docker, la mise en place de cela demandera un peu plus de modifications : surcharge de configurations voire de fichiers et exposition du port (4000 ici).
Consommation CPU
Par rapport à une installation 2.3, qui utilisait notamment PSP pour mettre à jour les groupes vers ldap, la consommation CPU est moindre, alors même que les synchronisations de groupes sont plus réactives.
Sur le graphe ci-dessous, la migration de Grouper 2.3 vers 5 (sous docker) a été opérée le 23 octobre.
Sous docker, la mise en place de cela demandera un peu plus de modifications : surcharge de configurations voire de fichiers et exposition du port (4000 ici)