auth/README

   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
  10 used, Moodle still maintains the internal "user" table
  11 with all the associated information about that user such
  12 as name, email address and so on.
  13
  14 The active method is set by the admin on the Configuration page.
  15
  16
  17 email - authentication by email  (DEFAULT METHOD)
  18
  19     - user fills out form with email address
  20     - email sent to user with link
  21     - user clicks on link in email to confirm
  22     - user account is created
  23     - user can log in
  24
  25
  26 none  - no authentication at all .. very insecure!!
  27
  28     - user logs in using ANY username and password
  29     - if the username doesn't already exist then
  30       a new account is created
  31     - when user tries to access a course they
  32       are forced to set up their account details
  33
  34 manual - internal authentication only
  35
  36     - user logs in using username and password
  37     - no way for user to make their own account
  38
  39
  40 ldap  - Uses an external LDAP server
  41
  42     - user logs in using username and password
  43     - these are checked against an LDAP server
  44     - if correct, user is logged in
  45     - optionally, info is copied from the LDAP
  46       database to the Moodle user database
  47
  48     (see the ldap/README for more details on config etc...)
  49
  50
  51 imap  - Uses an external IMAP server
  52
  53     - user logs in using username and password
  54     - these are checked against an IMAP server
  55     - if correct, user is logged in
  56     - if the username doesn't already exist then
  57       a new account is created
  58
  59
  60 pop3  - Uses an external POP3 server
  61
  62     - user logs in using username and password
  63     - these are checked against a POP3 server
  64     - if correct, user is logged in
  65     - if the username doesn't already exist then
  66       a new account is created
  67
  68
  69 nntp  - Uses an external NNTP server
  70
  71     - user logs in using username and password
  72     - these are checked against an NNTP server
  73     - if correct, user is logged in
  74     - if the username doesn't already exist then
  75       a new account is created
  76
  77
  78 db  - Uses an external database to check username/password
  79
  80     - user logs in using username and password
  81     - these are checked against an external database
  82     - if correct, user is logged in
  83     - if the username doesn't already exist then
  84       a new Moodle account is created
  85
  86
  87 ------------------------------------------------------------------------------------
  88
  89 Authentication API
  90
  91 This file describes Moodle interface functions to authentication modules.
  92
  93 Most of functions are from ldap-authentication module and are not implemented (yet?)
  94 on other modules. Please feel free to extend other modules to support same features
  95 or roll your own module.
  96
  97 Some of new function are still tested and are not documented here yet.
  98
  99
 100
 101 AUTHENTICATION
 102 Basic fuctions to authenticate users with external db
 103
 104 Mandatory:
 105
 106     auth_user_login ($username, $password)
 107
 108     Authenticate username, password with userdatabase.
 109
 110     Returns:
 111     true if the username and password work
 112     and false if they don't
 113
 114 Optional:
 115
 116     auth_get_userinfo($username)
 117
 118     Query other userinformation from database.
 119
 120     Returns:
 121     Userinformation in array ( name => value, ....
 122     or false in case of error
 123
 124 COURSE CREATING
 125
 126     auth_iscreator($username)
 127
 128     should user have rights to create courses
 129
 130     Returns:
 131     True if user have rights to crete cources otherwise false
 132
 133
 134 USER CREATION
 135
 136 Functions that enable usercreation, activation and deactivation
 137 from moodle to external database
 138
 139
 140     auth_user_exists ($username)
 141
 142     Checks if given username exist on external db
 143
 144     Returns:
 145     true if given usernname exist or false
 146
 147     auth_user_create ($userobject,$plainpass)
 148
 149     Creates new user to external db. User should be created
 150     in inactive stage until confirmed by email.
 151
 152     Returns:
 153     True on success otherwise false
 154
 155
 156     auth_user_activate ($username)
 157
 158     activate new user after email-address is confirmed
 159
 160     Returns:
 161     True on success otherwise false
 162
 163
 164     auth_user_disable ($username) {
 165
 166     deactivate  user in external db.
 167
 168     Returns:
 169     True on success otherwise false
 170
 171
 172
 173 USER INFORMATION AND SYNCRONIZATION
 174
 175     auth_get_userlist ()
 176
 177     Get list of usernames in external db.
 178
 179     Returns:
 180     All usernames in array or false on error.
 181
 182
 183     auth_get_users($filter='*')
 184
 185     Get ALL USEROBJECTS FROM EXTERNAL DB.
 186
 187     Returns:
 188     Array of all users as objects from external db
 189
 190