It's better when it's simple

User Tools

Site Tools


Two Factor Authentication - Core Plugin

Compatible with DokuWiki

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

plugin Provides modular two factor authentication functionality to DokuWiki

Last updated on
Admin, Action

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:

  1. Install the attribute plugin
  2. Install the Two Factor Core plugin (this one)
  3. 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.

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

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.

Change Log

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.

User Setup

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.

User Login

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.

Admin Page

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 optin, optout, and mandatory. Default: optin
  • 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: enabled
  • 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.

plugin/twofactor.txt · Last modified: 2024-03-27 23:51 by andi

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