doc: refonte doc exploitation idp

This commit is contained in:
Thomas NOËL 2015-07-02 16:25:10 +02:00
parent 5d44a28a1a
commit 6f2a59084f
1 changed files with 233 additions and 101 deletions

View File

@ -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 :
~~~
<link rel="stylesheet" href="{{STATIC_URL }}psl/css/style.css" />
~~~
ou la syntaxe plus actuelle :
~~~
{% load staticfiles %} <!-- au tout début du fichier HTML -->
...
<img src="{% static "psl/img/logo.png" %}">
~~~
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