Installation et personnalisation d'un service de découverte
Cette fiche concerne le WAYF distribué par SWITCH.
Site de référence du WAYF : http://www.switch.ch/aai/support/tools/wayf.html
1. Pourquoi cette implémentation ?
- implémentation légère en php
- open-source
- internationalisation (plusieurs langues définies par défaut)
- personnalisations facile à inclure
Embedded WAYF: Gain ergonomique qui permet d'inclure le menu déroulant contenant les fournisseurs d'identités directement sur la page d'accueil de la ressource- Lecture directe des méta-données (même au format SAML2). Le code permet de parcourir et alimenter directement le fichier qui liste les IdP extraits des méta-données d'une fédération.
2. Quelle version ?
Nous vous conseillons d'utiliser la dernière version du WAYF qui corrige certains bugs et offre ne nouvelles fonctionnalités (utilisation de méta-données au format SAML pour générer la liste des IdP).
Cette fiche concerne la version 1.9.x du WAYF de Switch.
3. Installation
Téléchargement du WAYF : https://forge.switch.ch/redmine/projects/wayf
l'arborescence est la suivante par défaut :
- config.php : Fichier de configuration
- IDProvider.conf.php : fichier qui permet de gérer manuellement des IdPs (identifiants et URL SSO). Le WAYF peut se baser directement sur ce fichier au lieu d'extraire la liste depuis un fichier de méta-données XML.
- IDProvider.metadata.conf.php : contient le résultat de l'exécution du script readMetadata.php
- images : répertoire contenant des images pour la personnalisation du WAYF
- languages.php : fichier de langues d'internationalisations. Cinq langues disponibles par défaut, Anglais, Français, Allemand, Italien, Portugais.
- LICENSE
- README
- readMetadata.php : extrait la liste des IdP (Identifiant et URL SSO) d'un fichier de méta-données en XML spécifié dans config.php
- templates.php : fichier principal gérant le “look” du WAYF. Fichier à modifier pour le personnaliser
- WAYF : Script php métier qui gère les redirections HTTP, positionnement de cookies du WAYF ainsi que la gestion du “embedded WAYF”
- extraction de la liste des IdP depuis un fichier de méta-données au format SAML 2. ;
- définition de la liste des IdP dans un fichier
IDProvider.conf.php.
La première solution évite de devoir gérer la liste des IdPs (adapté pour lister tous les IdP d'une fédération). La tache d'analyse du fichier de méta-données est assurée par le script readMetadata.php, dont l'exécution peut être planifiée dans la crontab.
La seconde a pour avantage de permettre aux ressources utilisant le WAYF de ne garder que les IdP qu'elle reconnait et de les présenter de façon catégorisée, voir l'exemple de SWITCH ici.
4. Configuration
Toute la configuration du fonctionnement du WAYF se fait dans le fichier config.php. Voici une description succincte de certaines options disponibles :
- $useSAML2Metadata = true : active l'extraction de la liste des IdP depuis un fichier de méta-données en XML spécifié $metadataFile ;
- $SAML2MetaOverLocalConf = true : extrait les IdP des fichiersIDProvider.conf.php et du fichier XML des méta-données en donnant priorité à ce dernier si conflit de description d'un IdP existe. Cette fonctionnalité est limitée : l'opération ne fait pas la somme des deux listes des IdP dans le cas où les sources de données sont définies ;
- $showPermanentSetting = false : affiche la case de sélection définitive de l'IdP et non pas seulement la sélection pour “la session uniquement”. Cela induit une bonne information des usagers de la ressource dans le cas où ils auraient besoin d'effacer pour une raison ou une autre le cookie permanent qui a été positionné pour cela ;
- $commonDomain : permet d'utiliser une instance du WAYF pour plusieurs ressources qui se trouvent sur différents serveurs physiques ou simplement sur des virtualshosts différents. Mais le WAYF ne pourra positionner de cookies que pour le domaine spécifié dans cette variable. Exemple :
- $commonDomain = exemple.fr
- URL ressource 1 : ressource1.exemple.fr
- URL ressource 2 :ressource2.autreexemple.org
- URL WAYF : exemple.fr/wayf
- ⇒ ici le WAYF ne pourra positionner les cookies des choix des utilisateurs que pour le ressource 1 et pas la deuxième.
Les autres options sont normalement assez explicites et peuvent être laissées par défaut, sauf pour celles qui induisent une personnalisation de l'affichage.
Remarque : Pendant la période de migration entre la fédération du CRU et la fédération Éducation-Recherche, vous devez alimenter votre WAYF avec le fichier de méta-données agrégées (CRU+RENATER), fourni par RENATER. Plus de détails sur cette page.
5. Personnalisation de l'interface graphique
Pour personnaliser l'apparence du WAYF, vous devrez modifier le fichier templates.php. Des connaissances en PHP et en HTML/CSS seront toutefois nécessaires.
La fonction “embedded WAYF” (non décrite dans ce document) offre un meilleur niveau d'intégration avec une ressource puisque les éléments graphiques seront insérés dans la page de la ressource.Plus d'informations sur cette fonctionnalité sur cette page.