MDL-8922 More work on fixing RSS block XHTML
[moodle.git] / auth / README
CommitLineData
faebaf0f 1This directory contains authentication modules.
2
139ebfdb 3Each of these modules describes a different way to
4check that a user has provided a correct
faebaf0f 5
139ebfdb 6 - username, and
faebaf0f 7 - password.
8
b9ddb2d5 9Even when external forms of authentication are being used, Moodle still
10maintains the internal "user" table with all the associated information about
11that user such as name, email address and so on.
faebaf0f 12
b9ddb2d5 13Multiauthentication in Moodle 1.8
14-------------------------------------
15
16The active methods are set by the admin on the Configuration page. Multiple
17authentication plugins can now be used and ordered in a fail-through sequence.
18One plugin can be selected for interactive login as well (which will need to be
19part of the enabled plugin sequence).
faebaf0f 20
21
22email - authentication by email (DEFAULT METHOD)
23
24 - user fills out form with email address
139ebfdb 25 - email sent to user with link
faebaf0f 26 - user clicks on link in email to confirm
27 - user account is created
28 - user can log in
29
30
31none - no authentication at all .. very insecure!!
139ebfdb 32
faebaf0f 33 - user logs in using ANY username and password
34 - if the username doesn't already exist then
35 a new account is created
139ebfdb 36 - when user tries to access a course they
faebaf0f 37 are forced to set up their account details
38
88478a66 39manual - internal authentication only
40
41 - user logs in using username and password
42 - no way for user to make their own account
43
faebaf0f 44
45ldap - Uses an external LDAP server
2ee53d15 46
47 - user logs in using username and password
48 - these are checked against an LDAP server
49 - if correct, user is logged in
50 - optionally, info is copied from the LDAP
51 database to the Moodle user database
d1b4e172 52
2ee53d15 53 (see the ldap/README for more details on config etc...)
d1b4e172 54
55
56imap - Uses an external IMAP server
57
58 - user logs in using username and password
59 - these are checked against an IMAP server
60 - if correct, user is logged in
61 - if the username doesn't already exist then
62 a new account is created
63
64
df3988ea 65pop3 - Uses an external POP3 server
66
67 - user logs in using username and password
68 - these are checked against a POP3 server
69 - if correct, user is logged in
70 - if the username doesn't already exist then
71 a new account is created
72
73
74nntp - Uses an external NNTP server
75
76 - user logs in using username and password
77 - these are checked against an NNTP server
78 - if correct, user is logged in
79 - if the username doesn't already exist then
80 a new account is created
81
82
d1b4e172 83db - Uses an external database to check username/password
139ebfdb 84
d1b4e172 85 - user logs in using username and password
86 - these are checked against an external database
87 - if correct, user is logged in
88 - if the username doesn't already exist then
89 a new Moodle account is created
5b06bef1 90
91
b9ddb2d5 92--------------------------------------------------------------------------------
5b06bef1 93
94Authentication API
b9ddb2d5 95------------------
96
97Each authentication plugin is now contained in a subfolder as a class definition
98in the auth.php file. For instance, the LDAP authentication plugin is the class
99called auth_plugin_ldap defined in:
100
101 /auth/ldap/auth.php
102
103To instantiate the class, there is a function in lib/moodlelib called
104get_auth_plugin() that does the work for you:
105
106 $ldapauth = get_auth_plugin('ldap');
107
108If an auth is not specified, get_auth_plugin() will return you the auth plugin
109defined in the $CFG->auth variable.
110
111Auth plugin classes are pretty basic. They contain the same functions that were
112previously in each plugin's lib.php file, but refactored to become class
113methods, and tweaked to reference the plugin's instantiated config to get at the
114settings, rather than the global $CFG variable.
115
116Configuration
117-----------------
118
119All auth plugins must have a config property that contains the name value pairs
120from the config_plugins table. This is populated using the get_config() function
121in the constructor. The settings keys have also had the "auth_" prefix, as well
122as the auth plugin name, trimmed. For instance, what used to be
123
124 echo $CFG->auth_ldapversion;
125
126is now accessed as
127
128 echo $ldapauth->config->version;
129
130Authentication settings have been moved to the config_plugins database table,
131with the plugin field set to "auth/foo" (for instance, "auth/ldap").
132
133Upgrading from Moodle 1.7
134-----------------------------
135
136Moodle will upgrade the old auth settings (in $CFG->auth_foobar where foo is the
137auth plugin and bar is the setting) to the new style in the config_plugin
138database table.
139
140Method Names
141-----------------
142
143When the functions from lib.php were ported to methods in auth.php, the "auth_"
144prefix was dropped. For instance, calls to
145
146 auth_user_login($user, $pass);
147
148now become
149
150 $ldapauth->user_login($user, $pass);
151
152this also avoids having to worry about which auth/lib file to include since
153Moodle takes care of it for you when you create an instance with
154get_auth_plugin().
155
156Code Usage
157-----------------
158
159Code calling auth plugins can use method_exists() to determine plugin
160functionality, much in the same way that function_exists() was used until now.
161In addition, auth plugins provide some methods by default that can be called:
162
163user_login($username, $password)
164 This is the primary method that is used by the authenticate_user_login()
165 function in moodlelib.php. This method should return a boolean indicating
166 whether or not the username and password authenticate successfully.
167
168is_internal()
169 Returns true if this authentication plugin is "internal" (which means that
170 Moodle stores the users' passwords and other details in the local Moodle
171 database).
172
173can_change_password()
174 Returns true if the plugin can change the users' passwords.
175
176change_password_url()
177 Returns the URL for changing the users' passwords, or false if the default
178 URL can be used.
179
fb5c7739 180user_update_password($user, $newpassword)
181 Updates the user's password. In previous versions of Moodle, the function
182 auth_user_update_password accepted a username as the first parameter. The
183 revised function expects a user object.
5b06bef1 184
b9ddb2d5 185config_form()
186 Displays the configuration form for the auth plugin, for use in the admin
187 pages.
5b06bef1 188
b9ddb2d5 189process_config()
190 Saves the auth plugin's configuration to the database.
5b06bef1 191
b9ddb2d5 192Other Methods
193------------------
5b06bef1 194
b9ddb2d5 195Most of functions are from ldap-authentication module and are not implemented
196(yet?) on other modules. Please feel free to extend other modules to support
197same features or roll your own module.
5b06bef1 198
b9ddb2d5 199Some of the new functions are still to be tested and are not documented here
200yet.
5b06bef1 201
202AUTHENTICATION
b9ddb2d5 203
204Basic fuctions to authenticate users with external db.
5b06bef1 205
139ebfdb 206Mandatory:
b9ddb2d5 207
208 auth_plugin_foo()
209
210 Constructor. At the least, it populates config member variable with settings
211 from the Moodle database. It makes sense to put other startup code here.
212
139ebfdb 213 user_login($username, $password)
b9ddb2d5 214
5b06bef1 215 Authenticate username, password with userdatabase.
216
217 Returns:
218 true if the username and password work
219 and false if they don't
220
221Optional:
b9ddb2d5 222
223 get_userinfo($username)
224
5b06bef1 225 Query other userinformation from database.
226
227 Returns:
139ebfdb 228 Userinformation in array ( name => value, ....
5b06bef1 229 or false in case of error
230
b9ddb2d5 231
232 validate_form(&$form, &$err)
233
1590773b 234 Validate form data.
235
236 Returns:
237 Bool. Manipulates $form and $err arrays in place
238
239
5b06bef1 240COURSE CREATING
241
b9ddb2d5 242 iscreator($username)
5b06bef1 243
244 should user have rights to create courses
245
246 Returns:
247 True if user have rights to crete cources otherwise false
248
249
250USER CREATION
251
252Functions that enable usercreation, activation and deactivation
253from moodle to external database
139ebfdb 254
255
256 user_exists ($username)
b9ddb2d5 257
5b06bef1 258 Checks if given username exist on external db
259
260 Returns:
261 true if given usernname exist or false
b9ddb2d5 262
263
139ebfdb 264 user_create ($userobject,$plainpass)
b9ddb2d5 265
5b06bef1 266 Creates new user to external db. User should be created
267 in inactive stage until confirmed by email.
268
269 Returns:
270 True on success otherwise false
271
272
139ebfdb 273 user_activate ($username)
b9ddb2d5 274
5b06bef1 275 activate new user after email-address is confirmed
276
277 Returns:
278 True on success otherwise false
279
280
b9ddb2d5 281 user_disable ($username) {
282
5b06bef1 283 deactivate user in external db.
b9ddb2d5 284
5b06bef1 285 Returns:
286 True on success otherwise false
287
288
289
290USER INFORMATION AND SYNCRONIZATION
291
b9ddb2d5 292 get_userlist ()
5b06bef1 293
294 Get list of usernames in external db.
295
296 Returns:
297 All usernames in array or false on error.
5b06bef1 298
b9ddb2d5 299