MDL-50925 auth_nntp: Remove from core and into plugins DB
[moodle.git] / auth / README.txt
1 This directory contains authentication modules.
3 Each of these modules describes a different way to
4 check that a user has provided a correct
6    - username, and
7    - password.
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.
14 Multiauthentication in Moodle 1.8
15 -------------------------------------
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).
23 email - authentication by email  (DEFAULT METHOD)
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
32 none  - no authentication at all .. very insecure!!
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
41 nologin  - user can not log in, login as is possible
43     - this plugin can be used to prevent normal user login
46 manual - internal authentication only
48     - user logs in using username and password
49     - no way for user to make their own account
52 ldap  - Uses an external LDAP server
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
60     (see the ldap/README for more details on config etc...)
63 imap  - Uses an external IMAP server
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
72 pop3  - Uses an external POP3 server
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
81 db  - Uses an external database to check username/password
83     - user logs in using username and password
84     - these are checked against an external database
85     - if correct, user is logged in
86     - if the username doesn't already exist then
87       a new Moodle account is created
90 --------------------------------------------------------------------------------
92 Authentication API
93 ------------------
96 AUTHENTICATION PLUGINS
97 ----------------------
98 Each authentication plugin is now contained in a subfolder as a class definition
99 in the auth.php file. For instance, the LDAP authentication plugin is the class
100 called auth_plugin_ldap defined in:
102    /auth/ldap/auth.php
104 To instantiate the class, there is a function in lib/moodlelib called
105 get_auth_plugin() that does the work for you:
107    $ldapauth = get_auth_plugin('ldap');
109 Auth plugin classes are pretty basic and should be extending auth_plugin_base class.
110 They contain the same functions that were previously in each plugin's lib.php file,
111 but refactored to become class methods, and tweaked to reference the plugin's instantiated
112 config to get at the settings, rather than the global $CFG variable.
114 When creating new plugins you can either extend the abstract auth_plugin_base class
115 (defined in lib/authlib.php) or create a new one and implement all methods from
116 auth_plugin_base.
118 The new plugin architecture allows creating of more advanced types such as custom SSO
119 without the need to patch login and logout pages (see *_hook() methods in existing plugins).
121 Configuration
122 -----------------
124 All auth plugins must have a config property that contains the name value pairs
125 from the config_plugins table. This is populated using the get_config() function
126 in the constructor. The settings keys have also had the "auth_" prefix, as well
127 as the auth plugin name, trimmed. For instance, what used to be
129    echo $CFG->auth_ldapversion;
131 is now accessed as
133    echo $ldapauth->config->version;
135 Authentication settings have been moved to the config_plugins database table,
136 with the plugin field set to "auth/foo" (for instance, "auth/ldap").
139 Method Names
140 -----------------
142 When the functions from lib.php were ported to methods in auth.php, the "auth_"
143 prefix was dropped. For instance, calls to
145    auth_user_login($user, $pass);
147 now become
149    $ldapauth->user_login($user, $pass);
151 this also avoids having to worry about which auth/lib file to include since
152 Moodle takes care of it for you when you create an instance with
153 get_auth_plugin().
155 The basic class defines all applicable methods that moodle uses, you can find
156 more information in lib/authlib.php file.
159 Upgrading from Moodle 1.7
160 -----------------------------
162 Moodle will upgrade the old auth settings (in $CFG->auth_foobar where foo is the
163 auth plugin and bar is the setting) to the new style in the config_plugin
164 database table.
168 Upgrading from Moodle 1.8
169 ------------------------------
171 user_activate() method was removed from public API because it was used only from user_confirm() in LDAP