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 separate 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
41 To establish a COMPLETELY private wiki, such as an internal corporate one
42 set ALLOW_ANON_USER = false, and probably require user passwords as described below.
43 In this case the user will be prompted to login immediately upon accessing
44 any page. This is similar to HttpAuth.
48 This feature was called REQUIRE_SIGNIN_BEFORE_EDIT before. To enable
49 ALLOW_BOGO_LOGIN and/or ALLOW_USER_PASSWORDS, ALLOW_ANON_EDIT must be
50 false, otherwise it will override ALLOW_BOGO_LOGIN and
51 ALLOW_USER_PASSWORDS. This will go away, with true page permissions.
55 If ALLOW_BOGO_LOGIN is true, users are allowed to login (with
56 any/no password) using any userid which:
57 1) is not the ADMIN_USER, and
58 2) is a valid WikiWord (matches $WikiNameRegexp.)
60 If true, users may be created by themselves. Otherwise we need
61 separate ALLOW_USER_PASSWORDS auth. If such a user will create a so
62 called HomePage named after his WikiWord userid, he will be able to
63 store his preferences and password there.
64 If ALLOW_ANON_EDIT = true, one may still sign in to be able to store
65 UserPreferences and named RecentChanges entries.
66 PASSWORD_LENGTH_MINIMUM is ignored by bogo login attempts.
67 If an empty password is used, any user can sign in with this userid.
69 ! REQUIRE_SIGNIN_BEFORE_EDIT (Legacy)
71 If set, then if an anonymous user attempts to edit a page he will
72 be required to sign in. This constant was replaced by ALLOW_ANON_EDIT in v1.3.8.
73 If ALLOW_BOGO_LOGIN is true, of course, no password is required, but the user
74 must still sign in under some sort of WikiWord name. This will go away,
75 with true page permissions.
77 ! ALLOW_USER_PASSWORDS
79 True User Authentification is used with Bogo Login and not-empty
80 passwords or ALLOW_USER_PASSWORDS = true.
82 To require user passwords set
84 ALLOW_ANON_EDIT = false
85 ALLOW_BOGO_LOGIN = false
86 ALLOW_USER_PASSWORDS = true
88 Otherwise any anon or bogo user might login without any or a wrong
89 password. A login attempt with ALLOW_USER_PASSWORDS = true depends on
90 the defined USER_AUTH_ORDER auth methods, the USER_AUTH_POLICY and
91 PASSWORD_LENGTH_MINIMUM.
93 !! FAQ - UPGRADE PROBLEMS:
95 * ''Fatal error: The script tried to execute a method or access a
96 property of an incomplete object. Please ensure that the class
97 definition wikiuser of the object you are trying to operate on was
98 loaded _before_ the session was started in...''
100 This error will appear you switch from old (or from new to old) in the
101 same browser session. You have an old (or new) WikiUser object in your
102 current session, which is incompatible with the new (or old) WikiUser
103 object on session restauration.
105 Workaround: Close and open your browser again. The session cookie
106 should be destroyed, and you will get a fresh new WikiUser
107 object. Your default WIKI_ID (your username) will not be lost.
109 * ''lib\Template.php:22: Warning[2]: fopen("", "rb") - No such file or directory''
111 PHPWIKI_DIR could not be determined automatically. You probably
112 started from a different diretory.
114 Workaround: Set PHPWIKI_DIR in index.php or in your start script. You
115 most likely have to set DATA_PATH also, when your pages look like the
116 ancient-style Wiki (Times-Roman, black-white), i.e. no CSS is loaded.
119 Below we define which methods exists and in which order theys are used:
121 !! USER_AUTH_ORDER auth methods
123 $USER_AUTH_ORDER is an array of the following strings. You can
124 en-/disable any and change the order.
126 * __~BogoLogin__: This will eventually replace the old ALLOW_BOGO_LOGIN constant,
127 but it will require PASSWORD_LENGTH_MINIMUM. So non-empty passwords can be disabled.
128 * __~PersonalPage__: Store passwords in the users homepage metadata (simple)
129 * __Db__: Use $DBAuthParams~[~] (see below) with PearDB or ADODB only.
130 If 'auth_dsn' is undefined, and wiki pages are stored via SQL or ADODB,
131 it uses the same database. (fastest)
132 * __LDAP__: Authenticate against LDAP_AUTH_HOST with the LDAP_AUTH_SEARCH settings
133 * __IMAP__: Authenticate against IMAP_AUTH_HOST (e.g. an existing email account)
134 * __POP3__: Authenticate against POP3_AUTH_HOST (e.g. an existing email account)
135 * __File__: Check username:crypted-passwords in .htaccess like files.
136 Use e.g. Apache's htpasswd program to manage this file.
137 * __~HttpAuth__: Use the protection by the webserver, either .htaccess or httpd.conf
138 If no HTTP AUTH is enforced by the webserver (e.g no require valid-user), then
139 this method will enforce error 401 to force the client to display a password
142 Each method is a WikiUser (in fact a ~_PassUser) class, which defines the checkPass() and
143 userExists() methods and optionally mayChangePass() and storePass().
147 The available policies defines how and when each auth method from
148 USER_AUTH_ORDER is tried, and what to do on failure. Some policies
149 require to know it at advance at initialization time, some have to
150 check if a valid user exists and some simply check valid username -
153 ;__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).
154 ;__first-only__: use only the first method in USER_AUTH_ORDER
155 ;__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
156 ;__stacked__: check the given user - password combination for all methods and return true on the first success.
158 ! AUTH_FILE_* constants
164 Statements for separate DB User Authentication.
166 This array defines the database prepare statements to select and
167 update the password and preferences. This is typically used to
168 interface with other applications or user databases in quasi secure
169 wiki's. (often so called "Content Management Systems").
170 The database can be external like radius, phpnuke, courier authmysql,
171 apache auth_mysql or just a simple user table within phpwiki.
172 The most likely auth_dsn option is the same dsn as the wikipages, in
173 fact if it's empty $DBParams~['dsn'~] is used. If
174 $DBParams~['db_type'~] is not ADODB, the Pear DB library is used
177 This is the list of the available options and some examples. For the statements we use the following symbolic variables:
179 $password : plain or encrypted password
180 $pref_blob : serialized string of the PHP preferences array (may get large, but not too large. 128 - 1024. mysql TEXT is enough)
181 $groupname : groupname
183 Note: The symbolic variables (like "$password", ...) must be enclosed in double quotes!
184 ADODB Warning: With ADODB we must currently define the correct alias names: SELECT db_column as name
185 This requirement will go away when we switch to FETCH_ROW instead of the slower FETCH_ASSOC
186 (scheduled for 1.4.0)
188 ;auth_dsn: 'mysql://user@password:localhost/phpwiki'
192 ;auth_crypt_method: 'crypt' (simple unix crypt, not md5 crypt, sha1 or else) or 'plain' (also for mysql md5)
194 ;auth_check: needs "$password" and "$userid", returns ok with plain or the password with crypt
196 'auth_crypt_method' = 'plain':
197 'SELECT IF(passwd="$password",1,0) as ok FROM user WHERE username="$userid"' or
198 'SELECT IF(passwd=PASSWORD("$password"),1,0) as ok FROM user WHERE username="$userid"',
200 'auth_crypt_method' = 'crypt':
201 'SELECT password as password FROM user WHERE username="$userid"',
203 auth_user_exists is only needed with auth_crypt_method = plain and USER_AUTH_POLICY = stacked or old:
204 ;auth_user_exists: 'SELECT username as userid FROM user WHERE username="$userid"'
206 ;auth_update: 'UPDATE user SET password="$password" WHERE username="$userid"' or
207 'UPDATE user SET password=PASSWORD("$password") WHERE username="$userid"'
208 ;user_create: 'INSERT INTO user SET username="$userid", password="$password", pref="$pref_blob"'
210 If auth_update is not defined but auth_check is defined, the user
211 cannot change his password. But then better crypt methods may be used
212 also. $password is processed by the auth_crypt_method.
213 For mysql md5-crypt use auth_crypt_method = plain and 'UPDATE user SET
214 password=PASSWORD("$password") WHERE username="$userid"'
216 user_create is typically undefined, but may be defined to get rid of
217 PersonalPage users completely.
219 auth_user_exists is only needed with auth_crypt_method = plain and
220 USER_AUTH_POLICY = stacked or old or for certain plugins which want to
221 list all users. With auth_crypt_method = crypt the auth_check
222 statement is used for the userExists() check.
226 This can be optionally defined in an external DB. The default is the
229 ;pref_select: 'SELECT pref as pref FROM user WHERE username="$userid"',
230 ;pref_update: 'UPDATE user SET pref="$pref_blob" WHERE username="$userid"', or
231 mysql-specific: 'REPLACE INTO user SET prefs="$pref_blob", userid="$userid"'
232 (only if the pref table uses these two fields only!)
237 DB methods for lib/WikiGroup.php. This can be optionally defined in a
238 file (see AUTH_GROUP_FILE) or an external DB. The default storage
239 location is a special locked wikipage named after the group and as
240 content a list of all groupmembers.
242 ;is_member: 'SELECT 1 FROM groups WHERE user=$userid"" AND group="$groupname"',
243 ;group_members: ''All members of the group.'' 'SELECT username FROM grouptable WHERE groupname="$groupname"'
244 ;user_groups: ''All groups this user belongs to.'' 'SELECT groupname FROM grouptable WHERE username="$userid"'
250 The preferences are stored as serialized hash of non-default values,
251 at the following locations:
254 # Cookie (only the userid as WIKI_ID)
258 ~AnonUser uses Cookie alone. For signed in users (~BogoUser and
259 higher) the PersonalPage and/or Database methods are tried. If these
260 methods fail (no such page or user exists) only the userid will be
261 stored in a Cookie. For some short time a serialized array of
262 _UserPreference objects was stored which was "not a good thing".
263 There is code to detect these objects and convert them automatically.
264 Also serialized arrays stored in a WIKI_PREFS2 or WIKI_NAME cookie are
265 deprecated and are automatically converted and deleted.
267 To use the "PersonalPage" location a page with the same name as the
268 userid must exist, the so called "HomePage". This does not need be a
269 WikiWord pagename but it sure helps.
271 If $DBAuthParams~['pref_select'~] is defined, PersonalPage preferences
272 are ignored and the preferences are read from the database. If
273 $DBAuthParams~['pref_update'~] is defined, the preferences are stored
274 back into the database.
278 Group membership information can be stored in
283 For the group wikipage you have to create for every group a page with
284 a list of users and the master group page called "CategoryGroup".
286 For the database setup you can define the following $DBAuthParams[] statements.
287 You can define 1:n or n:m user<=>group relations, as you wish.
288 Note: Only the PearDB library may be used so far.
290 Sample configurations
293 only one group per user:
294 'is_member' 'SELECT 1 FROM user WHERE user=$userid"" AND group="$groupname"',
295 'group_members' 'SELECT user FROM user WHERE group="$groupname"'
296 'user_groups' 'SELECT group FROM user WHERE user="$userid"'
298 or multiple groups per user (n:m):
300 'is_member' 'SELECT 1 FROM groups WHERE user=$userid"" AND group="$groupname"'
301 'group_members' 'SELECT DISTINCT user FROM groups WHERE group="$groupname"'
302 'user_groups' 'SELECT group FROM groups WHERE user="$userid"'
305 Files are defined similar to unix /etc/groups, exactly like apache htgroup files:
307 AUTH_GROUP_FILE = '<filename>'
309 group1: user1 user2 user3 ...