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