Table des matières
Comment écrire un back office d'authentification?
La traduction de cette page est incomplète mais l'avertissement ci dessous est bien à jour ! les backends d'authentification décrits sur cette page ne fonctionneraient que sur des versions de DokuWiki anciennes allant jusqu'à 2012-10-13 “Adora Belle” incluse. Pour vos nouveaux développements, reportez vous à la nouvelle documentation des Extensions d'authentification. Les anciens backends décrits ici ne sont plus pris en charge. |
---|
Le système d'authentification de Dokuwiki est très modulable et peut, d'une manière générale, authentifier un utilisateur en utilisant tout ce qui est accessible par PHP.
Si aucun des back offices fournis ne fait ce que vous voulez, vous pouvez tout simplement créer le votre. Les back offices sont stockés dans le dossier inc/auth/
et doivent obligatoirement être nommés <backend>.class.php
, <backend> étant le nom de votre back office. Dans ce fichier, vous devez déclarer une classe nommée auth_<backend>
.
NB : Votre classe peut aussi étendre un back office déjà existant ou tout simplement la classe auth_basic
définie dans inc/auth/basic.class.php
.
Dans votre classe, vous devez surcharger quelques méthodes et fixer la valeur de certains attributs hérités de la classe de base. Quelques-uns de ces attributs sont décrits ci-dessous, mais pour l'implémentation de votre classe, vous devez vous référer aux commentaires de la classe de base!
Si vous écrivez un nouveau back office, pensez à le partager avec la communauté!
Attributs dont les valeurs doivent être fixées
$success
Ce simple booléen doit être fixé à true dans votre constructeur si votre module d'authentification a correctement été initialisé. Utilisez cette variable pour signaler au front-office que quelque chose s'est mal passé en la fixant à false.
$cando
Cette variable est en fait un tableau associatif de booléens. Vous devez fixer les champs du tableau à true pour toutes les fonctionnalités que votre back office fournit. Voici une liste des clés dans le tableau $cando
et leurs significations :
addUser | est-ce que des utilisateurs peuvent être créés? |
delUser | est-ce que des utilisateurs peuvent être supprimés? |
modLogin | les noms de login peuvent-ils être changés? |
modPass | les mots de passe peuvent-ils être changés? |
modName | les noms réels peuvent-ils être changés? |
modMail | les adresses mails peuvent-elles être changées? |
modGroups | les groupes peuvent-ils être changés? |
getUsers | peut-on récupérer une liste d'utilisateurs (filtrée)? |
getUserCount | peut-on récupérer le nombre d'utilisateurs? |
getGroups | peut-on récupérer une liste des groupes disponibles? |
external | le module vérifie-t-il l'authentification externe? |
logoff | le module possède-t-il des méthodes spéciales de déconnexion? |
Méthodes requises
Seules deux fonctions doivent absolument être implémentées. Mais plus vous en ferez, plus le front office sera capable d'interagir.
Constructeur
Evidemment, votre classe doit posséder un constructeur! Il doit fixer les valeurs des champs mentionnés ci-dessus.
checkPass()
Cette méthode doit vérifier si un utilisateur donné existe et si le mot de passe donné (en plaintext) est correct.
getUserData()
Cette méthode est utilisée pour retourner des informations à propos d'un utilisateur, comme son adresse mail et son nom réel.
Méthodes facultatives
Toutes ces méthodes sont optionnelles et ne seront appelées que si le champ approprié est fixé à true.
trustExternal()
Si $cando['external'] vaut true, cette méthode est utilisée pour authentifier un utilisateur – aucune des méthodes d'authentification internes à DokuWiki ne seront utilisées.
Cette fonction peut être utilisée pour s'authentifier grâce à des cookies tiers ou grâce aux mécanisme d'authentification d'Apache. Elle remplace la fonction auth_login()
du fichier inc/auth.php
.
Jetez un oeil au back office punbb pour un example d'utilisation de cette fonction.
Si cette fonction est implémentée, vous pourrez omettre toutes les autres méthodes de votre module (même celles indiquées comme requises – à part bien sûr le constructeur).
D'après l'example de punbb, la méthode trustExternal()
doit fixer la valeur des variables globales suivantes :\\'
$USERINFO['name']
$USERINFO['mail']
$USERINFO['grps']
$_SERVER['REMOTE_USER']
$_SESSION[DOKU_COOKIE]['auth']['user']
$_SESSION[DOKU_COOKIE]['auth']['info'] = $USERINFO;
Pour une description des variabes $USERINFO, référez-vous à la documentation de la fonction GetUserData()
.
N'oubliez pas d'ajouter ' global $USERINFO
' au début de cette fonction, pour rendre la variable accessible.
Un autre élément à garder à l'esprit si vous implémentez “Single Sign On” en vous basant sur un cookie, est que si vous voulez pouvoir utiliser le formulaire de connexion de DokuWiki quand le cookie SSO n'est pas présent, vous devez créer ce cookie après avoir vérifié les identifiants, pour qu'au prochain chargement de la page vous puissiez procéder à l'authentification en vous basant sur ce cookie SSO, les variables $user
et $pass
étant vides tant que le formulaire de connexion n'est pas soumis. Dans punbb, cela est réalisé par l'appel de la fonction pun_setcookie()
.
logOff()
Si $cando['logoff'] vaut true, cette méthode sera appelée lors d'une déconnexion. Utilisez-la pour effacer les cookies ou pour les actions similaires. Ceci est probablement utile uniquement avec trustExternal.
createUser()
Crée un utilisateur avec les données fournies.
modifyUser()
Modifie les données d'un utilisateur.
deleteUser()
Supprime un ou plusieurs utilisateurs.
getUserCount()
Renvoie le nombre d'utilisateurs correspondant à certains critères de filtrage.
retrieveUsers()
Récupère les données utilisateur pour les utilisateurs correspondant à certains critères de filtrage.
addGroup()
Crée un nouveau groupe.
retrieveGroups()
Liste les groupes disponibles.