diff --git a/documentation/exploitation-idp-authentic.md b/documentation/exploitation-idp-authentic.md index 2e8ebe4..387b0dd 100644 --- a/documentation/exploitation-idp-authentic.md +++ b/documentation/exploitation-idp-authentic.md @@ -2,90 +2,6 @@ % Entr'ouvert SCOP -- http://www.entrouvert.com -Intégration à la fédération -=========================== - -Le choix de la fédération dans laquelle enregistrer l'IdP est fait dans le -fichier `/etc/authentic2/supann.conf` (se référer au manuel d'installation pour -plus d'information). - -**Une mise à jour des meta-données de la fédération est effectuée chaque -heure**, voir `/etc/cron.d/authentic2-supann`. - -Lors de l'installation d'une ressource dans la fédération, il peut être utile -de mettre à jour aussitôt les méta-données au niveau de l'IdP sans attendre une -heure. Pour cela, utiliser la commande suivante : - -~~~ -# su -s /bin/sh -c /usr/lib/authentic2-supann/update-renater-meta.sh authentic -~~~ - -Gabarits (_templates_ pour charte graphique) -============================================ - -Pour définir la charte graphique du site, il faut créer des _templates_, -c'est-à-dire des gabaris ou modèles de pages qui seront utilisés par Authentic -pour construire les pages HTML. - -Ces fichiers sont des gabartis gérés par le moteur de rendu de Django. Pour -savoir les utiliser, il faut connaitre leur langage de programmation, documenté -ici : [https://docs.djangoproject.com/fr/1.7/topics/templates/](https://docs.djangoproject.com/fr/1.7/topics/templates/) - -Les gabarits par défaut sont installés dans le répertoire -`/usr/share/pyshared/authentic2/templates/`. - -Pour remplacer un des gabarits par défaut, il faut créer un fichier avec le -même nom, et éventuellement dans le même sous-répertoire, à l'intérieur de -`/var/lib/authentic2/templates/`. Par exemple: - -* s'il faut remplacer `/usr/share/pyshared/authentic2/templates/base.html` alors - il faut créer un fichier `/var/lib/authentic2/templates/base.html` -* s'il faut remplacer `/usr/share/pyshared/authentic2/templates/idp/homepage.html` - il faut utiliser `/var/lib/authentic2/templates/idp/homepage.html` - -Un **gabarit de base** défini le style général du site, il est la base de -toutes les autres pages. Il est écrit sur -`/usr/share/pyshared/authentic2/templates/base.html`. - -**Pour modifier le style général du site**, il est donc conseillé de partir de -ce `base.html`, c'est-à-dire : - -~~~ -# cp /usr/share/pyshared/authentic2/templates/base.html /var/lib/authentic2/templates/base.html -# chmod 644 /var/lib/authentic2/templates/base.html -~~~ - -Puis travailler sur le fichier: - -~~~ -# nano /var/lib/authentic2/templates/base.html -~~~ - -Les modifications opérées sur le gabarit sont immédiatement visibles sur le -site. Cependant il se peut que différents systèmes de _cache_ interviennent, -auquel cas il peut être utile, entre autre, de redémarrer Authentic (`service -authentic2 restart`). - -Interface d'administration -========================== - -L'intégration à la fédération Renater «fixe» la configuration de l'IdP. Il peut -cependant être parfois utile d'aller vérifier que la configuration est -correcte. Pour cela, se rendre sur: - -> `https://idp.quelquechose.fr/admin` - -et se connecter avec un compte administrateur, par exemple l'identifiant -`admin` et le mot de passe choisi lors du `newdb` sur le serveur LDAP. - -Attention 1 : ne pas modifier ces configurations si vous ne savez pas ce que vous -faîtes ! - -Attention 2 : l'intégration à la fédération remets obligatoirement un -certain de nombre de configuration en place chaque heure -- par exemple les -réglements d'attributs obligatoires. - - Arrêt et démarrage ================== @@ -98,26 +14,185 @@ disponibles: * `service authentic2 start` : démarrage du service * `service authentic2 restart` : arrêt puis redémarrage du service -Logs -==== -Authentic est, techniquement, un processus géré par `gunicorn`, celui-ci -enregistre ses logs dans: +Configuration +============= -* `/var/log/authentic2/gunicorn-access.log`: accès au service -* `/var/log/authentic2/gunicorn-error.log`: autres messages qui, malgré le nom - du fichier, ne sont pas que les erreurs mais aussi des informations sur le - démarrage et l'arrêt, par exemple. +Intégration à la fédération +--------------------------- -Apache enregistre également les logs d'accès au service via HTTPS, dans -deux fichiers : +Le choix de la fédération dans laquelle enregistrer l'IdP est fait dans le +fichier `/etc/authentic2/supann.conf` (se référer au manuel d'installation pour +plus d'information). -* `/var/log/apache2/authentic2-supann_access.log` : logs d'accès -* `/var/log/apache2/authentic2-supann_error.log` : logs d'erreurs +**Une mise à jour des meta-données de la fédération est effectuée chaque heure, +à XXh30**, voir `/etc/cron.d/authentic2-supann`. + +Cela signifie que l'ensemble de la configuration de tous les services +(fournisseurs SAML) est faite dans les fichiers XML diffusés par la fédération +(meta-données et filtre d'attributs). Si une modification locale de +configuration est effectuée dans Authentic, elle sera écrasée par la mise à +jour suivante. + +Mise à jour forcée des données de la fédération +----------------------------------------------- + +Lors de l'installation d'une nouvelle ressource dans la fédération, il peut +être utile de mettre à jour aussitôt les méta-données au niveau de l'IdP sans +attendre une heure. Pour cela, utiliser la commande suivante : + +~~~ +# su -s /bin/sh -c /usr/lib/authentic2-supann/update-renater-meta.sh authentic +~~~ + +Explication : cette commande lance le script +`/usr/lib/authentic2-supann/update-renater-meta.sh` en tant qu'utilisateur +`authentic`. Il s'agit de la commande qui est lancée chaque heure par *cron*, +comme indiqué dans `/etc/cron.d/authentic2-supann`. -Mise à jour -=========== +Charte graphique +================ + +Gabarits HTML, généralités +-------------------------- + +Pour définir la charte graphique du site, il faut créer des _templates_, +c'est-à-dire des gabaris ou modèles de pages qui seront utilisés par Authentic +pour construire les pages HTML. + +Ces fichiers sont gérés par le moteur de rendu de Django. Pour savoir les +utiliser, il faut connaitre leur langage de programmation, documenté ici : +[https://docs.djangoproject.com/fr/1.7/topics/templates/](https://docs.djangoproject.com/fr/1.7/topics/templates/) + +Les gabarits par défaut sont installés dans le répertoire +`/usr/share/pyshared/authentic2/templates/`. Ils ne doivent pas être modifiés, +mais peuvent être replacés/surchargés. + +Pour surcharger/remplacer un des gabarits par défaut, il faut créer un fichier +avec le même nom, et dans le même sous-répertoire, à l'intérieur de +`/var/lib/authentic2/templates/`. + +Par exemple s'il faut surcharger +`/usr/share/pyshared/authentic2/templates/authentic2/base.html` alors il faut +créer un fichier `/var/lib/authentic2/templates/authentic2/base.html`. + +Gabarit général : base.html +--------------------------- + +Un **gabarit de base** défini le style général du site, il est la base de +toutes les autres pages. Il est écrit sur +`/usr/share/pyshared/authentic2/templates/authentic2/base.html`. + +**Pour modifier le style général du site**, il suffit de partir de ce fichier +`base.html`, donc d'abord en faire une copie de travail : + +~~~ +# cp /usr/share/pyshared/authentic2/templates/authentic2/base.html \ + /var/lib/authentic2/templates/authentic2/base.html +# chmod 644 /var/lib/authentic2/templates/authentic2/base.html +~~~ + +Puis travailler sur le fichier obtenu +`/var/lib/authentic2/templates/authentic2/base.html` + +Les modifications opérées sur le gabarit sont immédiatement visibles sur le +site. Cependant il se peut que différents systèmes de _cache_ interviennent, +auquel cas il peut être plus rapide de redémarrer Authentic (`service +authentic2 restart`). + +Fichiers statiques (images, css, js) +------------------------------------ + +Les garabits HTML peuvent faire appel à des fichiers statiques, avec deux +syntaxes possibles : + +~~~ + +~~~ + +ou la syntaxe plus actuelle : + +~~~ + {% load staticfiles %} + ... + +~~~ + +Le fichier correspondant doit être présent dans le répertoire `/var/lib/authentic2/static/`, +c'est à dire avec les deux exemples ci-dessus : + +* `/var/lib/authentic2/static/psl/css/style.css` +* `/var/lib/authentic2/static/psl/img/logo.png` + +Une fois les fichiers copiés dans ces répertoires, il faut utiliser l'outil +de déploiement des fichiers statiques de Django pour qu'il les place dans +un répertoire géré par le serveur Web (Apache ici). Pour cela, il suffit +de relancer l'IdP, son démarrage intègre le déploiement des _statics_: + +> `# service authentic2 restart` + + +Pour en savoir plus, lire la documentation de référence sur la gestion des +fichiers statiques par un logiciel Django : +[https://docs.djangoproject.com/en/1.7/howto/static-files/](https://docs.djangoproject.com/en/1.7/howto/static-files/) + + +Interfaces de gestion +===================== + +Interface d'administration +-------------------------- + +L'intégration à la fédération Renater «fixe» la configuration de l'IdP. Il peut +cependant être parfois utile d'aller vérifier que la configuration est +correcte. Pour cela, se rendre sur: + +> `https://idp.exemple.fr/admin/` + +et se connecter avec un compte administrateur, par exemple l'identifiant +`admin` et le mot de passe choisi lors du `newdb` sur le serveur LDAP. + +Attention : cette interface est une vue quasi directe de la configuration des +services et utilisateurs. Il ne faut pas modifier ces configurations. +L'interface d'administration est activée uniquement à des fins de vérification +et/ou déboguage. + +Attention : l'intégration à la fédération remets la configuration de chaque +service à zéro, chaque heure -- par exemple les réglements d'attributs. + +Interface simplifiée +-------------------- + +Une interface de gestion simplifiée est également disponible à l'adresse : + +> `https://idp.exemple.fr/manage/` + +Ici encore cette interface n'est présente qu'à des fins de vérification. Elle +est prévue pour une instance d'Authentic qui gère elle-même ses utilisateurs et +ses services, ce qui n'est pas le cas ici : les utilisateurs sont gérés dans +l'annuaire LDAP, le services sont configurés via les données de la fédération. + +Données à sauvegarder +===================== + +Configuration : + +* `/etc` complet +* sinon, au moins `/etc/authentic2/` +* sinon, au moins la bi-clé `/etc/authentic2/key.pem` et `/etc/authentic2/cert.pem` +* `/var/lib/authentic2` complet, surtout si les gabarits ont été adaptés + (sous-répertoire `templates` et `static`) + +Données (base PostgreSQL) : + +Il est inutile de dupliquer la base de données, elle n'est utilisée par +Authentic que pour enregistrer les configurations des services providers, +celles-ci étant obtenues via la fédération. + + +Mise à jour du logiciel +======================= La mise à jour du système doit être effectuée aussi fréquement que possible, typiquement une fois par jour (mises à jour de sécurité Debian). Entr'ouvert @@ -135,17 +210,74 @@ Mise à jour des paquets qui ont une version plus récente que celle installée > `# apt-get upgrade` - Il est possible que des versions futures de la solution nécessitent l'installation de nouveaux paquets, dans ce cas Entr'ouvert mettra à jour les -dépendances de ses paquets et il faudra utiliser la commande `apt-get -dist-upgrade`. +dépendances de ses paquets et il faudra utiliser la commande suivante : +> `# apt-get dist-upgrade`. + + +Débogage +======== + +Journaux (logs) +--------------- + +Authentic est, techniquement, un processus géré par `gunicorn`, celui-ci +enregistre ses logs dans: + +* `/var/log/authentic2/gunicorn-access.log`: accès au service +* `/var/log/authentic2/gunicorn-error.log`: autres messages qui, malgré le nom + du fichier, ne sont pas que les erreurs mais aussi des informations sur le + démarrage et l'arrêt, par exemple. + +Apache enregistre également les logs d'accès au service via HTTPS, dans +deux fichiers : + +* `/var/log/apache2/authentic2-supann_access.log` : logs d'accès +* `/var/log/apache2/authentic2-supann_error.log` : logs d'erreurs + +Echanges SAML +------------- + +Authentic est un IdP qui utilise le protocole SAML 2.0 pour ses échanges sur la +fédération Renater. La majeure partie du débogage se passe en général via +l'écoute des échanges SAML 2.0 dans un navigateur client. Nous conseillons +l'utilisation du navigateur Firefox avec l'extension SAML tracer : +[https://addons.mozilla.org/fr/firefox/addon/saml-tracer/](https://addons.mozilla.org/fr/firefox/addon/saml-tracer/). + +Mode DEBUG +---------- + +Si le déboguage doit se faire dans le logiciel lui-même, il est possible d'activer +le mode `DEBUG` dans `/etc/authentic2/supann.conf` : + +~~~ +# extrait de /etc/authentic2/supann.conf: +export DEBUG=1 +~~~ + +puis relancer le service : + +> `# service authentic2 restart` + +De nombreuses informations de débogage sont alors présentes dans +`/var/log/syslog`, qui peuvent s'avérer importantes en cas de problème lourd. +Elles peuvent être demandées en cas d'appel au support de la solution. + +Par ailleurs, en cas d'erreur (HTTP 400 ou 500), des messages d'erreur système +complets et détaillés (_traceback_) sont affichés sur le navigateur. + +Attention : **ne jamais fonctionner en production avec le mode DEBUG**. En +effet, dans ce mode, le service peut afficher des traces d'erreurs qui +divulguent des informations sensibles sur le navigateur des utilisateurs. ----- Historique du document ====================== +> 20150611 tnoel -- restructuration, adaptations à Authentic 2.1.20+ + > 20150217 tnoel -- première version