Differences

This shows you the differences between two versions of the page.

--- plugin:twofactor [2018-06-27 00:25] – Added authentication issue code to module. wilminator
+++ plugin:twofactor [2024-03-27 23:51] (current) – version upped andi
@@ Line 3: / Line 3: @@
 ---- plugin ----
 description: Provides modular two factor authentication functionality to DokuWiki
-author     : Michael Wilmes
+author     : Andreas Gohr, Michael Wilmes
-email      : michael.wilmes@gmail.com
+email      : dokuwiki@cosmocode.de
-type       : Action Admin
+type       : action, admin
-lastupdate : 2018-06-26
+lastupdate : 2024-03-27
-compatible : 2015-08-10a "Detritus", 2016-06-26 "Elenor Of Tsort", 2017-02-19b "Frusterick Manners"
+compatible : Hogfather, Igor, Jack Jackrum, Kaos
 depends    : attribute
 conflicts  :
@@ Line 13: / Line 13: @@
 tags       : 2fa, two-factor, security, authentication
-downloadurl: https://github.com/wilminator/dokuwiki-plugin-twofactor/zipball/master
+downloadurl: https://github.com/cosmocode/dokuwiki-plugin-twofactor/zipball/master
-bugtracker : https://github.com/wilminator/dokuwiki-plugin-twofactor/issues
+bugtracker : https://github.com/cosmocode/dokuwiki-plugin-twofactor/issues
-sourcerepo : https://github.com/wilminator/dokuwiki-plugin-twofactor/
+sourcerepo : https://github.com/cosmocode/dokuwiki-plugin-twofactor/
 donationurl:
-screenshot_img : http://i.imgur.com/wqcCAKE.png
+screenshot_img :
 ----
-===== Summary =====
-This module provides a two factor authentication framework to a wiki. It is designed to work with any wiki-based authentication mechanism (sorry Apache authentication users, I have not tested it for you). This module requires at least one Two Factor authentication module (listed below) in order to work.
+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.
-===== MAJOR REVISION =====
+===== Installation =====
-As of 2016-01-06, I have completely overhauled this module and in order to use it you **will** need to add at least one supporting module. The benefit is that new modules can be added or updated without impacting other modules.
+:!: **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  [[https://github.com/wilminator/dokuwiki-plugin-twofactor/archive/refs/heads/master.zip|downloaded]].
-===== Installation =====
+:!: 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 plugin and at least one supporting module. Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.
+  - Install the [[plugin:attribute]] plugin
+  - Install the Two Factor Core plugin (this one)
+  - Install at least one Two Factor Provider:
+    * [[plugin:twofactoremail|Email]] -- Send a one-time password to a user using their DokuWiki registered email address.
+    * [[plugin:twofactoraltemail|Alternate Email]] -- Send a one-time password to a user using an email address that is not registered with DokuWiki.
+    * [[plugin:twofactorgoogleauth|Google Authenticator]] -- Allow the use of Google Authenticator to generate login tokens.
+    * [[plugin:twofactortelegram|Telegram]] -- Send a one-time password to Telegram.
+Search and install the plugin using the [[plugin:extension|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.
@@ Line 38: / Line 44: @@
 Depending on how the Two Factor module is configured, users will be able to continue to use the wiki without using two factor authentication.
-===== Two Factor Modules =====
+==== Change Log ====
+{{rss>https://github.com/cosmocode/dokuwiki-plugin-twofactor/commits/master.atom date}}
-  * [[plugin:twofactoremail|Email]] -- Send a one-time password to a user using their DokuWiki registered email address.
-  * [[plugin:twofactoraltemail|Alternate Email]] -- Send a one-time password to a user using an email address that is not registered with DokuWiki.
-  * [[plugin:twofactorgoogleauth|Google Authenticator]] -- Allow the use of Google Authenticator to generate login tokens.
-  * [[plugin:twofactorsmsgateway|SMS via Email Gateway]] -- Send a one-time password to a user's cell phone using an email gateway.
-  * [[plugin:twofactorsmsappliance|SMS via Appliance]] -- Send a one-time password to a user's cell phone using an SMS appliance.
 ===== 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. As of Detritus, I have used this with authad in production and authplain in development with great success. Please post if you have success with other back-ends!
+**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 =====
-{{ http://i.imgur.com/d0oeyOl.png?160|User Configuration Page}}
 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, each user will have a master checkbox to turn on and off two factor authentication. When turned on, the user will then have the option to turn on and off the use of any installed modules. If the user turns on the use of a module, the user will have to verify that the module works for them by either supplying the correct token or one-time password. After the user has verified that it is working, the wiki will then allow that module to be used for two factor authentication.
+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.
-The user may use any one of the modules they have configured to two factor authenticate, so configuring both Google Authenticator and and 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.
+Users can configure their preferred provider as a default.
 ===== User Login =====
-If a module supports token-based authentication, like Google Authenticator, the token must be supplied at the login page. If the user is not using a token based method, such as a one-time password via SMS message, the user leaves that field blank at the login page and will be redirected to a separate page to supply the one-time password.
+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.
@@ Line 68: / Line 74: @@
 ===== Admin Page =====
-There is an admin page to enable the reset of two factor settings for users that manage to get locked out. Face it, cellphones get lost and people mistype data in fields, so it's gonna happen...
+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, check the box next to the user whose account you want to reset, then click the Reset selected button. 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.
+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 =====
-  * ''enable'' -- Turn on or off all two factor authentication functionality. Default: ''off''
   * ''optinout'' -- Configure two factor features as ''optin'', ''optout'', and ''mandatory''. Default: ''optin''
-  * ''otpcontent'' -- The message to deliver to the user.'' $otp'' is replaced with the randomly generated code. Default: ''$otp'' is your verification code.
+  * ''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''
-  * ''generatorexpiry'' -- How many windows of time a GA code is valid for. This setting allows for a code to be useful for longer than its display time in GA. Very helpful for slow typing users of if a code is seen at the end of its display time. Default: ''2'' (the time displayed plus one more code)
+  * ''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.
-  * ''otplength'' -- Length of the randomly generated OTP. Default: ''7''
-  * ''sentexpiry'' -- Time in minutes that a sent OTP is valid for. Default: ''5''
-  * ''loginnotice'' (Not working yet) -- Send a notice on successful login to the user. Options are never (''none''), user choice (''user''), and always send a message (always). Default: ''user''
-===== Development =====
-Additional work will be based on my free time in the future. I was allowed to put this together for my work and release it, but future development will be on my personal time.
-==== API ====
-**NOTE: Work In Progress**
-I am going to document the Two Factor module API here in order to provide all information about this plugin in one place. I am open to suggestions if a better location can be found.
-=== Change Log ===
-{{rss>https://github.com/wilminator/dokuwiki-plugin-twofactor/commits/master.atom date}}
-=== Known Bugs and Issues ===
-  * The login notification does not work yet.
-=== ToDo/Wish List ===
-  * I've had a request to add Twilio and Plivo as supported two factor resources. After the redesign, I will look into it. I will need some help for testing, my personal budget is zero dollars and zilch cents.
-  * Possibly supply a configuration setting enabling the admin to designate which characters to use in the OTP generator. Right now it is fixed on Arabic numerals.
-===== YOUR Help =====
-I originally wrote this because we needed 2FA for our wiki at work. Our use of DokuWiki has come to a close, but I will continue to maintain this code for the foreseeable future on my own time. That said, I will post fixes that are brought to my attention and test it our in my development environment as best as possible, but now I need ** your ** help to confirm that it is working.  Also, please let me know that this update does or does not work with the current stable release so I can update this compatibility page.
-===== FAQ =====
-WIP. I will pull discussion questions and post them here as blatant questions come up.
+More configuration is available for the individual providers.
-===== Big Thanks / Acknowledgement =====
+===== Implementing new Providers =====
-First, I want to thank my employer, Antelope Valley College, for allowing me to release this code to the open source community.
+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.
-A big thanks goes out to Dan Popp for the work on his [[plugin:authgoogle2fa|Google 2FA plugin]] -- it provided me with the idea, libraries, and a code template to get this project started.
+The following old providers have not been updated to work with this version of the plugin, yet:
-Another big thanks to Christopher Smith and the developers that worked on the [[plugin:usermanager|User Manager Plugin]]. I used their admin code as the basis for my plugin and have to give them credit for their work that I used.
+  * [[plugin:twofactorsmsappliance|SMS Appliance]]
+  * [[plugin:twofactorsmsgateway|SMS Gateway]]
+  * [[plugin:twofactoryubiauth|Yubiauth]]
-===== Discussion =====
+Please [[https://www.cosmocode.de/en/services/wiki/dokuwiki/|get in contact]] if you want to commission the update of above providers or a completely new one.
-Feel free to write anything constructive. My hope is that this plugin will provide many admins with useful functionality.