doc: refonte doc exploitation idp
This commit is contained in:
parent
5d44a28a1a
commit
6f2a59084f
|
@ -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
|
||||
|
||||
|
|
Reference in New Issue