Table of Contents
Two Factor Authentication - Core 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
This module provides a two factor authentication framework to a wiki. It is designed to work with any wiki-based authentication mechanism that supports the 'getUsers' method (see below for additional information). This module requires at least one Two Factor authentication module (listed below) in order to work.
READ BEFORE UPGRADING The twofactor plugin was rewritten in 2022. When upgrading from any release before 2022-04-07 you also need to upgrade all plugins listed below! Not all former twofactor providers have been updated, yet. User's two factor configurations should continue to work after upgrading. The old plugin can still be downloaded.
Note the order in which the two factor plugins are installed and deinstalled are important! Use the following order to install, reverse the order on deinstall:
- Install the attribute plugin
- Install the Two Factor Core plugin (this one)
- Install at least one Two Factor Provider:
- Email – Send a one-time password to a user using their DokuWiki registered email address.
- Alternate Email – Send a one-time password to a user using an email address that is not registered with DokuWiki.
- Google Authenticator – Allow the use of Google Authenticator to generate login tokens.
- Telegram – Send a one-time password to Telegram.
This plugin requires configuration prior to being functional. However, it will not interfere with any existing authentication plugin. This plugin “wraps” the authentication module by preventing the user from accessing the wiki until the two factor challenge is completed.
Depending on how the Two Factor module is configured, users will be able to continue to use the wiki without using two factor authentication.
- allow to skip 2fa for trusted IP addresses (2024-02-21 10:56)
- Version upped (2023-07-11 23:52)
- avoid rogue 2fa code generations (2023-07-11 15:13)
- protect password reset with 2fa (2023-07-11 12:56)
- Version upped (2023-06-12 23:51)
- Merge pull request #8 from alexdraconian/uid-option (2023-06-12 18:17)
- Add "useinternaluid" option (2023-06-11 15:53)
- Version upped (2023-01-24 23:51)
How It Works
This is NOT an authentication plugin. Instead, it is a display barrier between your users and the wiki. When a user logs in but has not completed two factor authentication, they are guided to the Two Factor configuration page to configure it (if mandatory for the wiki) or to a separate screen where they can enter any received One-Time Passwords (OTP). This means that conceptually, this should work with ANY authentication plugin.
In order to use two factor authentication, the user will have to first configure their own two factor settings if any additional modules require it. This setup can be done through the Two Factor configuration page.
Unless the wiki uses mandatory two factor authentication, users can opt out of using two factor authentication.
Users are presented with a list of available Two Factor providers and can add any one of them to their account. Adding a provider will require verifying the setup using one time passcode.
Users can configure their preferred provider as a default.
Once the user set up at least one two factor provider, the wiki will ask for the second factor login, after the regular login was successful.
The user may use any one of the providers they have configured to authenticate, so configuring both Google Authenticator and an alternate email one-time password allows the user to use either method to login. Keep in mind that in order for multiple modules to be effective, the modules should not have a single point of failure, e.g. configuring Google Authenticator and SMS messages doesn't work if the user loses their cell phone.
Any user that has not configured two factor authentication can login without supplying a token or one-time password, and will be redirected to the Two Factor configuration page if two factor authentication is required by the wiki admin.
There is an admin page to enable the reset of two factor settings for users that manage to get locked out.
Once in the admin page, click the reset button next to a user. This removes all user settings, and they will have to completely reconfigure their two factor setup from the beginning. There is no option to individually manage their settings to prevent tampering.
Configuration and Settings
optinout– Configure two factor features as
useinternaluid– When disabled, all 2fa authentication is bound to the user's IP address. Whenever their IP changes they need to reauthenticate. This enhances security but might be inconvenient for your users. Default:
trustedIPs– A regular expression to match against the user's IP address. Users with a matching IP address do not need to provide a second factor. Useful to only require 2fa outside the office for example. Default: not set.
More configuration is available for the individual providers.
Implementing new Providers
Providers are action plugins that inherit from
\dokuwiki\plugin\twofactor\Provider. They need to implement at least all the abstract methods but may overwrite any other methods in that class. Best have a look at the existing provider plugins to learn more.
The following old providers have not been updated to work with this version of the plugin, yet:
Please get in contact if you want to commission the update of above providers or a completely new one.