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