Use the command module:configure of jelix to install the module:

$ php dev.php module:configure jauth

It will activate the module, and create a new file var/config/index/auth.coord.ini.php, which is the configuration of the plugin auth.

Then launch php install/installer.php.

Copy the file lib/jelix-modules/jauth/install/var/config/auth.coord.ini.php into the configuration directory of your entry point, for instance app/system/index/auth.coord.ini.php.

You should then add this line into the coordplugins section of your application configuration file:

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

• *Note on the plugin declaration**: if you use several coordinator plugins, the order of declaration in the configuration is important. So if the plugin "auth" is in first, then other plugins won't be called if it asks a redirection. So you should declare the "auth" plugin after plugins that don't need authentication.

You can learn more about plugins here.

You must assign the driver option with a driver name and fill a section containing the driver parameters.

driver=Db

It is possible to indicate the driver into the main configuration (mainconfig.ini.php, localconfig.ini.php or the configuration file of an entry point), into the section coordplugin_auth.

[coordplugin_auth]
driver=Db

Read the jAuth drivers documentation to know which driver you can use and how to activate it.

Since Jelix 1.4.1 (and 1.3.4, 1.2.10), there are two hashing system to hash your password in the storage. Jelix 1.4.1 and higher provide indeed a more secured method, using the new password API of PHP 5.5.

Old deprecated hashing system ¶

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

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

New hashing system ¶

When using the jAuth module, one can add/modify options to suit his neeeds. An example of auth.plugin.ini.php file:

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

The parameter on_error_sleep defines defines a duration. This is the amount of time in seconds, where authentication form is inactivated if user has not succeeded it. However it is not recommended to activate it, as it may facilitate a DDOS attack.

For after_login and after_logout, watch below.

Templates of the module jAuth can be easily customized if you overload them. Just copy and edit them in var/themes/default/jauth/. More about themes here.

Auth plugin defines some config options to specify redirections on login/logout steps, used by the jauth module.

Parameters after_login and after_logout must content some selectors to actions, to which a redirection will be made, if login succeeds for the first one, and if the logout succeeds for the second one. There are required. (else you will have some errors on a bad redirection).

In a authentication form or a logout url, you can add a parameter indicating to which page jelix should go after a login or a logout. This parameter should be named auth_url_return and should contain the url of this page. If you want to use it, you should activate enable_after_login_override and/or enable_after_logout_override (set them to on or off).

jauth module provides some urls mapping, to declare into your app/system/urls.xml file. Add the line:

<url pathinfo="/auth"     module="jauth" include="urls.xml"/>

To login/logout a user, you should call the methods login() and logout():

   // login
   $ok = jAuth::login('the_login', 'the_password');
   
   // logout
   jAuth::logout();

You can also use the jAuth::setUserSession($login) method to set the user without verifying the password. It is useful to implements a stateless web API with JWT for example.

After calling login() and if this is a success, jAuth stores some informations about the user in the session. These informations are in an object, that you can retrieve with getUserSession():

  $user = jAuth::getUserSession();

The class of this object depends of the driver. For the "db" driver, this will be a DAO record, from the DAO indicated in the configuration of jAuth.

You can know if a user is connected with the method isConnected():

  if (jAuth::isConnected()) {
      // ok, a user is connected
  }

To login the user in a persistant manner (he will be recognized automatically when he go on your application, even if his session has been destroyed), you have to add the true value as third parameter, when calling the login() method.

You can also just verify a login/password, without "connecting" a user :

  $ok = jAuth::verifyPassword('the_login', 'the_password');

Read the reference documentation of jAuth to know about other methods.

To manage user, you have to call jAuth too. To create a user, you need to retrieve an object for the new user, to fill it with some informations if needed, then to ask jAuth to save it.

   // retrieve a new object for the new user
   $newUser = jAuth::createUserObject ('the_login', 'the_password');
   
   //add some information, for example the birthday date.
   $newUser->birthday = '1980-01-01';
   
   // let's register the new user
   $ok = jAuth:saveNewUser($newUser);

To modify informations of a user, you have to retrieve the object corresponding to the user, to modify it, then to ask jAuth to save it.

   $user = jAuth::getUserSession()
   // or
   $user = jAuth::getUser('his_login');

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

   // save
   jAuth::updateUser($user);

Notice: if the modified user is the current connected user, then informations in sessions are also updated.

Don't use this process to modify the password! Because you don't really know how the password is encrypted, or how it is stored. It depends of the jAuth configuration and of the driver. So, to change the password, use the method canChangePassword() and changePassword(). The first one allow to know if the password can be changed. Some authentication protocol, like SAML, oAuth etc, may not allow to change the password, as it is not accessible to the application.

if (jAuth::canChangePassword($login)) {
   jAuth::changePassword($login, 'the_new_password');
}
else {
    $reasonMessage =  jAuth::getReasonToForbiddenPasswordChange();
}

Calling getReasonToForbiddenPasswordChange when canChangePassword() fails, allows to display the reason to the user (method existing since Jelix 1.7.11).

You can use the method jAuth::getRandomPassword() to generate a random password.

To delete a user, use jAuth::removeUser() :

   jAuth::removeUser('his_login');

To retrieve a list of users, use jAuth::getUserList():

   $list = jAuth::getUserList();

The result is an iterator over a list of objects, each objects representing a user (like the object you retrieve with getUser()).

About every jAuth methods emit events. As a result, modules can be aware of authentication status and do some specific action related to user.

• AuthNewUser : a new user has been created
• AuthCanRemoveUser : ask if deletion of a user is allowed
• AuthRemoveUser : a user has been removed
• AuthUpdateUser : current user has been updated
• AuthCanLogin : ask if user can connect
• AuthLogin : a user has logged in
• AuthLogout : a user has logged out
• AuthErrorLogin : a user authentication has failed
• AuthBeforeLogin : apply some process before a user authentication
• AuthChangePassword (since Jelix 1.6.17): the password of a user has changed.

In response to some of these events, you can set some data:

• for AuthCanRemoveUser, set canremove to true or false
• for AuthCanLogin : set canlogin to true or false
• for AuthBeforeLogin : set processlogin to true or false (false to cancel the login)

Exemple of an event handler on "AuthCanRemoveUser":

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

See the chapter about events to know more.