3 !!! The new phpwiki user authentification and preferences settings
5 A typical wiki needs no authentification, some wiki's support a so called
6 "Bogo" login, where the username is a wikiword and therefore any note on any page
7 (typically ended with "--UserName") is automatically linked to the users homepage
9 PhpWiki supported anonymous edits from the beginning,
10 non-anonymous edits, with required BogoLogin since version ???
11 and true user identification with required username and passwords since 1.3.4,
12 where the optional password was stored in the users HomePage metadata.
13 Seperately PhpWiki could be hacked to be protected by HTTP Auth
14 (e.g. Apache's .htaccess <require>), the username would then be
15 $PHP_AUTH_USER and the password not needed.
17 Since version 1.3.4 ReiniUrban was working on UserAuthentificationNew
18 to support authentification against external sources also, such as a
19 mysql database, LDAP or IMAP or .htaccess like files.
20 From version 1.3.4 to 1.3.7 only HTTP Auth, LDAP, and IMAP was supported,
21 the configuration settings for the planned (and already written) DbAuth code
22 was in index.php, but it was never enabled (which probably lead to some confusion).
23 Since version 1.3.8 UserAuthentificationNew is enabled.
25 We have to seperate various storage methods for UserPreferences
26 (cookie, PersonalPage and database), various retrieval methods for
27 username-password pairs (AuthMethods) and various AuthPolicies.
29 !! New constants and variables:
30 * ALLOW_ANON_USER default: true
31 * ALLOW_ANON_EDIT default: true
32 * ALLOW_BOGO_LOGIN default: true
33 * ALLOW_USER_PASSWORDS default: true
34 * PASSWORD_LENGTH_MINIMUM default: 6
35 * $USER_AUTH_ORDER~[~] default: ("PersonalPage","Db")
36 * USER_AUTH_POLICY default: "old"
37 * $DBAuthParams~[~] see below
40 ; ENABLE_USER_NEW : This will be removed with the 1.3.9 release.
41 ;: It's just to decide if ~WikiUserNew.php should be loaded instead of the old ~WikiUser.php
45 To establish a COMPLETELY private wiki, such as an internal corporate one
46 set ALLOW_ANON_USER = false, and probably require user passwords as described below.
47 In this case the user will be prompted to login immediately upon accessing
48 any page. This is similar to HttpAuth.
52 This feature was called REQUIRE_SIGNIN_BEFORE_EDIT before. To enable
53 ALLOW_BOGO_LOGIN and/or ALLOW_USER_PASSWORDS, ALLOW_ANON_EDIT must be
54 false, otherwise it will override ALLOW_BOGO_LOGIN and
55 ALLOW_USER_PASSWORDS. This will go away, with true page permissions.
59 If ALLOW_BOGO_LOGIN is true, users are allowed to login (with
60 any/no password) using any userid which:
61 1) is not the ADMIN_USER, and
62 2) is a valid WikiWord (matches $WikiNameRegexp.)
64 If true, users may be created by themselves. Otherwise we need
65 seperate ALLOW_USER_PASSWORDS auth. If such a user will create a so
66 called HomePage named after his WikiWord userid, he will be able to
67 store his preferences and password there.
68 If ALLOW_ANON_EDIT = true, one may still sign in to be able to store
69 UserPreferences and named RecentChanges entries.
70 PASSWORD_LENGTH_MINIMUM is ignored by bogo login attempts.
71 If an empty password is used, any user can sign in with this userid.
73 ! REQUIRE_SIGNIN_BEFORE_EDIT (Legacy)
75 If set, then if an anonymous user attempts to edit a page he will
76 be required to sign in. This constant was replaced by ALLOW_ANON_EDIT in v1.3.8.
77 If ALLOW_BOGO_LOGIN is true, of course, no password is required, but the user
78 must still sign in under some sort of WikiWord name. This will go away,
79 with true page permissions.
81 ! ALLOW_USER_PASSWORDS
83 True User Authentification is used with Bogo Login and not-empty
84 passwords or ALLOW_USER_PASSWORDS = true.
86 To require user passwords set
88 ALLOW_ANON_EDIT = false
89 ALLOW_BOGO_LOGIN = false
90 ALLOW_USER_PASSWORDS = true
92 Otherwise any anon or bogo user might login without any or a wrong
93 password. A login attempt with ALLOW_USER_PASSWORDS = true depends on
94 the defined USER_AUTH_ORDER auth methods, the USER_AUTH_POLICY and
95 PASSWORD_LENGTH_MINIMUM.
97 !! FAQ - UPGRADE PROBLEMS:
99 * ''Fatal error: The script tried to execute a method or access a
100 property of an incomplete object. Please ensure that the class
101 definition wikiuser of the object you are trying to operate on was
102 loaded _before_ the session was started in...''
104 This error will appear you switch from old (or from new to old) in the
105 same browser session. You have an old (or new) WikiUser object in your
106 current session, which is incompatible with the new (or old) WikiUser
107 object on session restauration.
109 Workaround: Close and open your browser again. The session cookie
110 should be destroyed, and you will get a fresh new WikiUser
111 object. Your default WIKI_ID (your username) will not be lost.
113 * ''lib\Template.php:22: Warning[2]: fopen("", "rb") - No such file or directory''
115 PHPWIKI_DIR could not be determined automatically. You probably
116 started from a different diretory.
118 Workaround: Set PHPWIKI_DIR in index.php or in your start script. You
119 most likely have to set DATA_PATH also, when your pages look like the
120 ancient-style Wiki (Times-Roman, black-white), i.e. no CSS is loaded.
123 Below we define which methods exists and in which order theys are used:
125 !! USER_AUTH_ORDER auth methods
127 $USER_AUTH_ORDER is an array of the following strings. You can
128 en-/disable any and change the order.
130 * __~BogoLogin__: This will eventually replace the old ALLOW_BOGO_LOGIN constant,
131 but it will require PASSWORD_LENGTH_MINIMUM. So non-empty passwords can be disabled.
132 * __~PersonalPage__: Store passwords in the users homepage metadata (simple)
133 * __Db__: Use $DBAuthParams~[~] (see below) with PearDB or ADODB only.
134 If 'auth_dsn' is undefined, and wiki pages are stored via SQL or ADODB,
135 it uses the same database. (fastest)
136 * __LDAP__: Authenticate against LDAP_AUTH_HOST with the LDAP_AUTH_SEARCH settings
137 * __IMAP__: Authenticate against IMAP_AUTH_HOST (e.g. an existing email account)
138 * __POP3__: Authenticate against POP3_AUTH_HOST (e.g. an existing email account)
139 * __File__: Check username:crypted-passwords in .htaccess like files.
140 Use e.g. Apache's htpasswd program to manage this file.
141 * __~HttpAuth__: Use the protection by the webserver, either .htaccess or httpd.conf
142 If no HTTP AUTH is enforced by the webserver (e.g no require valid-user), then
143 this method will enforce error 401 to force the client to display a password
146 Each method is a WikiUser (in fact a ~_PassUser) class, which defines the checkPass() and
147 userExists() methods and optionally mayChangePass() and storePass().
151 The available policies defines how and when each auth method from
152 USER_AUTH_ORDER is tried, and what to do on failure. Some policies
153 require to know it at advance at initialization time, some have to
154 check if a valid user exists and some simply check valid username -
157 ;__old__: This policy checks all default USER_AUTH_ORDER methods, disables all not defined services (ldap, imap) and tries to use all available methods as in the previous PhpWiki releases with the stacked policy (slow).
158 ;__first-only__: use only the first method in USER_AUTH_ORDER
159 ;__strict__: check if the user exists for all methods: on the first existing user, try the password. dont try the other methods on failure then
160 ;__stacked__: check the given user - password combination for all methods and return true on the first success.
162 ! AUTH_FILE_* constants
168 Statements for seperate DB User Authentication.
170 This array defines the database prepare statements to select and
171 update the password and preferences. This is typically used to
172 interface with other applications or user databases in quasi secure
173 wiki's. (often so called "Content Management Systems").
174 The database can be external like radius, phpnuke, courier authmysql,
175 apache auth_mysql or just a simple user table within phpwiki.
176 The most likely auth_dsn option is the same dsn as the wikipages, in
177 fact if it's empty $DBParams~['dsn'~] is used. If
178 $DBParams~['db_type'~] is not ADODB, the Pear DB library is used
181 This is the list of the available options and some examples. For the statements we use the following symbolic variables:
183 $password : plain or encrypted password
184 $pref_blob : serialized string of the PHP preferences array (may get large, but not too large. 128 - 1024. mysql TEXT is enough)
185 $groupname : groupname
187 Note: The symbolic variables (like "$password", ...) must be enclosed in double quotes!
188 ADODB Warning: With ADODB we must currently define the correct alias names: SELECT db_column as name
189 This requirement will go away when we switch to FETCH_ROW instead of the slower FETCH_ASSOC
190 (scheduled for 1.4.0)
192 ;auth_dsn: 'mysql://user@password:localhost/phpwiki'
196 ;auth_crypt_method: 'crypt' (simple unix crypt, not md5 crypt, sha1 or else) or 'plain' (also for mysql md5)
198 ;auth_check: needs "$password" and "$userid", returns ok with plain or the password with crypt
200 'auth_crypt_method' = 'plain':
201 'SELECT IF(passwd="$password",1,0) as ok FROM user WHERE username="$userid"' or
202 'SELECT IF(passwd=PASSWORD("$password"),1,0) as ok FROM user WHERE username="$userid"',
204 'auth_crypt_method' = 'crypt':
205 'SELECT password as password FROM user WHERE username="$userid"',
207 auth_user_exists is only needed with auth_crypt_method = plain and USER_AUTH_POLICY = stacked or old:
208 ;auth_user_exists: 'SELECT username as userid FROM user WHERE username="$userid"'
210 ;auth_update: 'UPDATE user SET password="$password" WHERE username="$userid"' or
211 'UPDATE user SET password=PASSWORD("$password") WHERE username="$userid"'
212 ;user_create: 'INSERT INTO user SET username="$userid", password="$password", pref="$pref_blob"'
214 If auth_update is not defined but auth_check is defined, the user
215 cannot change his password. But then better crypt methods may be used
216 also. $password is processed by the auth_crypt_method.
217 For mysql md5-crypt use auth_crypt_method = plain and 'UPDATE user SET
218 password=PASSWORD("$password") WHERE username="$userid"'
220 user_create is typically undefined, but may be defined to get rid of
221 PersonalPage users completely.
223 auth_user_exists is only needed with auth_crypt_method = plain and
224 USER_AUTH_POLICY = stacked or old or for certain plugins which want to
225 list all users. With auth_crypt_method = crypt the auth_check
226 statement is used for the userExists() check.
230 This can be optionally defined in an external DB. The default is the
233 ;pref_select: 'SELECT pref as pref FROM user WHERE username="$userid"',
234 ;pref_update: 'UPDATE user SET pref="$pref_blob" WHERE username="$userid"', or
235 mysql-specific: 'REPLACE INTO user SET prefs="$pref_blob", userid="$userid"'
236 (only if the pref table uses these two fields only!)
241 DB methods for lib/WikiGroup.php. This can be optionally defined in a
242 file (see AUTH_GROUP_FILE) or an external DB. The default storage
243 location is a special locked wikipage named after the group and as
244 content a list of all groupmembers.
246 ;is_member: 'SELECT 1 FROM groups WHERE user=$userid"" AND group="$groupname"',
247 ;group_members: ''All members of the group.'' 'SELECT username FROM grouptable WHERE groupname="$groupname"'
248 ;user_groups: ''All groups this user belongs to.'' 'SELECT groupname FROM grouptable WHERE username="$userid"'
254 The preferences are stored as serialized hash of non-default values,
255 at the following locations:
258 # Cookie (only the userid as WIKI_ID)
262 ~AnonUser uses Cookie alone. For signed in users (~BogoUser and
263 higher) the PersonalPage and/or Database methods are tried. If these
264 methods fail (no such page or user exists) only the userid will be
265 stored in a Cookie. For some short time a serialized array of
266 _UserPreference objects was stored which was "not a good thing".
267 There is code to detect these objects and convert them automatically.
268 Also serialized arrays stored in a WIKI_PREFS2 or WIKI_NAME cookie are
269 deprecated and are automatically converted and deleted.
271 To use the "PersonalPage" location a page with the same name as the
272 userid must exist, the so called "HomePage". This does not need be a
273 WikiWord pagename but it sure helps.
275 If $DBAuthParams~['pref_select'~] is defined, PersonalPage preferences
276 are ignored and the preferences are read from the database. If
277 $DBAuthParams~['pref_update'~] is defined, the preferences are stored
278 back into the database.
282 Group membership information can be stored in
287 For the group wikipage you have to create for every group a page with
288 a list of users and the master group page called "CategoryGroup".
290 For the database setup you can define the following $DBAuthParams[] statements.
291 You can define 1:n or n:m user<=>group relations, as you wish.
292 Note: Only the PearDB library may be used so far.
294 Sample configurations
297 only one group per user:
298 'is_member' 'SELECT 1 FROM user WHERE user=$userid"" AND group="$groupname"',
299 'group_members' 'SELECT user FROM user WHERE group="$groupname"'
300 'user_groups' 'SELECT group FROM user WHERE user="$userid"'
302 or multiple groups per user (n:m):
304 'is_member' 'SELECT 1 FROM groups WHERE user=$userid"" AND group="$groupname"'
305 'group_members' 'SELECT DISTINCT user FROM groups WHERE group="$groupname"'
306 'user_groups' 'SELECT group FROM groups WHERE user="$userid"'
309 Files are defined similar to unix /etc/groups, exactly like apache htgroup files:
311 AUTH_GROUP_FILE = '<filename>'
313 group1: user1 user2 user3 ...