J3.x

Difference between revisions of "Creating an Authentication Plugin for Joomla"

From Joomla! Documentation

m (Added Category Needs to be marked for translation)
m (Marked for translation)
Line 1: Line 1:
{{Joomla version|version=3.0|time=and later|comment=Tutorial}}
+
<noinclude><languages /></noinclude>
The authentication plugin system for Joomla! offers a great deal of flexibility and power to the system. Using the system, it is possible to authenticate users from any source - the Joomla! internal database, the Open ID system, an LDAP directory, or any authentication system that can be accessed using PHP.
+
{{Joomla version|version=3.0|time=and later|comment=<translate>Tutorial</translate>}}
 +
<translate>The authentication plugin system for Joomla! offers a great deal of flexibility and power to the system. Using the system, it is possible to authenticate users from any source - the Joomla! internal database, the Open ID system, an LDAP directory, or any authentication system that can be accessed using PHP.</translate>
  
This tutorial will present a really basic example of an authentication plugin that demonstrates how to create custom authentication plugins for the Joomla! CMS.
+
<translate>This tutorial will present a really basic example of an authentication plugin that demonstrates how to create custom authentication plugins for the Joomla! CMS.</translate>
  
== The plgAuthenticationMyauth Class ==
+
<translate>== The plgAuthenticationMyauth Class ==</translate>
Joomla! plugins are created by creating a child class of the JPlugin class. The JPlugin class provides all the infrastructure and basic functionality that is required. All that is necessary is to provide the necessary methods to handle the desired event.
+
<translate>Joomla! plugins are created by creating a child class of the JPlugin class. The JPlugin class provides all the infrastructure and basic functionality that is required. All that is necessary is to provide the necessary methods to handle the desired event.</translate>
  
To create an authentication plugin, the name of the child class must begin with <code>plgAuthentication</code>, and must end with the name of the plugin that is being created. In our case, the plugin is called Myauth, so the class will be called <code>plgAuthenticationMyauth</code>.
+
<translate>To create an authentication plugin, the name of the child class must begin with <code>plgAuthentication</code>, and must end with the name of the plugin that is being created. In our case, the plugin is called Myauth, so the class will be called <code>plgAuthenticationMyauth</code>.</translate>
  
The class will have just a single method - the <code>onUserAuthenticate()</code> method. This method is actually very simple, as will be demonstrated.
+
<translate>The class will have just a single method - the <code>onUserAuthenticate()</code> method. This method is actually very simple, as will be demonstrated.</translate>
  
== The onAuthenticate() Method ==
+
<translate>== The onAuthenticate() Method ==</translate>
The <code>onAuthenticate()</code> method is the method that will be called when the system is trying to use your plugin to authenticate the user. This method will be passed three parameters: the credentials, some extra options, and a reference to an object of type JAuthenticationResponse. This method needs to determine if the username and password are a valid combination for authentication and return the result in the JAuthenticationResponse object.
+
<translate>The <code>onAuthenticate()</code> method is the method that will be called when the system is trying to use your plugin to authenticate the user. This method will be passed three parameters: the credentials, some extra options, and a reference to an object of type JAuthenticationResponse. This method needs to determine if the username and password are a valid combination for authentication and return the result in the JAuthenticationResponse object.</translate>
  
For our example, the authentication check that we are going to do is very simple. We will simply make sure that the specified username exists in the users table, and if it does, we will check to see if the username is the reverse of the password. Note since {{JVer|3.1}} that the database object is created in the constructor so we can call it with <code>$db</code>. So our authentication check will look like:
+
<translate>For our example, the authentication check that we are going to do is very simple. We will simply make sure that the specified username exists in the users table, and if it does, we will check to see if the username is the reverse of the password. Note since {{JVer|3.1}} that the database object is created in the constructor so we can call it with <code>$db</code>. So our authentication check will look like:</translate>
 
   
 
   
 
<source lang="php">
 
<source lang="php">
Line 33: Line 34:
 
</source>
 
</source>
  
Although this is very basic in our example, this code can be replaced with any code that is necessary to perform the authentication checking that is necessary for your plugin. The flexibility is only limited by what PHP can do.
+
<translate>Although this is very basic in our example, this code can be replaced with any code that is necessary to perform the authentication checking that is necessary for your plugin. The flexibility is only limited by what PHP can do.</translate>
  
Now that we have determined whether or not authentication was successful, we can now create our response:
+
<translate>Now that we have determined whether or not authentication was successful, we can now create our response:</translate>
  
 
<source lang="php">
 
<source lang="php">
Line 68: Line 69:
 
</source>
 
</source>
  
For failed responses, we set two properties of the response object: the status property, and the error_message property. Currently there are six recognized response status value - <code>STATUS_SUCCESS</code>, <code>STATUS_FAILURE</code>, <code>STATUS_CANCEL</code>, <code>STATUS_EXPIRED</code>, <code>STATUS_DENIED</code> and <code>STATUS_UNKNOWN</code>. For more information on these status values, consult the libraries/joomla/user/authentication.php file.
+
<translate>For failed responses, we set two properties of the response object: the status property, and the error_message property. Currently there are six recognized response status value - <code>STATUS_SUCCESS</code>, <code>STATUS_FAILURE</code>, <code>STATUS_CANCEL</code>, <code>STATUS_EXPIRED</code>, <code>STATUS_DENIED</code> and <code>STATUS_UNKNOWN</code>.</translate> <translate>For more information on these status values, consult the libraries/joomla/user/authentication.php file.</translate>
  
The error_message property is set in case the authentication is not successful. In our plugin, we set two possible values to this property: "User does not exist", which indicates that our query did not return any results, and "Invalid username and password", which indicates that the password was not the reverse of the username. It should be noted that these values are not returned to the user. For security reasons, the only thing the user will see is a successful login, or a message that says, "Username and password do not match." The Joomla! system can be configured so that these error messages can be stored in a log file for debugging purposes.
+
<translate>The error_message property is set in case the authentication is not successful. In our plugin, we set two possible values to this property: "User does not exist", which indicates that our query did not return any results, and "Invalid username and password", which indicates that the password was not the reverse of the username. It should be noted that these values are not returned to the user. For security reasons, the only thing the user will see is a successful login, or a message that says, "Username and password do not match." The Joomla! system can be configured so that these error messages can be stored in a log file for debugging purposes.</translate>
  
If authentication is successful, we can optionally add information from our authentication source to the response. In this case, we are retrieving the user information from the Joomla! database and storing the email address in the response object. For more information on what data can be stored in the response object, please consult [http://api.joomla.org/Joomla-Platform/User/JAuthenticationResponse.html the Joomla API]. This data can then be used by user plugins in the event it is desired to automatically create users or perform other login tasks.
+
<translate>If authentication is successful, we can optionally add information from our authentication source to the response. In this case, we are retrieving the user information from the Joomla! database and storing the email address in the response object. For more information on what data can be stored in the response object, please consult [http://api.joomla.org/Joomla-Platform/User/JAuthenticationResponse.html the Joomla API]. This data can then be used by user plugins in the event it is desired to automatically create users or perform other login tasks.</translate>
  
== The Complete myauth.php File ==
+
<translate>== The Complete myauth.php File ==</translate>
  
Now that we have completed the two methods that are necessary for our class, we put our class into a PHP file that has the same name as our plugin. Since our plugin is called Myauth, we call our file myauth.php. Here is the complete listing for this file:
+
<translate>Now that we have completed the two methods that are necessary for our class, we put our class into a PHP file that has the same name as our plugin. Since our plugin is called Myauth, we call our file myauth.php. Here is the complete listing for this file:</translate>
  
 
<source lang="php">
 
<source lang="php">
Line 154: Line 155:
 
</source>
 
</source>
  
== The XML Install Manifest ==
+
<translate>== The XML Install Manifest ==</translate>
  
Now that we have created our JPlugin class, all we have to do is create our XML install file that will tell the Joomla! installer how to install our plugin. This file is simple:
+
<translate>Now that we have created our JPlugin class, all we have to do is create our XML install file that will tell the Joomla! installer how to install our plugin. This file is simple:</translate>
 
   
 
   
 
<source lang="xml">
 
<source lang="xml">
Line 177: Line 178:
 
</source>
 
</source>
  
You will notice that this file looks very similar to any other Joomla! XML install manifest file. There are a few important things to notice.
+
<translate>You will notice that this file looks very similar to any other Joomla! XML install manifest file. There are a few important things to notice.</translate>
  
The first thing to notice is the group attribute on the root element. For authentication plugins, the group attribute must have the value 'authentication'. This tells the Joomla! system to treat your plugin as an authentication plugin.
+
<translate>The first thing to notice is the group attribute on the root element. For authentication plugins, the group attribute must have the value 'authentication'. This tells the Joomla! system to treat your plugin as an authentication plugin.</translate>
  
It is also important to note that the version attribute of the root element (extension) should be 3.0. This will tell Joomla! that your plugin is written for Joomla! {{JVer|3.x}}.
+
<translate>It is also important to note that the version attribute of the root element (extension) should be 3.0. This will tell Joomla! that your plugin is written for Joomla! {{JVer|3.x}}.</translate>
  
We entered the name 'Authentication - Myauth' in the name field. Your plugin doesn't HAVE to follow this convention, but it looks better because then it will match the standard authentication plugins that are listed in the plugin manager.
+
<translate>We entered the name 'Authentication - Myauth' in the name field. Your plugin doesn't HAVE to follow this convention, but it looks better because then it will match the standard authentication plugins that are listed in the plugin manager.</translate>
  
Finally, notice that filename attribute that contains our plugin file has an attribute called plugin. The value of this should be the name of our plugin. In this case, it is myauth.
+
<translate>Finally, notice that filename attribute that contains our plugin file has an attribute called plugin. The value of this should be the name of our plugin. In this case, it is myauth.</translate>
  
== Wrapping it All Up and Using It ==
+
<translate>== Wrapping it All Up and Using It ==</translate>
  
Now that we have created our two files, all we have to do is package them up into an archive file that can be read by the Joomla! installer system.
+
<translate>Now that we have created our two files, all we have to do is package them up into an archive file that can be read by the Joomla! installer system.</translate>
  
Once we package and install our plugin, it is ready to be used. The plugin is published using the Plugin Manager. All of the authentication plugins will be grouped together. Plugins are enabled by 'publishing them'. You can publish as many authentication plugins as you want. In order for successful authentication to occur, only one of the plugins needs to return a <code>JAUTHENTICATE_STATUS_SUCCESS</code> result.
+
<translate>Once we package and install our plugin, it is ready to be used. The plugin is published using the Plugin Manager. All of the authentication plugins will be grouped together. Plugins are enabled by 'publishing them'. You can publish as many authentication plugins as you want. In order for successful authentication to occur, only one of the plugins needs to return a <code>JAUTHENTICATE_STATUS_SUCCESS</code> result.</translate>
  
== Conclusion ==
+
<translate>== Conclusion ==</translate>
  
We have now created a simple authentication plugin. We have demonstrated the basic process of doing an authentication check and return the results to the Joomla! system.
+
<translate>We have now created a simple authentication plugin. We have demonstrated the basic process of doing an authentication check and return the results to the Joomla! system.</translate>
  
You can also easily test this plugin by packaging it yourself.
+
<translate>You can also easily test this plugin by packaging it yourself.</translate>
  
 +
<noinclude>
 +
<translate>
 
[[Category:Tutorials]]
 
[[Category:Tutorials]]
 
[[Category:Plugin Development]]
 
[[Category:Plugin Development]]
[[Category:Needs to be marked for translation]]
+
</translate>
 +
</noinclude>

Revision as of 18:50, 26 June 2015

Other languages:
English • ‎español • ‎français • ‎中文(台灣)‎
Joomla! 
≥ 3.0
Tutorial

The authentication plugin system for Joomla! offers a great deal of flexibility and power to the system. Using the system, it is possible to authenticate users from any source - the Joomla! internal database, the Open ID system, an LDAP directory, or any authentication system that can be accessed using PHP.

This tutorial will present a really basic example of an authentication plugin that demonstrates how to create custom authentication plugins for the Joomla! CMS.

The plgAuthenticationMyauth Class[edit]

Joomla! plugins are created by creating a child class of the JPlugin class. The JPlugin class provides all the infrastructure and basic functionality that is required. All that is necessary is to provide the necessary methods to handle the desired event.

To create an authentication plugin, the name of the child class must begin with plgAuthentication, and must end with the name of the plugin that is being created. In our case, the plugin is called Myauth, so the class will be called plgAuthenticationMyauth.

The class will have just a single method - the onUserAuthenticate() method. This method is actually very simple, as will be demonstrated.

The onAuthenticate() Method[edit]

The onAuthenticate() method is the method that will be called when the system is trying to use your plugin to authenticate the user. This method will be passed three parameters: the credentials, some extra options, and a reference to an object of type JAuthenticationResponse. This method needs to determine if the username and password are a valid combination for authentication and return the result in the JAuthenticationResponse object.

For our example, the authentication check that we are going to do is very simple. We will simply make sure that the specified username exists in the users table, and if it does, we will check to see if the username is the reverse of the password. Note since Joomla 3.1 that the database object is created in the constructor so we can call it with $db. So our authentication check will look like:

$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'] )))

Although this is very basic in our example, this code can be replaced with any code that is necessary to perform the authentication checking that is necessary for your plugin. The flexibility is only limited by what PHP can do.

Now that we have determined whether or not authentication was successful, we can now create our response:

$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';
}

For failed responses, we set two properties of the response object: the status property, and the error_message property. Currently there are six recognized response status value - STATUS_SUCCESS, STATUS_FAILURE, STATUS_CANCEL, STATUS_EXPIRED, STATUS_DENIED and STATUS_UNKNOWN. For more information on these status values, consult the libraries/joomla/user/authentication.php file.

The error_message property is set in case the authentication is not successful. In our plugin, we set two possible values to this property: "User does not exist", which indicates that our query did not return any results, and "Invalid username and password", which indicates that the password was not the reverse of the username. It should be noted that these values are not returned to the user. For security reasons, the only thing the user will see is a successful login, or a message that says, "Username and password do not match." The Joomla! system can be configured so that these error messages can be stored in a log file for debugging purposes.

If authentication is successful, we can optionally add information from our authentication source to the response. In this case, we are retrieving the user information from the Joomla! database and storing the email address in the response object. For more information on what data can be stored in the response object, please consult the Joomla API. This data can then be used by user plugins in the event it is desired to automatically create users or perform other login tasks.

The Complete myauth.php File[edit]

Now that we have completed the two methods that are necessary for our class, we put our class into a PHP file that has the same name as our plugin. Since our plugin is called Myauth, we call our file myauth.php. Here is the complete listing for this file:

<?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';
	}
    }
}
?>

The XML Install Manifest[edit]

Now that we have created our JPlugin class, all we have to do is create our XML install file that will tell the Joomla! installer how to install our plugin. This file is 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>

You will notice that this file looks very similar to any other Joomla! XML install manifest file. There are a few important things to notice.

The first thing to notice is the group attribute on the root element. For authentication plugins, the group attribute must have the value 'authentication'. This tells the Joomla! system to treat your plugin as an authentication plugin.

It is also important to note that the version attribute of the root element (extension) should be 3.0. This will tell Joomla! that your plugin is written for Joomla! Joomla 3.x.

We entered the name 'Authentication - Myauth' in the name field. Your plugin doesn't HAVE to follow this convention, but it looks better because then it will match the standard authentication plugins that are listed in the plugin manager.

Finally, notice that filename attribute that contains our plugin file has an attribute called plugin. The value of this should be the name of our plugin. In this case, it is myauth.

Wrapping it All Up and Using It[edit]

Now that we have created our two files, all we have to do is package them up into an archive file that can be read by the Joomla! installer system.

Once we package and install our plugin, it is ready to be used. The plugin is published using the Plugin Manager. All of the authentication plugins will be grouped together. Plugins are enabled by 'publishing them'. You can publish as many authentication plugins as you want. In order for successful authentication to occur, only one of the plugins needs to return a JAUTHENTICATE_STATUS_SUCCESS result.

Conclusion[edit]

We have now created a simple authentication plugin. We have demonstrated the basic process of doing an authentication check and return the results to the Joomla! system.

You can also easily test this plugin by packaging it yourself.