1
2               authhttp DokuWiki HTTP authentication plugin
3       Copyright (c) 2013-2023 Pieter Hollants <pieter@hollants.com>
4           Licensed under the GNU Public License (GPL) version 3
5
6
7Last successfully tested: 2023-09-20 with PHP 8.0.30 and
8                          DokuWiki 2023-04-04a "Jack Jackrum"
9
10
11DESCRIPTION
12
13This auth plugin is for you if you don't want your users to have to login
14through the login form all the time when you have instead already configured
15your webserver to perform some sort of authentication (eg. HTTP Basic or
16NTLM authentication). In that case, the Webserver provides a user's
17credentials to PHP scripts through the superglobal variables
18$_SERVER['PHP_AUTH_USER'] and $_SERVER['PHP_AUTH_PW'].
19
20Out of the box DokuWiki will already pick these up and pretend the user
21supplied those through the login form. It will perform authentication using
22the configured auth plugin (usually authplain) and, if successful, show the
23user (and the admin) options depending on the auth plugin's capabilities.
24
25This all works out as long as
26- EITHER DokuWiki's auth plugin does NOT report capabilities such as "change
27  login name", "change password", "add user", "edit user", "delete user"
28  so that DokuWiki consequently does not expose these controls to the user
29- OR the Webserver and DokuWiki's auth plugin use the SAME source for their
30  authentication.
31
32If the first condition is not true, ie. the plugin DOES provide the named
33capabilities, the user could attempt to change his password through the
34"User profile" function. The admin, through the "User manager", could also
35change his login name, delete him or add him with a different login name.
36
37Now if the second condition is ALSO not true, there can be inconsistencies
38between the HTTP authentication (which might eg. use an old password) and
39DokuWiki's auth plugin (which might have stored a new password somewhere
40else), causing Single Sign-On to break and errors to be displayed.
41
42Note that this is not a bug in DokuWiki - DokuWiki can't in any way know how
43your Webserver's HTTP authentication has been set up.
44
45For example, if you configure your Webserver to display the username/password
46prompt but not to actually validate them, there is no problem at all since
47DokuWiki (without this plugin) is the only entity doing actual authentication.
48This might actually be a considerable setup since there is not much point in
49authenticating twice. https://www.dokuwiki.org/tips:httpauth-passthru
50describes this.
51
52This plugin does it the other way round. It assumes that the web server already
53did the authentication and essentially annuls DokuWiki's own authentication by
54providing a minimalistic checkPass() method which does not really authenticate.
55It merely checks that DokuWiki's idea of username/password equals the HTTP
56authentication credentials which should always be the case (except if you did
57not enable HTTP authentication in your Webserver).
58
59Note however that DokuWiki expects information that HTTP authentication does
60not provide and where the plugin, when used on its own, thus has to improvise:
61- the user's real name: authhttp will simply return the user's login name here.
62- the user's email address: authhttp makes one up by appending a configurable
63  domain part to the user's login name. This will generate email addresses that
64  will probably not work. There is not really a way around this, so you might
65  want to disable email-related functions in DokuWiki.
66- the user's groups: authhttp will simply put all users in DokuWiki's
67  "defaultgroup". Users whose login names are listed in "specialusers" will
68  also be reported to be member of "specialgroup". If you did not modify
69  DokuWiki's "superuser" configuration setting default of "@admin", you should
70  leave this setting at "admin" as well and put users supposed to be admins in
71  "specialusers".
72
73If these limitations are not acceptable, you might want to combine authhttp
74with another plugin, authsplit (https://www.dokuwiki.org/plugin:authsplit).
75authhttp comes with an action plugin that improves integration with authsplit:
76- When authhttp is the primary auth plugin for authsplit, there could be the
77  case that while users are known to authhttp, they aren't to the secondary auth
78  plugin yet, so they'd have to register (unless authsplit's "autocreate_users"
79  feature is used). In this scenario, the username for registration should match
80  the HTTP authentication username. Also, the login form should be hidden
81  because there is not much sense in offering a form-based login when HTTP
82  authentication is used. authhttp's action plugin takes care of all that.
83- When authhttp is used on its own, ie. without authsplit, users are ALWAYS
84  logged in and "registered", so authhttp's action plugin won't have a visible
85  effect.
86
87
88INSTALLATION
89
90Download the latest version from https://github.com/pief/authhttp/zipball/master
91and rename the extracted directory to "authhttp", otherwise the plugin won't
92work.
93
94Please refer to http://www.dokuwiki.org/plugins for additional info
95on how to install plugins in DokuWiki.
96
97
98CONFIGURATION AND SETTINGS
99
100- usernameregex: A regular expression specifying the actual user name part of
101  the HTTP authentication login name (the string in $_SERVER['PHP_AUTH_USER']).
102  Examples:
103  .+           for UNIX/passwd environments (ie. user name = login name)
104  ^[^@]+       for Kerberos environments with user@domain login names,
105               uses everything before the @ character as user name
106  \\[^\\]+$    for Windows domain environments with DOMAIN\USER login names,
107               uses everything after the \ character as user name
108- emaildomain: The domain to append to login names to generate email addresses.
109- specialusers: The login names of users to be put in the special group. You
110  can list multiple login names separated by Space.
111- specialgroup: The name of the special group.
112
113Note: when authhttp is used together with authsplit and authhttp is the primary
114auth plugin for authsplit, the last three configuration settings above will
115have no effect any longer due to the way authsplit works.
116
117
118REFERENCES
119
120Visit the DokuWiki plugin page at
121
122  https://www.dokuwiki.org/plugin:authhttp
123
124To follow development more closely, clone the GitHub repo at
125
126  https://github.com/pief/authhttp.git
127
128
129CREDITS
130
131This plugin is based on ideas in the "ggauth" auth backend by Grant Gardner
132<grant@lastweekend.com.au>. Grant has not been maintaining ggauth for
133DokuWiki versions after "WeatherWax". Also, his "http" auth backend uses
134trustExternal() which eg. does not support group memberships if used on
135its own, ie. without the ggauth "split" auth backend.
136