Two Factor Authentication
=========================

You can enable two-factor authentication (2FA) for your staff and, if desired,
require it for users with specified roles on your TouchPoint database. Once enabled,
all users who have any of the specified roles will be required to use 2FA in order
to log in. They can do this using any TOTP (time-based one-time password) authenticator.
See :ref:`Supported Authenticators <SupportedAuthenticators>` below for a list of several
common TOTP authenticators.

This is a feature intended for staff. It is not designed for `MyData` users. You can make
it available as an option or, as indicated above, require it for certain roles. If you
make it required, we recommend you begin with only your most sensitive roles, such as
`Finance`, `FinanceAdmin`, and `Admin`. Once this core group has become familiar with the feature,
you can then require it for other sensitive roles, if desired.

Configuring 2FA
---------------

To enable 2FA on your database, toggle the **TwoFactorAuthEnabled** administration setting to `True`.
This setting and the related settings mentioned in this section are found at `Administration > Setup > Settings > System > Security`. With this setting in place, users will have an option in
their account menu to `Enable 2FA`. See the next section for user setup steps.

.. figure:: https://i.tpsdb.com/2FAEnable.png
    :target: #

To determine how many days a two-factor authentication will remain valid, configure the **TwoFactorAuthExpirationDays** administration setting with a value of the number of days
you wish an authentication to last. If this setting is empty, the default is 30 days.
Once a user has logged in with 2FA enabled on a device, they are not prompted to enter a
2FA code again on that device/browser combination for the number of days you set (unless
cookies are deleted before then).

To require 2FA for certain roles, configure the **TwoFactorAuthRequiredRoles** administration setting with a value of the roles (comma-separated) that will require it - for example, ``Admin,Finance,FinanceAdmin``. Users who have any of the listed roles and who have not yet set up 2FA for their account will be prompted to do so immediately, if already logged in, or otherwise when they next attempt to log in.

User Setup
----------

When users select `Enable 2FA` (or when a role they have is initially required), they are
taken to the 2FA Setup Screen, shown below. To complete the setup, they use their preferred
TOTP authenticator app to add an entry and scan the displayed code. (See your preferred app
for the exact steps to add a new entry by scanning a code.)

.. figure:: https://i.tpsdb.com/2FASetupScreen.png
    :target: #

|

After scanning the displayed code with the authenticator app, the user will then be prompted
to enter the six-digit code from the app to complete the process. Following setup, users will
enter the current six-digit code from the authenticator app when prompted while logging into
the TouchPoint database.

.. _SupportedAuthenticators:

Common Supported Authenticators
-------------------------------

As noted above, any TOTP authenticator will work for 2FA. Below are some commons ones:

-	Authenticator Plus
-	Authy
-	Duo Mobile
-	Google Authenticator
-	LastPass Authenticator
-	Microsoft Authenticator

What if a user lost or left their phone at home?
------------------------------------------------

What happens if a user has 2FA enabled but does not have their phone with the authenticator
app? In that case, someone with the `Admin` role can disable 2FA for that user. The Admin would go to the `System` tab on the user's profile, Edit their account and, from the `Actions` drop down menu, select `Disable 2FA`.

.. figure:: https://i.tpsdb.com/2FADisable.png
    :target: #

|

Of course, if 2FA is required for a role that user has, when they attempt to log in they will be prompted to set up 2FA again and will not be able to log in without an authentication app.


|
|

+--------------------+------------------+
| **Latest Update**  | **08/30/2020**   |
+--------------------+------------------+

Modified wording to indicate where to locate the relevant administration settings.