[Summary view] [Print] [Text view]

   1  This directory contains authentication modules.
   2  
   3  Each of these modules describes a different way to
   4  check that a user has provided a correct
   5  
   6     - username, and
   7     - password.
   8  
   9  Even when external forms of authentication are being used, Moodle still
  10  maintains the internal "user" table with all the associated information about
  11  that user such as name, email address and so on.
  12  
  13  
  14  Multiauthentication in Moodle 1.8
  15  -------------------------------------
  16  
  17  The active methods are set by the admin on the Configuration page. Multiple
  18  authentication plugins can now be used and ordered in a fail-through sequence.
  19  One plugin can be selected for interactive login as well (which will need to be
  20  part of the enabled plugin sequence).
  21  
  22  
  23  email - authentication by email  (DEFAULT METHOD)
  24  
  25      - user fills out form with email address
  26      - email sent to user with link
  27      - user clicks on link in email to confirm
  28      - user account is created
  29      - user can log in
  30  
  31  
  32  none  - no authentication at all .. very insecure!!
  33  
  34      - user logs in using ANY username and password
  35      - if the username doesn't already exist then
  36        a new account is created
  37      - when user tries to access a course they
  38        are forced to set up their account details
  39  
  40  
  41  nologin  - user can not log in, login as is possible
  42  
  43      - this plugin can be used to prevent normal user login
  44  
  45  
  46  manual - internal authentication only
  47  
  48      - user logs in using username and password
  49      - no way for user to make their own account
  50  
  51  
  52  ldap  - Uses an external LDAP server
  53  
  54      - user logs in using username and password
  55      - these are checked against an LDAP server
  56      - if correct, user is logged in
  57      - optionally, info is copied from the LDAP
  58        database to the Moodle user database
  59  
  60      (see the ldap/README for more details on config etc...)
  61  
  62  
  63  imap  - Uses an external IMAP server
  64  
  65      - user logs in using username and password
  66      - these are checked against an IMAP server
  67      - if correct, user is logged in
  68      - if the username doesn't already exist then
  69        a new account is created
  70  
  71  
  72  pop3  - Uses an external POP3 server
  73  
  74      - user logs in using username and password
  75      - these are checked against a POP3 server
  76      - if correct, user is logged in
  77      - if the username doesn't already exist then
  78        a new account is created
  79  
  80  
  81  nntp  - Uses an external NNTP server
  82  
  83      - user logs in using username and password
  84      - these are checked against an NNTP server
  85      - if correct, user is logged in
  86      - if the username doesn't already exist then
  87        a new account is created
  88  
  89  
  90  db  - Uses an external database to check username/password
  91  
  92      - user logs in using username and password
  93      - these are checked against an external database
  94      - if correct, user is logged in
  95      - if the username doesn't already exist then
  96        a new Moodle account is created
  97  
  98  
  99  --------------------------------------------------------------------------------
 100  
 101  Authentication API
 102  ------------------
 103  
 104  
 105  AUTHENTICATION PLUGINS
 106  ----------------------
 107  Each authentication plugin is now contained in a subfolder as a class definition
 108  in the auth.php file. For instance, the LDAP authentication plugin is the class
 109  called auth_plugin_ldap defined in:
 110  
 111     /auth/ldap/auth.php
 112  
 113  To instantiate the class, there is a function in lib/moodlelib called
 114  get_auth_plugin() that does the work for you:
 115  
 116     $ldapauth = get_auth_plugin('ldap');
 117  
 118  Auth plugin classes are pretty basic and should be extending auth_plugin_base class.
 119  They contain the same functions that were previously in each plugin's lib.php file,
 120  but refactored to become class methods, and tweaked to reference the plugin's instantiated
 121  config to get at the settings, rather than the global $CFG variable.
 122  
 123  When creating new plugins you can either extend the abstract auth_plugin_base class
 124  (defined in lib/authlib.php) or create a new one and implement all methods from
 125  auth_plugin_base.
 126  
 127  The new plugin architecture allows creating of more advanced types such as custom SSO
 128  without the need to patch login and logout pages (see *_hook() methods in existing plugins).
 129  
 130  Configuration
 131  -----------------
 132  
 133  All auth plugins must have a config property that contains the name value pairs
 134  from the config_plugins table. This is populated using the get_config() function
 135  in the constructor. The settings keys have also had the "auth_" prefix, as well
 136  as the auth plugin name, trimmed. For instance, what used to be
 137  
 138     echo $CFG->auth_ldapversion;
 139  
 140  is now accessed as
 141  
 142     echo $ldapauth->config->version;
 143  
 144  Authentication settings have been moved to the config_plugins database table,
 145  with the plugin field set to "auth/foo" (for instance, "auth/ldap").
 146  
 147  
 148  Method Names
 149  -----------------
 150  
 151  When the functions from lib.php were ported to methods in auth.php, the "auth_"
 152  prefix was dropped. For instance, calls to
 153  
 154     auth_user_login($user, $pass);
 155  
 156  now become
 157  
 158     $ldapauth->user_login($user, $pass);
 159  
 160  this also avoids having to worry about which auth/lib file to include since
 161  Moodle takes care of it for you when you create an instance with
 162  get_auth_plugin().
 163  
 164  The basic class defines all applicable methods that moodle uses, you can find
 165  more information in lib/authlib.php file.
 166  
 167  
 168  Upgrading from Moodle 1.7
 169  -----------------------------
 170  
 171  Moodle will upgrade the old auth settings (in $CFG->auth_foobar where foo is the
 172  auth plugin and bar is the setting) to the new style in the config_plugin
 173  database table.
 174  
 175  
 176  
 177  Upgrading from Moodle 1.8
 178  ------------------------------
 179  
 180  user_activate() method was removed from public API because it was used only from user_confirm() in LDAP