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