This directory contains authentication modules.

Each of these modules describes a different way to
check that a user has provided a correct

   - username, and
   - password.

Even when external forms of authentication are being used, Moodle still
maintains the internal "user" table with all the associated information about
that user such as name, email address and so on.

Multiauthentication in Moodle 1.8
-------------------------------------

The active methods are set by the admin on the Configuration page. Multiple
authentication plugins can now be used and ordered in a fail-through sequence.
One plugin can be selected for interactive login as well (which will need to be
part of the enabled plugin sequence).


email - authentication by email  (DEFAULT METHOD)

    - user fills out form with email address
    - email sent to user with link
    - user clicks on link in email to confirm
    - user account is created
    - user can log in


none  - no authentication at all .. very insecure!!

    - user logs in using ANY username and password
    - if the username doesn't already exist then
      a new account is created
    - when user tries to access a course they
      are forced to set up their account details

manual - internal authentication only

    - user logs in using username and password
    - no way for user to make their own account


ldap  - Uses an external LDAP server

    - user logs in using username and password
    - these are checked against an LDAP server
    - if correct, user is logged in
    - optionally, info is copied from the LDAP
      database to the Moodle user database

    (see the ldap/README for more details on config etc...)


imap  - Uses an external IMAP server

    - user logs in using username and password
    - these are checked against an IMAP server
    - if correct, user is logged in
    - if the username doesn't already exist then
      a new account is created


pop3  - Uses an external POP3 server

    - user logs in using username and password
    - these are checked against a POP3 server
    - if correct, user is logged in
    - if the username doesn't already exist then
      a new account is created


nntp  - Uses an external NNTP server

    - user logs in using username and password
    - these are checked against an NNTP server
    - if correct, user is logged in
    - if the username doesn't already exist then
      a new account is created


db  - Uses an external database to check username/password

    - user logs in using username and password
    - these are checked against an external database
    - if correct, user is logged in
    - if the username doesn't already exist then
      a new Moodle account is created


--------------------------------------------------------------------------------

Authentication API
------------------

Each authentication plugin is now contained in a subfolder as a class definition
in the auth.php file. For instance, the LDAP authentication plugin is the class
called auth_plugin_ldap defined in:

   /auth/ldap/auth.php

To instantiate the class, there is a function in lib/moodlelib called
get_auth_plugin() that does the work for you:

   $ldapauth = get_auth_plugin('ldap');

If an auth is not specified, get_auth_plugin() will return you the auth plugin
defined in the $CFG->auth variable.

Auth plugin classes are pretty basic. They contain the same functions that were
previously in each plugin's lib.php file, but refactored to become class
methods, and tweaked to reference the plugin's instantiated config to get at the
settings, rather than the global $CFG variable.

Configuration
-----------------

All auth plugins must have a config property that contains the name value pairs
from the config_plugins table. This is populated using the get_config() function
in the constructor. The settings keys have also had the "auth_" prefix, as well
as the auth plugin name, trimmed. For instance, what used to be

   echo $CFG->auth_ldapversion;

is now accessed as

   echo $ldapauth->config->version;

Authentication settings have been moved to the config_plugins database table,
with the plugin field set to "auth/foo" (for instance, "auth/ldap").

Upgrading from Moodle 1.7
-----------------------------

Moodle will upgrade the old auth settings (in $CFG->auth_foobar where foo is the
auth plugin and bar is the setting) to the new style in the config_plugin
database table.

Method Names
-----------------

When the functions from lib.php were ported to methods in auth.php, the "auth_"
prefix was dropped. For instance, calls to

   auth_user_login($user, $pass);

now become

   $ldapauth->user_login($user, $pass);

this also avoids having to worry about which auth/lib file to include since
Moodle takes care of it for you when you create an instance with
get_auth_plugin().

Code Usage
-----------------

Code calling auth plugins can use method_exists() to determine plugin
functionality, much in the same way that function_exists() was used until now.
In addition, auth plugins provide some methods by default that can be called:

user_login($username, $password)
   This is the primary method that is used by the authenticate_user_login()
   function in moodlelib.php. This method should return a boolean indicating
   whether or not the username and password authenticate successfully.

is_internal()
   Returns true if this authentication plugin is "internal" (which means that
   Moodle stores the users' passwords and other details in the local Moodle
   database).

can_change_password()
   Returns true if the plugin can change the users' passwords.

change_password_url()
   Returns the URL for changing the users' passwords, or false if the default
   URL can be used.

user_update_password($user, $newpassword)
   Updates the user's password. In previous versions of Moodle, the function
   auth_user_update_password accepted a username as the first parameter. The
   revised function expects a user object.

config_form()
   Displays the configuration form for the auth plugin, for use in the admin
   pages.

process_config()
   Saves the auth plugin's configuration to the database.

Other Methods
------------------

Most of functions are from ldap-authentication module and are not implemented
(yet?) on other modules. Please feel free to extend other modules to support
same features or roll your own module.

Some of the new functions are still to be tested and are not documented here
yet.

AUTHENTICATION

Basic fuctions to authenticate users with external db.

Mandatory:

    auth_plugin_foo()

    Constructor. At the least, it populates config member variable with settings
    from the Moodle database. It makes sense to put other startup code here.

    user_login($username, $password)

    Authenticate username, password with userdatabase.

    Returns:
    true if the username and password work
    and false if they don't

Optional:

    get_userinfo($username)

    Query other userinformation from database.

    Returns:
    Userinformation in array ( name => value, ....
    or false in case of error


    validate_form(&$form, &$err)

    Validate form data.

    Returns:
    Bool. Manipulates $form and $err arrays in place


COURSE CREATING

    iscreator($username)

    should user have rights to create courses

    Returns:
    True if user have rights to crete cources otherwise false


USER CREATION

Functions that enable usercreation, activation and deactivation
from moodle to external database


    user_exists ($username)

    Checks if given username exist on external db

    Returns:
    true if given usernname exist or false


    user_create ($userobject,$plainpass)

    Creates new user to external db. User should be created
    in inactive stage until confirmed by email.

    Returns:
    True on success otherwise false


    user_activate ($username)

    activate new user after email-address is confirmed

    Returns:
    True on success otherwise false


    user_disable ($username) {

    deactivate  user in external db.

    Returns:
    True on success otherwise false



USER INFORMATION AND SYNCRONIZATION

    get_userlist ()

    Get list of usernames in external db.

    Returns:
    All usernames in array or false on error.