MDL-9861 Password expiration value is calculated wrong when ldap_expirationtime2unix...
[moodle.git] / auth / README.txt
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
109e9581 13
b9ddb2d5 14Multiauthentication in Moodle 1.8
15-------------------------------------
16
17The active methods are set by the admin on the Configuration page. Multiple
18authentication plugins can now be used and ordered in a fail-through sequence.
19One plugin can be selected for interactive login as well (which will need to be
20part of the enabled plugin sequence).
faebaf0f 21
22
23email - authentication by email (DEFAULT METHOD)
24
25 - user fills out form with email address
139ebfdb 26 - email sent to user with link
faebaf0f 27 - user clicks on link in email to confirm
28 - user account is created
29 - user can log in
30
31
32none - no authentication at all .. very insecure!!
139ebfdb 33
faebaf0f 34 - user logs in using ANY username and password
35 - if the username doesn't already exist then
36 a new account is created
139ebfdb 37 - when user tries to access a course they
faebaf0f 38 are forced to set up their account details
39
109e9581 40
41nologin - user can not log in, login as is possible
42
43 - this plugin can be used to prevent normal user login
44
45
88478a66 46manual - internal authentication only
47
48 - user logs in using username and password
49 - no way for user to make their own account
50
faebaf0f 51
52ldap - Uses an external LDAP server
2ee53d15 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
d1b4e172 59
2ee53d15 60 (see the ldap/README for more details on config etc...)
d1b4e172 61
62
63imap - 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
df3988ea 72pop3 - 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
81nntp - 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
d1b4e172 90db - Uses an external database to check username/password
139ebfdb 91
d1b4e172 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
5b06bef1 97
98
b9ddb2d5 99--------------------------------------------------------------------------------
5b06bef1 100
101Authentication API
b9ddb2d5 102------------------
103
109e9581 104
105AUTHENTICATION PLUGINS
106----------------------
b9ddb2d5 107Each authentication plugin is now contained in a subfolder as a class definition
108in the auth.php file. For instance, the LDAP authentication plugin is the class
109called auth_plugin_ldap defined in:
110
111 /auth/ldap/auth.php
112
113To instantiate the class, there is a function in lib/moodlelib called
114get_auth_plugin() that does the work for you:
115
116 $ldapauth = get_auth_plugin('ldap');
117
109e9581 118Auth plugin classes are pretty basic and should be extending auth_plugin_base class.
119They contain the same functions that were previously in each plugin's lib.php file,
120but refactored to become class methods, and tweaked to reference the plugin's instantiated
121config to get at the settings, rather than the global $CFG variable.
122
123When 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
125auth_plugin_base.
b9ddb2d5 126
109e9581 127The new plugin architecture allows creating of more advanced types such as custom SSO
f5fd4347 128without the need to patch login and logout pages (see *_hook() methods in existing plugins).
b9ddb2d5 129
130Configuration
131-----------------
132
133All auth plugins must have a config property that contains the name value pairs
134from the config_plugins table. This is populated using the get_config() function
135in the constructor. The settings keys have also had the "auth_" prefix, as well
136as the auth plugin name, trimmed. For instance, what used to be
137
138 echo $CFG->auth_ldapversion;
139
140is now accessed as
141
142 echo $ldapauth->config->version;
143
144Authentication settings have been moved to the config_plugins database table,
145with the plugin field set to "auth/foo" (for instance, "auth/ldap").
146
b9ddb2d5 147
148Method Names
149-----------------
150
151When the functions from lib.php were ported to methods in auth.php, the "auth_"
152prefix was dropped. For instance, calls to
153
154 auth_user_login($user, $pass);
155
156now become
157
158 $ldapauth->user_login($user, $pass);
159
160this also avoids having to worry about which auth/lib file to include since
161Moodle takes care of it for you when you create an instance with
162get_auth_plugin().
163
109e9581 164The basic class defines all applicable methods that moodle uses, you can find
165more information in lib/authlib.php file.
5b06bef1 166
b9ddb2d5 167
109e9581 168Upgrading from Moodle 1.7
169-----------------------------
b9ddb2d5 170
109e9581 171Moodle will upgrade the old auth settings (in $CFG->auth_foobar where foo is the
172auth plugin and bar is the setting) to the new style in the config_plugin
173database table.