DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:authsplit

Split Authentication Plugin

Compatible with DokuWiki

  • 2024-02-06 "Kaos" unknown
  • 2023-04-04 "Jack Jackrum" yes
  • 2022-07-31 "Igor" yes
  • 2020-07-29 "Hogfather" yes

plugin Splits DokuWiki authentication among auth plugins

Last updated on
2023-07-28
Provides
Auth
Repository
Source

Similar to authchained

Tagged with authentication, split

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 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 are modified in the primary auth plugin only since by design the secondary auth plugin knows empty ones only
    • group membership is always modified in the secondary auth plugin

  • 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:

method Primary auth plugin Secondary auth plugin
checkPass() Authenticated here User existance required
(Can create if autocreate_users == 1)
trustExternal() Authenticated here User existance required
(Can create if autocreate_users == 1)
logOff() Done here -
getUserData() User existance required Stored here
createUser() Created here
(If supported by the auth plugin)
Created here
modifyUser() Depends on the information being modified:
Login names Modified here
(If supported by the auth plugin)
Modified here
Real names Modified here
(If supported by the auth plugin)
Modified here
eMail addresses Modified here
(If supported by the auth plugin)
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

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

Search and install the plugin using the Extension Manager.

Alternatively, download the latest version from Github to lib/plugins and rename the extracted directory to authsplit, otherwise the plugin won't work. Please refer to 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.

Change Log

Credits

This plugin is based on ideas in the “ggauth” auth backend by Grant Gardner. 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.

Discussion

Please use the Discussion page for user comments.

plugin/authsplit.txt · Last modified: 2023-09-20 20:51 by Klap-in

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki