Merge pull request #295 from Wachizungu/add-mfa-hotp-totp-documentation

new: [TOTP/HOTP] Add TOTP/HOTP related documentation
MISP · Sep 1, 2023 · f43a9a5 · f43a9a5
2 parents cf66610 + c293c84
commit f43a9a5
Show file tree

Hide file tree

Showing 12 changed files with 59 additions and 0 deletions.
diff --git a/administration/README.md b/administration/README.md
@@ -875,4 +875,35 @@ The background workers can be managed via the CLI in addition to the UI / API ma
     MISP/app/Console/cake Admin restartWorkers
 #### Kill A Worker
     MISP/app/Console/cake Admin killWorker [worker_pid]
+
+## Administration of TOTP/HOTP
+MISP 2.4.172 introduced multi-factor authentication (TOTP/HOTP) support.
+
+Before using or testing this feature, please note that it is extremely important to make sure your server has correct time syncing set up, since the TOTP tokens are time based. If you are alread using e-mail OTP, you can leave this on. The two multi-factor authentication methods can co-exist, users that have TOTP/HOTP set up, will no longer be able to use e-mail OTP. Those that do not have it set, will still be prompted for it in that case.
+
+After updating your MISP, make sure you have installed the required php dependencies by using the top menu to go to Administration > Server Settings & Maintenance > Diagnostics.
+
+![Screenshot of diagnostics page showing required php libraries for TOTP/HOTP](./figures/php-dependencies-totp.png)
+
+If you do not have them installed yet, you can run the equivalent of the below command for your setup / OS to install them:
+
+    sudo -u www-data sh -c "cd /var/www/MISP/app;php composer.phar update"
+
+You can see which users have TOTP/HOTP configured in the users index:
+![Screenshot of users index page, with highlight showing the column which indicates a user has TOTP/HOTP configured](./figures/user-with-totp-active-in-users-index.png)
+
+As a site-admin (users can't do this themselves), you can delete TOTP/HOTP for a user from the view user page, by clicking the TOTP Delete button.
+![Screenshot of view user page with highlighted delete OTP button](./figures/delete-totp-button.png)
+
+### Mandating TOTP/HOTP usage
+You can mandate the usage of TOTP/HOTP by setting the Security.otp_required setting to true. Users will then be prompted to set up TOTP/HOTP when trying to access a page, if they haven't done so yet.
+
+From the command line you can run the equivalent of the below command for your setup, to configure this:
+
+    sudo -u www-data /var/www/MISP/app/Console/cake Admin setSetting Security.otp_required true
+
+### Transitioning from e-mail OTP to TOTP/HOTP
+If you are currently using e-mail OTP on your instance, you have the option to enable TOTP/HOTP (by installing the required php dependencies) and giving your users a transition period to set up their TOTP (e-mail OTP will still work during this period), before mandating TOTP.
+### How to use TOTP/HOTP
+For information on how to use this feature from a normal user perspective, please refer to the [using the system](../using-the-system/README.md) section.
 
diff --git a/administration/figures/delete-totp-button.png b/administration/figures/delete-totp-button.png
diff --git a/administration/figures/php-dependencies-totp.png b/administration/figures/php-dependencies-totp.png
diff --git a/administration/figures/user-with-totp-active-in-users-index.png b/administration/figures/user-with-totp-active-in-users-index.png
diff --git a/using-the-system/README.md b/using-the-system/README.md
@@ -667,3 +667,31 @@ The response from requesting an invalid page
 	<url>/The_meaning_of_life</url>
 </response>
 ```
+
+### Using TOTP/HOTP multi-factor authentication
+MISP 2.4.172 introduced multi-factor authentication (TOTP/HOTP) support. For information on how to enable and configure this feature, please refer to the [administration](../administration/README.md) section.
+
+#### Generating TOTP/HOTP tokens
+Using the top menu bar, navigate to Global Actions > My Profile.
+Click the TOTP Generate button.
+![Screenshot of my profile view with TOTP generate button highlighted](.\./figures/totp-generate-button.png)
+
+You can then use your favorite TOTP application (for example: Winauth or Google authenticator) on the next screen. Validate the set up is done correctly by entering a verification code.
+
+![Screenshot of TOTP set up validation screen](./figures/generate-and-validate-totp-screen.png)
+
+Once your set up has been validated, you will get redirected to a page containing your 50 HOTP/paper based tokens.
+
+![Screenshot of paper based single use tokens page](./figures/hotp-tokens.png)
+
+You can view these tokens again later, by going to your profile and clicking the View paper tokens button.
+
+![Screenshot of My profile page with View paper tokens button highlighted](./figures/view-paper-tokens-button.png)
+#### Logging in with TOTP/HOTP
+After setting up TOTP/HOTP for your account, you will be prompted for an OTP on future logins.
+![Screenshot of page requesting you to enter OTP after login](./figures/login-otp-request.png)
+Enter either a generated TOTP from your authenticator software, or the specified (numbered) paper based token.
+#### Deleting and re-generating TOTP/HOTP tokens
+Deletion of the TOTP/HOTP setup for your user can only be done by a site admin, reach out to the site admins of your instance in case you want to set up new tokens.
+#### Combining multiple forms of multi-factor authentication
+It is currently not possible to combine multiple forms of multi-factor authentication. As an example: once your user has TOTP/HOTP assigned, you can't use e-mail OTP for it. If you are using a system which has e-mail OTP set up as well, e-mail OTP will be used again when your TOTP/HOTP setup is deleted.
diff --git a/using-the-system/figures/config-option-make-totp-mandatory.png b/using-the-system/figures/config-option-make-totp-mandatory.png
diff --git a/using-the-system/figures/generate-and-validate-totp-screen.png b/using-the-system/figures/generate-and-validate-totp-screen.png
diff --git a/using-the-system/figures/hotp-tokens.png b/using-the-system/figures/hotp-tokens.png
diff --git a/using-the-system/figures/login-otp-request.png b/using-the-system/figures/login-otp-request.png
diff --git a/using-the-system/figures/totp-generate-button.png b/using-the-system/figures/totp-generate-button.png
diff --git a/using-the-system/figures/user-with-totp-active-in-users-index.png b/using-the-system/figures/user-with-totp-active-in-users-index.png
diff --git a/using-the-system/figures/view-paper-tokens-button.png b/using-the-system/figures/view-paper-tokens-button.png