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     auth_validate_form(&$form, &$err)
 125
 126     Validate form data.
 127
 128     Returns:
 129     Bool. Manipulates $form and $err arrays in place
 130
 131
 132 COURSE CREATING
 133
 134     auth_iscreator($username)
 135
 136     should user have rights to create courses
 137
 138     Returns:
 139     True if user have rights to crete cources otherwise false
 140
 141
 142 USER CREATION
 143
 144 Functions that enable usercreation, activation and deactivation
 145 from moodle to external database
 146
 147
 148     auth_user_exists ($username)
 149
 150     Checks if given username exist on external db
 151
 152     Returns:
 153     true if given usernname exist or false
 154
 155     auth_user_create ($userobject,$plainpass)
 156
 157     Creates new user to external db. User should be created
 158     in inactive stage until confirmed by email.
 159
 160     Returns:
 161     True on success otherwise false
 162
 163
 164     auth_user_activate ($username)
 165
 166     activate new user after email-address is confirmed
 167
 168     Returns:
 169     True on success otherwise false
 170
 171
 172     auth_user_disable ($username) {
 173
 174     deactivate  user in external db.
 175
 176     Returns:
 177     True on success otherwise false
 178
 179
 180
 181 USER INFORMATION AND SYNCRONIZATION
 182
 183     auth_get_userlist ()
 184
 185     Get list of usernames in external db.
 186
 187     Returns:
 188     All usernames in array or false on error.
 189
 190
 191     auth_get_users($filter='*')
 192
 193     Get ALL USEROBJECTS FROM EXTERNAL DB.
 194
 195     Returns:
 196     Array of all users as objects from external db
 197
 198