1
2 authsplit DokuWiki Split authentication plugin
3 Copyright (c) 2013-2017 Pieter Hollants <pieter@hollants.com>
4 Licensed under the GNU Public License (GPL) version 3
5
6
7NOTE: This auth plugin requires DokuWiki WeatherWax (2013-05-10a) or later!
8
9
10DESCRIPTION
11
12authsplit, while technically being an auth plugin, does NOT do any
13authentication itself. Instead, it splits DokuWiki's different authentication
14method calls among TWO other auth plugins that will do the actual work:
15- a PRIMARY auth plugin that will be used for VALIDATION of login names and
16 passwords only. This is where authentication really happens and the
17 authentication source behind this plugin is most probably shared with other
18 software and services.
19- a SECONDARY auth plugin that supplies ADDITIONAL user information such as
20 real names, email addresses and groups. This is most probably specific to
21 DokuWiki.
22
23This suggests using authsplit to combine a rather primitive, yet for some reason
24particularly useful auth plugin with an auth plugin that is more powerful, yet
25for some reason not useful enough if used on its own.
26
27The example that comes to mind is to use authhttp as PRIMARY auth plugin and
28authplain as SECONDARY auth plugin, thereby combining the advantages of reusing
29HTTP authentication information with an auth plugin that supplements everything
30HTTP authentication can't offer, such as email addresses. This is the scenario
31authsplit has been tested with, but in theory it should work with other auth
32plugin combinations as well. Feel free to give me feedback on other working
33combinations.
34
35As authsplit has to orchestrate two auth plugins and the user's state in
36them, it is possible that a user is known to one of the two plugins only or
37stored with different data. This may lead to the effect that while one auth
38plugin knows about him or her, (s)he is still being reported to DokuWiki as
39being unknown. Since these effects may not be particularly intuitive at first
40sight, you should read the following explanations carefully. It is ESSENTIAL to
41really understand how authsplit works in order to prevent accidental lockout
42or security breaches due to improper configuration and/or unexpected behavior!
43
44
45HOW IT WORKS
46
47In order to understand how authsplit works one doesn't really get around
48learning about DokuWiki's authentication system. Please refer to
49https://www.dokuwiki.org/devel:auth_plugins for fundamental basics.
50
51authsplit maps DokuWiki's authentication method calls as follows:
52
53- checkPass(): this is DokuWiki's method that validates login names and
54 passwords. authsplit will first make sure that the PRIMARY auth plugin
55 validates both login name and password successfully. If a user is not known
56 here, he is not known to DokuWiki at all.
57
58 If known and the password matches, authsplit then calls the internal helper
59 method _checkUserOnSecondaryAuthPlugin() (see below).
60
61- trustExternal(): this is the method DokuWiki calls if the PRIMARY auth
62 plugin uses external authentication. authsplit will let the auth plugin itself
63 do whatever authentication is required, eg. against a third-party cookie.
64
65 As with checkPass(), _checkUserOnSecondaryAuthPlugin() is then called. Due to
66 the semantics of external authentication, however, the method ends by doing an
67 additional call to getUserData() to update the global $USERINFO array with the
68 information from the SECONDARY auth plugin.
69
70- _checkUserOnSecondaryAuthPlugin(): This is an internal helper method that
71 tries to obtain the additional user information (real name, email address,
72 groups) from the SECONDARY auth plugin, which means that the user will have to
73 be known there by the same login name, too. If not, behaviour depends on the
74 autocreate_users configuration setting:
75 - if enabled (and the SECONDARY auth plugin reports being capable of adding
76 users), authsplit will create a user account there, too, using user
77 information from the PRIMARY auth plugin as basis. As this information will
78 most likely not be very useful, the user will not only be notified that an
79 account has been automatically created for him or her, but that (s)he should
80 also review his or her user profile.
81 - otherwise the user seems to DokuWiki to be not logged in and will thus most
82 likely see an "Access denied" page. He or she will either have to register
83 him- or herself or, if self-registration has been disabled, the Admin will
84 have to create an account for him or her.
85
86- logOff(): DokuWiki documentation says this method is run "in addition to the
87 usual logOff. Useful with trustExternal() to initiate actions for the
88 external backend, eg. use it to clear cookies or similar actions".
89
90 authsplit just delegates the call to the PRIMARY auth plugin's logOff()
91 method.
92
93- getUserData(): this is the method DokuWiki uses eg. to retrieve the user's
94 real name for display in the "Logged in as" section in the upper right (if
95 you use the default "DokuWiki" template). authsplit will call the PRIMARY
96 auth plugin's getUserData() method only to make sure the user exists there and
97 then return the SECONDARY auth plugin's getUserData() information to DokuWiki.
98 Thus, a user has to be known to both auth plugins, but the SECONDARY's user
99 information matters. Any group membership information returned from the PRIMARY
100 auth plugin will be silently ignored.
101
102- createUser(): this is the method that gets called if users register themselves
103 or the Admin uses DokuWiki's user manager to create an account for them.
104
105 authsplit will first check if the user is not known to the PRIMARY auth plugin
106 yet and whether it is capable of adding users. If so, it will try to create
107 the user there, first. This is so that you can use DokuWiki to quickly create
108 a user both in DokuWiki AND your common authentication source without having
109 to fire up whatever admin tool the PRIMARY auth plugin would otherwise
110 require.
111
112 If successful (or the PRIMARY auth plugin does not support adding users, as is
113 the case for authhttp), the user is then created in the SECONDARY auth plugin
114 but with an EMPTY password. This is by intent since passwords are supposed to
115 come from the PRIMARY auth plugin.
116
117 This also means that an Admin can not specify a password in the user manager
118 unless the PRIMARY auth plugin reports being capable of modifying passwords,
119 too. If not (and this is the case eg. for authhttp), this also means that in
120 the user self-registration form, users should not be able to specify a
121 password and DokuWiki should not try to generate one for them because it
122 wouldn't be stored anywhere and the user would thus get irritated. authhttp
123 eg. comes with an action plugin that takes care of this.
124
125- modifyUser(): where authsplit routes a change depends on the actual change
126 itself:
127 - for login names, real names and email addresses, authsplit will try to
128 modify in the PRIMARY auth plugin first (if that plugin reports being
129 capable of modifying it, that is), then in the SECONDARY auth plugin.
130 - passwords will be modified in the PRIMARY auth plugin only since by design
131 the SECONDARY auth plugin knows empty ones only.
132 - group memberships will always be modified in the SECONDARY auth plugin only.
133
134- deleteUser(): authsplit will ALWAYS route delete user requests to the
135 SECONDARY auth plugin only. This is because it can't know whether user
136 accounts known to the PRIMARY auth plugin are yet in use by other software.
137 Thus, deleting a user with the user manager will remove knowledge of his or
138 her existance in DokuWiki only.
139
140- retrieveUsers() / getUserCount(): authsplit will always route these method
141 calls to the SECONDARY auth plugin, following the concept that DokuWiki's
142 user manager is supposed to manage DokuWiki users in the first place. Thus,
143 even if the PRIMARY auth plugin offered these methods, the user lists and
144 counts obtained there would not be of much use since, unless autocreate_users
145 is enabled, only the SECONDARY auth plugin would really know which users resp.
146 how many users really had DokuWiki access.
147
148- addGroup() / retrieveGroups(): authsplit will always route these method calls
149 to the SECONDARY auth plugin since, by design, that is where group membership
150 information comes from.
151
152- isCaseSensitive() / cleanUser(): authsplit will always route these method
153 calls to the PRIMARY auth plugin since that is the one that dictates
154 restrictions on login names.
155
156- cleanGroup(): authsplit will always route this method call to the SECONDARY
157 auth plugin since that is the one that dictates restrictions on group names.
158
159So to summarize which auth plugins are involved in which method calls:
160
161 PRIMARY AUTH PLUGIN SECONDARY AUTH PLUGIN
162--------------------------------------------------------------------------------
163checkPass() Authenticated here User existance required*
164trustExternal() Authenticated here User existance required*
165logOff() Done here -
166getUserData() User existance required Stored here
167createUser() Created here**´ Created here
168modifyUser() Depends on the information being modified:
169 Login names Modified here** Modified here
170 Real names Modified here** Modified here
171 eMail addresses Modified here** Modified here
172 Passwords Modified here -
173 Group memberships - Modified here
174deleteUser() - Deleted here
175retrieveUsers() - Retrieved here
176getUserCount() - Counted here
177addGroup() - Created here
178retrieveGroups() - Retrieved here
179isCaseSensitive() Determined here -
180cleanUser() Determined here -
181cleanGroup() - Determined here
182
183Legend:
184* : Can be created if autocreate_users == 1
185**: If supported by the auth plugin
186
187This theory tells you, for example, that if you combine authplain as PRIMARY
188auth plugin with authmysql as SECONDARY auth plugin:
189- login names and passwords would come from authplain, ie. stored in the
190 conf/users.auth.php file.
191- additional user information would come from authmysql.
192- users would be created in both authplain and authmysql, modified in one or
193 both (depending on the information being modified) but deleted in authmysql
194 only
195- groups would be created in authmysql.
196
197Of course, this example is not a particular useful combination. After all, why
198would you want to store users in a DokuWiki-specific textfile and put additional
199information in a MySQL database...
200
201As mentioned above, using authhttp as the PRIMARY auth plugin and authplain
202as the SECONDARY auth plugin is the prime use case. You could of course also
203try to combine authhttp with authmysql, or authldap with authplain etc. In
204effect, just try things out and give me feedback on working combinations and
205their particular use cases.
206
207
208INSTALLATION
209
210Download the latest version from https://github.com/pief/authsplit/zipball/master
211and rename the extracted directory to "authsplit", otherwise the plugin won't
212work.
213
214Please refer to http://www.dokuwiki.org/plugins for additional info
215on how to install plugins in DokuWiki.
216
217
218CONFIGURATION AND SETTINGS
219
220authsplit itself uses the following configuration settings:
221- primary_authplugin: This is the DokuWiki auth plugin that will be used to
222 validate login names and passwords. An example candidate is my authhttp
223 plugin.
224- secondary_authplugin: This is the DokuWiki auth plugin that will be used to
225 store additional user information such as real names, email addresses and
226 groups.
227- username_caseconversion: If one of the two auth plugins used is
228 case-sensitive, it may be necessary to enable this setting to let authsplit
229 convert the username to either uppercase or lowercase (eg. when combining
230 authldap which is case-insensitive with authsplit which is not).
231- autocreate_users: If enabled, authsplit will automatically create user
232 accounts for any users that exist in the PRIMARY auth plugin, but are yet
233 unknown in the SECONDARY auth plugin. If disabled, users will either have to
234 register themselves or created by the admin (eg. if registration has been
235 disabled).
236- debug: If enabled, authsplit will flood the screen with debugging messages
237 meant to aid in troubleshooting its operation. This setting should not be
238 enabled in productive setups.
239
240Note that you'll have to take some of the used auth plugin's settings into
241consideration whereas some may not apply any longer due to the way authsplit
242works. For example, when using authhttp as the PRIMARY auth plugin, authhttp's
243configuration settings no longer have any effect since all email addresses and
244group information come from the SECONDARY auth plugin instead.
245
246
247REFERENCES
248
249Visit the DokuWiki plugin page at
250
251 https://www.dokuwiki.org/plugin:authsplit
252
253To follow development more closely, clone the GitHub repo at
254
255 https://github.com/pief/authsplit.git
256
257
258CREDITS
259
260This plugin is based on ideas in the "ggauth" auth backend by Grant Gardner
261<grant@lastweekend.com.au>, https://www.dokuwiki.org/auth:ggauth. Grant does
262not actively maintain ggauth anymore, so an update for the new auth plugins
263concept is unlikely.
264
265Support for external authentication was contributed by David Darras
266<david.darras@univ-lille1.fr>.
267