Two Factor Authentication

Two Factor Authentication (2FA) is an extra layer of security in addition to the commonly used user name and password security. When enabled, it requires an additional piece of security token that can be retrieved or generated by the user's own hardware device or software.

Supported Types of 2FA

**Google Authenticator**

Google Authenticator a free app that you can install on your smart phone which will generate a new security code every 30 seconds. For a first time user, the application will generate a QR code which the user must scan with their phone's camera to add the profile to their Google Authenticator app. He can then use the security code generated from the Google Authenticator for the first and subsequent logins. To install and get more information about Google Authenticator, see [Google Authenticator on Google Play](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2), or [Google Authenticator on App Store](https://apps.apple.com/us/app/google-authenticator/id388497605).

**Email**

If enabled, an email containing a generated security code will be sent to the user's registered email address. He can then use the security code to login.

**Important** 1. Make sure that you have configured your [Email settings](phpsetup.html?id=email-settings) correctly so that emails can be sent. 1. If you have a [third party transport](https://symfony.com/doc/current/mailer.html#using-a-3rd-party-transport) that is supported by Symfony Mailer, you can set the [Mailer DSN](tools.html?id=mailer-dsn) advanced setting to send email.

**SMS**

If enabled, a SMS message containing a generated security code will be sent to the user's mobile device for login.

**Important** 1. You must have your own SMS provider to send SMS messages before you can use this feature. 1. If you have a third party SMS provider that is supported by [Symfony SMS channel](https://symfony.com/doc/6.4/notifier.html#notifier-sms-channel), you can enable the **SmsNotifier** extension (for registered users only) to send SMS. 1. If you have a third party SMS provider that is not supported by the above option, you need to write your own SMS class in [Server Events - Global Codes](customscripts.html). 1. It is recommended that you use Sender ID to improve the SMS delivery. However, some countries do not support SMS Sender ID or require Sender ID registration. Please refer to the [AWS website](https://docs.aws.amazon.com/sns/latest/dg/sns-supported-regions-countries.html) to see if your country needs SMS Sender ID registration or does not support Sender ID.

How to Use

To enable the feature, you need to enable the **Two factor authentication (2FA)** checkbox and select the **2FA type** under [Security Settings](securitysetup.html). ![Two Factor Authentication](images/2fa1.png)

**Notes** 1. For security, 2FA applies to the super admin account also, if enabled. 1. The **Profile field** under [User Login Options](securitysetup.html?id=user-login-options) must be set to store the user secret and backup codes so it must be enabled also. 1. The **Email field** under [User Login Options](securitysetup.html?id=user-login-options) must be enabled if **Two factor authentication type** is set to **Email**. If **Super Admin** account is enabled, the setting **Email (for 2FA)** must be set. 1. The **Mobile field** under [User Login Options](securitysetup.html?id=user-login-options) must be enabled if **Two factor authentication type** is set to **SMS**. If **Super Admin** account is enabled, the setting **Phone (for 2FA)** must be set.

If **Force 2FA** is enabled, all users must login using 2FA. If **Force 2FA** is not enabled, users can opt in and opt out. After generation, an **Enable two factor authentication** button will be displayed in the user panel after the user logins. ![Enable/Disable two factor authentication](images/2fa2.png)
The user can then click the button to enable/disable two factor authentication login option. You can enable **Skip Password (login with 2FA only)** if you allow user to login without password but with the 2nd factor authentication only.

After 2FA is enabled, the user needs to enter the security code, either generated from the Google Authenticator app, or an one time password (OTP) received via email or SMS. After logging in successfully with their credentials (the first factor authentication), the user can then choose one of the enabled second factor authentication types to continue login. If no accounts are set up yet, the configuration step will be shown and the user needs to configure at least one account first. ![Configure 2FA](images/2faconfig.png) Before any type can be used, the user needs to verify the account of the type. If the account is not verified (the email address or phone number from project settings or users table are NOT considered as verified), an "unverified" icon ![Unverified](images/unverified.png) will be shown. The user needs to click the authentication type and verifiy. For Google Authenticator, see [First time use with Google Authenticator](twofactorauth.html?id=first-time-use-with-google-authenticator) below. For email or SMS type, an OTP will be sent to the email address or phone number for verification. Once verified, the "verified" icon ![Verified](images/verified.png) will be shown and the account can then be used for 2FA. Now the user can clicking the **Continue** button to go to next step and select the authentication type: ![Select 2FA](images/2faselect.png) The user can then get the OTP from Google Authenticator, or from email/SMS message sent to the verified account, and enter the OTP to complete 2FA.

**Note** You can customize the content of the email/SMS by modifying the _OneTimePasswordEmail.en-US.php_ and _OneTimePasswordSms.en-US.php_. See [Notification Templates](multilang.html?id=notification-templates) for details.

![Google Authenticator](images/2fa4a.png)

Google Authenticator

![Email](images/2fa4b.png)

![SMS](images/2fa4c.png)

SMS

First time use with Google Authenticator

For first time use with **Google Authenticator**, a dialog box with a QR code will be displayed to prompt the user to scan the QR Code using the Google Authenticator. ![Google Authenticator QR Code](images/2fa3.png) The user can then scan the QR Code to add the user profile to the Google Authenticator. He should enter the security code generated from the Google Authenticator to the input box then click the **Verify** button to proceed with the 2FA login.

Backup Codes

When 2FA is enabled, a set of backup codes will also be generated and saved in the user's Profile field. The backup codes are handy when the user has accidentally deleted his profile in the Google Authenticator, or uninstalled the app, or lost his mobile phone. In such cases the user can then use the backup codes as the 2FA security codes for login.

To retrieve the backup codes, after login, the user should click the Two factor authentication button in the user panel to go to the 2FA config page.

Then click the Backup codes link, the backup codes dialog box will appear:

The user can then click the Copy to clipboard to save the backup codes to the clipboard and then save them elsewhere. Note Each backup code can only be used once for login.

He can also click the Get new codes button to get a set of new backup codes. After getting new codes, the old backup codes become invalid, make sure you save the new backup codes.

Reset User Secret (Two Factor Authentication)

To cater for cases when a user is unable to generate the 2FA security code (e.g. due to losing his mobile phone), you can enable the Reset user secret (two factor authentication) option in User Login Option (see Security Settings -> User Login Options):

The administrator can then login and go to the list page of the user table to perform the reset for a certain user. After the reset, the user can then perform the login action again to set up the Google Authenticator as above.