Joomla! Documentation™

Joomla! 

≥ 3.0

Didacticiel

Le plugin d'authentification pour Joomla! offre beaucoup de souplesse et de puissance pour le système. En utilisant le système, il est possible d'authentifier des utilisateurs à partir de n'importe quelle source - la base de données Joomla, le système Open ID, un répertoire LDAP, ou un tout autre système d'authentification qui peut être consulté avec PHP.

Ce didacticiel vous propose un véritable exemple d'un plugin d'authentification de base qui montre comment créer des plugins d'authentification personnalisés pour le CMS Joomla.

La classe plgAuthenticationMyauth

Les plugins Joomla! sont créés par la création d'une classe enfant de la classe JPlugin. La classe JPlugin fournit toute l'infrastructure et les fonctionnalités de base qui sont nécessaires. Tout ce qu'il faut, c'est fournir les méthodes nécessaires pour gérer l'événement désiré.

Pour créer un plugin d'authentification, le nom de la classe enfant doit commencer par plgAuthentication, et doit se terminer par le nom du plugin à créer. Dans notre cas, le plugin s’appellera : "Myauth", de sorte que la classe devra s'appeler : plgAuthenticationMyauth.

La classe aura une méthode unique - la méthode onUserAuthenticate(). Cette méthode est en fait très simple, comme nous allons le démontrer.

La méthode onAuthenticate()

La méthode onAuthenticate() sera appelée lorsque le système va essayer d'utiliser votre plugin pour l'authentification des utilisateurs. Cette méthode va passer trois paramètres : les informations d'identification, quelques options supplémentaires et une référence à un objet de type JAuthenticationResponse. Cette méthode doit déterminer si le nom d'utilisateur et le mot de passe sont une combinaison valide pour l'authentification, puis retourner le résultat dans l'objet JAuthenticationResponse.

Concernant notre exemple, le contrôle d'authentification que nous allons opérer reste très simple. Nous allons simplement nous assurer que le nom d'utilisateur existe dans la table des utilisateurs et si c'est le cas, nous allons vérifier que le nom d'utilisateur soit bien l'inverse du mot de passe. Veuillez noter que depuis la version 3.1, l'objet de la base de données est créé dans le constructeur de sorte que nous pouvons l'appeler avec $db. Ainsi, notre vérification d'authentification ressemblera à ceci :

$db = JFactory::getDbo();
$query	= $db->getQuery(true)
	->select('id')
	->from('#__users')
	->where('username=' . $db->quote($credentials['username']));

$db->setQuery($query);
$result = $db->loadResult();

/**
 * To authenticate, the username must exist in the database, and the password should be equal
 * to the reverse of the username (so user joeblow would have password wolbeoj)
 */
if($result && ($credentials['username'] == strrev( $credentials['password'] )))

Bien que, dans notre exemple, le code soit très basique, il peut être remplacé par tout code nécessaire à votre plugin afin d'effectuer la vérification d'authentification adéquate. La flexibilité du code sera uniquement limitée par ce que PHP peut faire.

Maintenant que nous avons déterminé si oui ou non l'authentification a réussi, nous pouvons maintenant créer notre réponse :

$db = JFactory::getDbo();
$query	= $db->getQuery(true)
	->select('id')
	->from('#__users')
	->where('username=' . $db->quote($credentials['username']));

$db->setQuery($query);
$result = $db->loadResult();

if (!$result) {
    $response->status = JAuthentication::STATUS_FAILURE;
    $response->error_message = 'User does not exist';
}
/**
 * To authenticate, the username must exist in the database, and the password should be equal
 * to the reverse of the username (so user joeblow would have password wolbeoj)
 */
if($result && ($credentials['username'] == strrev( $credentials['password'] )))
{
    $email = JUser::getInstance($result); // Bring this in line with the rest of the system
    $response->email = $email->email;
    $response->status = JAuthentication::STATUS_SUCCESS;
}
else
{
    $response->status = JAuthentication::STATUS_FAILURE;
    $response->error_message = 'Invalid username and password';
}

En cas d'échec des réponses, nous avons défini deux propriétés de l'objet réponse : la propriété status et la propriété error_message. Actuellement, il existe six valeurs de réponse de statuts : STATUS_SUCCESS, STATUS_FAILURE, STATUS_CANCEL, STATUS_EXPIRED, STATUS_DENIED et STATUS_UNKNOWN. Pour plus d'informations sur ces valeurs de statut, veuillez consulter le fichier libraries/joomla/user/authentication.php.

La propriété error_message est définie en cas d'échec de l'authentification. Dans notre plugin, nous avons défini deux valeurs possibles pour cette propriété : "l'utilisateur n'existe pas", ce qui indique que notre requête ne renvoie aucun résultat et "Identifiant et mot de passe non valide", ce qui indique que le mot de passe n'est pas l'inverse du nom d'utilisateur. Il convient de noter que ces valeurs ne sont pas retournées à l'utilisateur. Pour des raisons de sécurité, la seule chose que l'utilisateur verra sera soit une connexion réussie, soit un message signifiant : "le nom d'utilisateur et le mot de passe ne correspondent pas". Le système Joomla! peut être configuré de sorte que ces messages d'erreur puissent être stockés dans un fichier journal à des fins de débogage.

Si l'authentification est réussie, on peut éventuellement ajouter à la réponse des informations à partir de notre authentification source. Dans ce cas, il faut récupérer les informations de l'utilisateur à partir de la base de données Joomla! et stocker l'adresse e-mail dans l'objet réponse. Pour plus d'informations sur les données pouvant être stockées dans l'objet réponse, vous pouvez consulter API Joomla! . Ces données peuvent ensuite être utilisées par les plugins utilisateurs au cours de l'événement défini afin de créer automatiquement des utilisateurs ou d'effectuer d'autres tâches de connexion.

Le fichier complet myauth.php

Maintenant que nous avons terminé les deux méthodes nécessaires à notre classe, nous pouvons placer notre classe dans un fichier PHP qui aura le même nom que notre plugin. Puisque notre plugin se nomme Myauth, nous appellerons notre fichier myauth.php. Voici notre fichier complet :

<?php
/**
 * @version    $Id: myauth.php 7180 2007-04-23 16:51:53Z jinx $
 * @package    Joomla.Tutorials
 * @subpackage Plugins
 * @license    GNU/GPL
 */

// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die();

/**
 * Example Authentication Plugin.  Based on the example.php plugin in the Joomla! Core installation
 *
 * @package    Joomla.Tutorials
 * @subpackage Plugins
 * @license    GNU/GPL
 */
class plgAuthenticationMyauth extends JPlugin
{
    /**
     * This method should handle any authentication and report back to the subject
     * This example uses simple authentication - it checks if the password is the reverse
     * of the username (and the user exists in the database).
     *
     * @access    public
     * @param     array     $credentials    Array holding the user credentials ('username' and 'password')
     * @param     array     $options        Array of extra options
     * @param     object    $response       Authentication response object
     * @return    boolean
     * @since 1.5
     */
    function onUserAuthenticate( $credentials, $options, &$response )
    {
        /*
         * Here you would do whatever you need for an authentication routine with the credentials
         *
         * In this example the mixed variable $return would be set to false
         * if the authentication routine fails or an integer userid of the authenticated
         * user if the routine passes
         */
        $db = JFactory::getDbo();
	$query	= $db->getQuery(true)
		->select('id')
		->from('#__users')
		->where('username=' . $db->quote($credentials['username']));

	$db->setQuery($query);
	$result = $db->loadResult();

	if (!$result) {
	    $response->status = STATUS_FAILURE;
	    $response->error_message = 'User does not exist';
	}

	/**
	 * To authenticate, the username must exist in the database, and the password should be equal
	 * to the reverse of the username (so user joeblow would have password wolbeoj)
	 */
	if($result && ($credentials['username'] == strrev( $credentials['password'] )))
	{
	    $email = JUser::getInstance($result); // Bring this in line with the rest of the system
	    $response->email = $email->email;
	    $response->status = JAuthentication::STATUS_SUCCESS;
	}
	else
	{
	    $response->status = JAuthentication::STATUS_FAILURE;
	    $response->error_message = 'Invalid username and password';
	}
    }
}
?>

Fichier manifest d'installation XML

Maintenant que nous avons créé notre classe JPlugin, tout ce qu'il nous reste à faire est de créer notre fichier XML d'installation qui indiquera au programme d'installation de Joomla! la procédure concernant notre plugin. Ce fichier est relativement simple :

<?xml version="1.0" encoding="utf-8"?>
<extension version="3.1" type="plugin" group="authentication">
    <name>Authentication - Myauth</name>
    <author>Joomla! Documentation Project</author>
    <creationDate>May 30, 2007</creationDate>
    <copyright>(C) 2005 - 2013 Open Source Matters. All rights reserved.</copyright>
    <license>http://www.gnu.org/copyleft/gpl.html GNU/GPL</license>
    <authorEmail>ian.maclennan@help.joomla.org</authorEmail>
    <authorUrl>www.joomla.org</authorUrl>
    <version>1.0</version>
    <description>An sample authentication plugin</description>
    <files>
        <filename plugin="myauth">myauth.php</filename>
    </files>
    <config/>
</extension>

Vous remarquerez que ce fichier est très similaire aux autres fichiers manifest d'installation XML Joomla. Quelques éléments importants sont à noter.

Le premier est l'attribut group sur l'élément racine. Pour des plugins d'authentification, l'attribut group doit contenir la valeur 'authentication'. Cela indique au système Joomla! de traiter votre plugin en tant que plugin d'authentification.

Il est également important de noter que l'attribut de version de l'élément racine extension doit être 3.1. Cela indiquera à Joomla! que votre plugin est écrit pour Joomla! .

Dans le champ name, nous avons indiqué son nom 'Authentication - Myauth'. Votre plugin n'est pas obligé de suivre cette convention de nommage, mais cela est préférable car il correspondra ainsi aux plugins standards d'authentification listés dans le gestionnaire de plugin.

Enfin, vous remarquez que l'attribut du filename qui contient les fichiers de notre plugin est nommé plugin. Sa valeur devrait être le nom de notre plugin. Dans notre cas, 'myauth'.

Empaquetage et utilisation

Maintenant que nous avons créé nos deux fichiers, tout ce qu'il nous reste à faire est de les empaqueter dans un fichier d'archive pouvant être lu par le système d'installation de Joomla.

Une fois que nous avons empaqueté et installé notre plugin, il est prêt à l'utilisation. Le plugin est publiable depuis le gestionnaire des plugins. Tous les plugins d'authentification seront regroupés. Il suffit de 'publier' les plugins pour les activer. Vous pouvez publier autant de plugins d'authentification que vous le souhaitez. Pour que l'authentification réussisse, seul un des plugins doit renvoyer un résultat JAUTHENTICATE_STATUS_SUCCESS.

Conclusion

Nous avons créé un plugin d'authentification simple. Nous avons démontré le processus de base permettant de vérifier une authentification et retourner les résultats au système Joomla.

Vous pouvez également tester facilement ce plugin en créant un paquet d'installation par vous-même.