Raccourcis : Contenu - rubriques - sous rubriques
EN FR
La page correspondant à la dernière version stable est consultable dans le Manuel Jelix 1.7

Le système d'authentification de Jelix ne s'occupe que d'une seule chose : gérer des identifiants/mots de passe et des utilisateurs. Il repose sur des pilotes[1] pour accéder aux données d'un utilisateur. C'est ainsi qu'il peut s'appuyer sur une base de données, un annuaire LDAP, etc. Pour le moment, il existe un pilote pour une base de données, un pilote pour un annuaire géré par un serveur LDS et un pilote pouvant utiliser une classe quelconque.

Mise en oeuvre

Le système d'authentification repose sur plusieurs choses :

  • Un plugin pour le coordinateur, nommé auth et livré en standard avec Jelix, vérifiant si l'authentification est effectuée pour les actions où elle est nécessaire.
  • Une classe jAuth, permettant d'effectuer les différentes opérations sur l'authentification et la gestion des identifiants. Cette classe repose sur un système de pilote.
  • Un module, jauth, proposant un contrôleur et des templates par défaut. Il n'est, en principe, pas indispensable : vous pouvez tout à fait utiliser votre propre contrôleur, la mise en oeuvre étant relativement simple.
  • Un objet stocké en session, contenant les informations sur l'utilisateur. Il est fourni par le pilote. Cela peut être un objet DAO, une simple classe, etc.

Installer le plugin auth pour le coordinateur

Le rôle du plugin auth :

  • vérifier l'authentification ;
  • gérer un timeout de session (optionnel) ;
  • gérer la persistance de l'authentification via un cookie (optionnel) ;
  • indiquer le driver à utiliser pour jAuth ;
  • indiquer les paramètres pour le pilote (DAO pour jAuthDb, cn/sn/uid pour un pilote LDAP, etc.) ;
  • indiquer ce qu'il faut faire en cas de non authentification.

Aussi, dès lors que l'on veut utiliser le système d'authentification, il faut activer le plugin et le configurer. Il est indispensable.

Dans le fichier de configuration, vous indiquerez alors dans la section « coordplugins » :


[coordplugins]
auth = "auth.coord.ini.php"

Le fichier de configuration « auth.coord.ini.php » du plugin est une copie du fichier « /lib/jelix/plugins/coord/auth/auth.coord.ini.php.dist », que vous placez dans le répertoire « var/config/ » de votre application

Note sur la déclaration du plugin : Si vous utilisez plusieurs plugins de coordinateur, l'ordre de déclaration des plugins dans le fichier de configuration a une importance. Ainsi, si vous placez le plugin auth en premier, il faut savoir que les autres plugins ne seront pas exécutés dans le cas où le plugin auth demande une redirection (par exemple la page d'identification). En général, il convient donc de placer ce plugin après les plugins ne nécessitant pas d'authentification.

Pour en savoir plus sur les plugins : plugins

Configurer le plugin

Vous devez ensuite éditer le fichier « auth.coord.ini.php », pour indiquer la configuration du système d'authentification. Voici les différents paramètres.

Indiquer le driver

Vous devez indiquer le nom du pilote utilisé au niveau de l'option « driver ». Vous devez ensuite avoir une section portant ce même nom, pour les options propres au driver.


   driver=XXX
   
   [XXX]
   foo=bar

Par exemple, pour le pilote « Db » (les informations sont stockées alors dans une base de données) :


 driver=Db
   
 [Db]
 dao = "mon_dao"
 password_crypt_function = md5

Pour en savoir plus sur les spécificités de chaque pilote disponible, ou même en créer un, consultez la documentation sur les pilotes jauth.

Timeout

L'option « timeout » permet d'indiquer en minutes le temps d'inactivité au bout duquel l'authentification ne sera plus valide. Si vous mettez « 0 », il n'y a pas de limite de temps. La session expirera à la fermeture du navigateur.

Contrôler l'authentification pour chaque action

Le plugin peut contrôler si l'action demandée a besoin d'une authentification ou non. Avec l'option « auth_required » dans le fichier INI, vous pouvez dire si par défaut toutes les actions nécessitent une authentification (valeur « on »), ou si par défaut, il n'y en a pas besoin (valeur « off »).


auth_required=on

Dans un cas comme dans l'autre, il faut pouvoir gérer les exceptions (par exemple, une action qui ne nécessite pas une authentification alors que par défaut toutes les actions le nécessitent). Les exceptions sont indiquées au niveau des contrôleurs, dans les paramètres de plugin.


class xxxCtrl extends jController {

    public $pluginParams = array( ...  );

}

Pour les actions concernées, vous indiquerez le paramètre auth.required et le mettrez à false ou true. Par exemple pour les actions index et affiche, il faut une authentification, alors que pour le reste des actions du contrôleur (« * » indique « toutes les actions »), ce n'est pas utile :


class xxxCtrl extends jController {

    public $pluginParams = array(
        '*'=>array('auth.required'=>false),
        'index'=>array('auth.required'=>true),
        'affiche'=>array('auth.required'=>true),
     );
}

Voir la page sur les plugins de coordinateurs pour mieux comprendre l'usage de « $pluginParams ».

Spécifier le comportement en cas de défaut d'authentification

Si l'authentification n'est pas faite alors que l'action en nécessite une, le plugin va alors agir en fonction de l'option on_error.

Si vous mettez la valeur 1, alors le plugin génèrera une erreur dont le message (ou plutôt la clé de la locale du message) est dans l'option error_message.

Si par contre la valeur est 2, alors le plugin exécutera l'action définie dans l'option on_error_action. Cela peut être une action d'un contrôleur du module auth (comme c'est le cas par défaut), ou alors une action de votre propre contrôleur dans un module tierce. Cette action en général affiche une page demandant un login/mot de passe (mais cela peut être autre chose…)

Persistance de l'authentification

jAuth propose un mécanisme de persistance d'authentification. C'est-à-dire la reconnaissance automatique de l'utilisateur quand il revient sur le site, même plusieurs jours après sa dernière visite (et donc après avoir perdu sa session PHP…). Cela se fait par le biais d'un cookie dans lequel sont stockées un certain nombre d'informations dont une partie est cryptée.

Vous avez pour cela deux paramètres importants :

  • persistant_enable : mettez le à « on » pour activer la persistance de l'authentification
  • persistant_crypt_key : c'est un paramètre à renseigner obligatoirement. Vous devez remplacer la valeur par défaut ! Ce paramètre doit contenir une chaîne quelconque de votre choix (plus de 10 lettres de préférence). Elle servira de clé de cryptage pour les données stockées dans le cookie. Si vous changez de clé en cours de route, les cookies seront invalides et les utilisateurs ne sont pas reconnus. Ils devront s'authentifier à nouveau.

D'autres paramètres sont disponibles :

  • persistant_cookie_name : indique le nom du cookie à utiliser. Par défaut : « jelixAuthentificationCookie ».
  • persistant_duration : indique la durée en jour de la validité du cookie. Par défaut c'est une journée.
  • persistant_cookie_path : le chemin du cookie. Par défaut (vide), il vaut la valeur de « basePath » dans la config générale.

Utiliser le contrôleur par défaut

Le module jauth propose des contrôleurs que vous pouvez utiliser pour gérer les actions de connexion, de déconnexion, en faisant appel à la classe jAuth. Il propose aussi des zones et des templates.

À l'avenir, il proposera également des zones de formulaire de changement de mot de passe, de formulaire de destruction de compte (si un utilisateur veut supprimer un compte sur une application type portail), de création de compte et de récupération de mot de passe. Bien sûr, on aurait des paramètres de configuration qui permettraient de dire si on autorise un utilisateur à supprimer son compte, à récupérer son mot de passe, etc.

Configuration classique

Quand on utilise le module jauth, il est possible d'ajouter des options de configuration propres au module. Par exemple, une configuration possible dans le fichier auth.plugin.ini.php peut être celle-ci :


  driver = Db
  on_error_action = "jauth~login:out"
  after_login = "myapp~default:index"
  after_logout = "jauth~login:form"
  on_error_sleep = 3
  [Db]
  dao = "jauth~jelixuser"

Le paramètre « on_error_sleep » est le nombre de secondes d'attente quand l'utilisateur a donné un mauvais mot de passe ou login. Pour « after_login » et « after_logout », voir plus bas.

Vous remarquerez aussi que dans l'exemple, on utilise le pilote Db. Le module jauth propose en effet un DAO pour le driver Db. Si vous l'utilisez, il faut créer alors la table « jlx_user » suivante (ici pour MySQL) :


  CREATE TABLE `jlx_user` (
  `usr_login` VARCHAR( 50 ) NOT NULL ,
  `usr_email` VARCHAR( 255 ) NOT NULL ,
  `usr_password` VARCHAR( 50 ) NOT NULL ,
  PRIMARY KEY ( `usr_login` )
  );

Vous pouvez bien sûr ajouter d'autres champs, il faudra alors proposer votre propre DAO (voir la documentation sur le pilote Db).

À noter que vous pouvez surcharger les templates du module en créant vos propres templates dans le dossier :


myapp/
  var/
    themes/
      default/
        jauth/

Configuration de la redirection

Dans la configuration du plugin, vous devez spécifier les paramètres « after_login », « after_logout », et éventuellement les options « enable_after_login_override » et « enable_after_logout_override ».

Les paramètres after_login et after_logout doivent contenir les sélecteurs des actions vers lesquelles il faut rediriger une fois que l'identification ou la déconnexion sont effectuées. Ils sont obligatoires. Si vous ne les indiquez pas, vous allez avoir des redirections vers l'action jauth~default:index qui n'existe pas, donc une erreur…

Il est possible dans un formulaire d'authentification ou de déconnexion, d'ajouter un paramètre caché contenant l'URL vers laquelle il faut rediriger. Cela permet de rediriger vers une page différente en fonction de la page sur laquelle on est quand on se connecte ou déconnecte. Dans ce cas, ce paramètre caché doit se nommer « auth_url_return », et doit contenir l'URL. Et vous devez mettre les paramètres de configuration enable_after_login_override et/ou enable_after_logout_override à « on ».

Utiliser son propre contrôleur

Vous pouvez utiliser vos propres contrôleurs pour gérer l'authentification : formulaire d'identification, connexion, déconnexion. Vous ferez appel alors à la classe jAuth et ses méthodes statiques pour vérifier les identifiants/mots de passe, connecter et déconnecter un utilisateur.

classe jAuth

C'est la classe principale du système d'authentification. Toutes ses méthodes sont statiques. Elle permet de gérer un utilisateur, de « connecter » et « déconnecter » un utilisateur, etc. Vous appellerez ces méthodes quand bon vous semble, sachant que les contrôleurs du module jauth peuvent se charger pour vous d'une bonne partie du travail. Voir son descriptif dans la référence.

l'objet user que vous passez à certaines méthodes vous est donné par jAuth lui même. C'est un objet contenant les données d'un utilisateur et il n'a pas de classe précise : son type dépend du driver utilisé et éventuellement de sa configuration (pour le driver Db, on peut fournir un DAO de notre choix par exemple). Il doit par contre respecter l'interface attendue par le driver, et doit avoir au moins un champ login et un champ password.

jAuth n'a pas à être surchargée. Elle s'appuie sur des « pilotes » pour gérer les différents types d'authentification.

Évènements

Pour la plupart des méthodes de jAuth, un évènement est émis. Cela permet à des modules tiers d'être au courant des différentes actions d'authentification, et donc de charger des données supplémentaires dans l'objet user, ou de gérer les données dépendantes à l'utilisateur etc.

  • AuthNewUser : indique qu'un utilisateur vient d'être ajouté
  • AuthCanRemoveUser : demande si on peut supprimer l'utilisateur ou pas
  • AuthRemoveUser : l'utilisateur a été supprimé
  • AuthUpdateUser : l'utilisateur vient d'être mis à jour
  • AuthCanLogin : demande si l'utilisateur peut se connecter
  • AuthLogin : un utilisateur vient de se connecter
  • AuthLogout : un utilisateur vient de se déconnecter

Notes

[1] drivers