Utilisez la commande installmodule de jelix pour installer le module :

$ cd myapp/
$ php cmd.php installmodule jauth

Cela activera le module et le plugin, et créera un nouveau fichier var/config/index/auth.coord.ini.php, qui est la configuration du plugin et du système d'authentification.

Copiez le fichier lib/jelix-modules/jauth/install/var/config/auth.coord.ini.php dans le repertoire de configuration du point d'entrée, par exemple, var/config/index/auth.coord.ini.php.

Dans le fichier de configuration du point d'entrée, vous indiquerez alors dans la section « coordplugins » :

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

• *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

Vous devez indiquer le nom du driver utilisé au niveau de l'option driver.

Depuis Jelix 1.6.18, vous pouvez aussi mettre ce nom de driver dans la configuration principale (mainconfig ou localconfig), comme ceci :

[coordplugin_auth]
driver=Db

Vous devez ensuite avoir une section portant ce même nom, pour les options propres au driver. consultez la documentation sur les pilotes jauth pour activer l'un d'eux.

Depuis Jelix 1.4.1 (et 1.3.4, 1.2.10), il y a deux systèmes de hachage des mots de passe pour leur stockage. Jelix 1.4.1 et supérieur propose en effet une méthode plus sécurisée, utilisant l'API password de PHP 5.5 (une implémentation pure PHP est fournie dans Jelix pour les versions antérieures de PHP).

Ancien système de hachage ¶

function sha1WithSalt($salt, $password) {
    return sha1($salt.':'.$password);
}

 driver=Db
   
 [Db]
 dao = "mon_dao"
 password_crypt_function = "1:sha1WithSalt"
 password_salt = "votre_sel_ici"

Nouveau système de hachage ¶

Migration ¶

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.

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.coord.ini.php peut être celle-ci :

  on_error_action = "jauth~login:out"
  after_login = "myapp~default:index"
  after_logout = "jauth~login:form"
  on_error_sleep = 3

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 (il n'est pas recommandé de l'activer, car cela facilite les attaques de type DDOS). Pour after_login et after_logout, voir plus bas.

À noter que vous pouvez surcharger les templates du module en créant vos propres templates dans le dossier var/themes/default/jauth/. Voir le système de thème.

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.

si vous utilisez le moteur d'urls significant, il vous faudra également ajouter dans votre fichier var/config/urls.xml la ligne <url pathinfo="/auth" module="jauth" include="urls.xml"/> afin d'obtenir des urls propres au module.

Pour connecter et déconnecter un utilisateur, il faut utiliser les méthodes login() et logout() :

   // Connexion
   $ok = jAuth::login('le_login', 'le_mot_de_passe_en_clair');
   
   // deconnexion
   jAuth::logout();

À partir du moment où login() a étéé appelé et a renvoyé true, jAuth stocke des informations sur l'utilisateur en session, qui peuvent être utilisées par d'autres composants. Ces informations sont dans un objet, que vous récupérez par getUserSession() :

  $user = jAuth::getUserSession();

La classe de cette objet dépend du driver utilisé. Pour le driver db, ça sera un record du dao indiqué dans la configuration de jAuth.

Vous pouvez à tout moment savoir si un utilisateur est identifié avec la méthode isConnected() :

  if (jAuth::isConnected()) {
      // ok, l'utilisateur est identifié
  }

Pour authentifier l'utilisateur de manière persistante (il sera reconnu même quand sa session sera détruite), ajoutez true en troisième paramètre de login().

Vous pouvez aussi simplement vérifier un login/mot de passe, sans connecter l'utilisateur qui correspond :

  $ok = jAuth::verifyPassword('le_login', 'le_mot_de_passe_en_clair');

Pour créer un utilisateur, il faut là aussi passer par jAuth. Vous devez d'abord lui demander de créer un objet qui contiendra les informations de l'utilisateur, et ensuite lui dire de l'enregistrer

   // récupération d'un objet
   $newUser = jAuth::createUserObject ('son_login', 'son_mot_de_passe_en_clair');
   
   // ajout d'information si nécessaire, dépendant de l'application
   $newUser->birthday = '1980-01-01';
   
   // création de l'utilisateur par le driver
   $ok = jAuth::saveNewUser($newUser);

Pour modifier les informations d'un utilisateur, vous devez récupérer l'objet qui correspond (cela peut être l'utilisateur courant), le modifier, et ensuite indiquer à jAuth de le sauver :

   $user = jAuth::getUserSession()
   // ou
   $user = jAuth::getUser('son_login');

   // exemple de modification
   $user->birthday = '1980-01-02';

   jAuth::updateUser($user);

Note : si l'utilisateur modifié est celui qui est actuellement connecté, les informations en sessions seront elles aussi modifiées.

N'utilisez pas ce processus pour modifier le mot de passe ! Car vous n'êtes pas censé savoir comment le mot de passe est chiffré/stocké. Cela dépend de la configuration de jAuth et du driver. Pour changer le mot de passe d'un utilisateur, il faut utiliser la méthode changePassword()

   jAuth::changePassword('son_login', 'nouveau_mot_de_passe_en_clair');

Vous pouvez utiliser jAuth::getRandomPassword() pour générer un mot de passe aléatoire.

Pour supprimer un utilisateur, utilisez jAuth::removeUser() :

   jAuth::removeUser('son_login');

Pour récupérer la liste des utilisateurs, utilisez jAuth::getUserList() :

   $list = jAuth::getUserList();

Vous récupérez alors un iterateur que vous pouvez utiliser avec un foreach. Chaque élément est un objet contenant les infos d'un utilisateur (comme avec getUser())

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
• AuthErrorLogin : indique une erreur d'authentification de l'utilisateur
• AuthBeforeLogin : permet d'effectuer des traitements spécifiques avant l'authentification de l'utilisateur
• AuthChangePassword (depuis Jelix 1.6.17): le mot de passe d'un utilisateur a changé.

Les tests sont sur les propriétés suivantes :

• AuthCanRemoveUser : canremove
• AuthCanLogin : canlogin
• AuthBeforeLogin : processlogin

function onAuthCanRemoveUser  ($event)
{
   $login = $event->getParam('login'); 
   if($login == 'admin)
     $ok = false;
   else
     $ok = true;
   $event->Add(array('canremove'=>$ok));
}