README2

AUTHENTICATION PLUGINS
----------------------
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").

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 Use
-----------------

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.

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

get_userinfo()
   This method should return an array of fields from the authentication source
   for the given username.

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.