OTP (One-Time Password) Email MFA

Introduction

OTP Email MFA is a Multi-factor authentication plugin that sends a one-time password to a user's email, providing an additional layer of security.

Multi-Factor Authentication (MFA) is a security best practice that adds an extra layer of protection on top of a username and password combination. By requiring an additional authentication code from a trusted device, MFA safeguards access to a user’s account even if the password is compromised.

Plugin information

This plugin bundle is compatible with Joget DX 8 and Joget DX 7.

Get started

Prerequisites

Set up SMTP values in the Joget App so the email tool works properly.
For more details, see General Settings > SMTP Settings.  

SMTP settings in General settings will enable Joget DX to use these SMTP values as global default values for all your apps.

Joget apps will ignore this global SMTP settings if the respective apps already have the settings configured, either in the Plugin Default Properties or Email Tool - Configure SMTP Settings page.

Where to get the plugin

You can download the plugin from GitHub.

How to install

1. Download the plugin from the Releases page on GitHub.
   
2. Click on the .jar file to initiate the download.
   
3. Go to your Joget DX 8 localhost or server and log in as admin.
   
4. In Joget Console, go to Admin Bar > Systems Settings > Manage Plugins.
5. Click Upload Plugins and select the downloaded .jar file, then click Upload.
6. The plugin will appear under the Installed Plugins tab.

How to use it

Administrators

1. Start the Joget server, log in as admin, and open the App Center.
2. Go to Settings > Directory Manager and choose Security Enhanced Directory Manager in the Select Plugin field.
   
3. Select OTP Email MFA Authenticator for the Multi-Factor Authenticator property.
   

Configure one-time password email MFA properties

1. This configuration will determine the properties of your OTP Email MFA Authenticator and the outcome of your plugin.
   In General > Configure One-time Password Email MFA Authenticator.
   
   Fields to configure:
   
   • Validity Period (minutes): Define how long the OTP remains valid once it is sent to the user's email registered in the profile (the default is 5 minutes).
   • Subject: Set the subject line for the OTP email.
   • Message: Configure the message body for the OTP email.
2. Then, in General > Configure One-time Password Email MFA Authenticator > Default Directory Password Policy.
   
3. In General > Configure One-time Password Email MFA Authenticator > Default Directory Password Policy > Notification.
   
   If you leave the Notification tab below empty, Joget will read the default SMTP configuration values from the General Settings > SMTP Settings page.
   
   

   Important

   If you set the values in this Notification tab, these settings will ignore the values you have set from the SMTP Settings > General Settings and send notification based on the configured values here.
   • From: Sender email address.
     Example
     no-reply@your-company-name.com
   • SMTP Host: Email Server SMTP Host
     Example
     smtp.gmail.com
   • SMTP Port: Email Server SMTP Port

     Typically, port 465 for the SSL security option and 587 for the TLS

   • Security: 
     • None
     • TLS
     • SSL

     Alternatively, you can click the hash symbol to allow the input of hash variables.

   • SMTP Username: Email Server Account Username

     On Google email account, use your full email address.

   • SMTP Password:  Email Server Account Password

     Password submitted will be encrypted for security reasons.

   • CC: Fully qualified address is expected.

     Multiple values can be accepted by separating them with semicolons.

     CC: lets you send a copy of a message to someone who's interested but is not the primary recipient.

   • HTML Content?:  Check if the Message is intended to be HTML content.
   • User Creation (Subject): Email Subject.
   • User Creation (Message): Email Message.
     
     Quick Test
     Hit the Send Test Email button to validate and test the email settings quickly.
4. Before submitting the OTP Email MFA Authenticator, click Send Test Email to verify your Email configuration.
   
5. Once all configurations have been inspected and tested, you may submit the OTP Email MFA Authenticator to Enable it. Once enabled, users will be able to enable MFA individually in their User profile.

6. Optionally, you may activate all users to use OTP Email MFA Authenticator by default by adding their usernames as entries into the dir_user_meta table. 

   Here's an SQL query where you can do so :

   insert into dir_user_meta (username, meta_key, meta_value) 
       select username,'OTP_EMAIL','enabled' 
       from dir_user t1
       where not exists(
           select id 
           from dir_user_meta t2
           where t2.username = t1.id
       );

7. This query will add all the existing users in the dir_user table into the dir_user_meta table with the following values: 
   • username : <username>
   • meta_key : OTP_EMAIL
   • meta_value : enabled
     The where not exists clause is to check and skip for existing users already having OTP enabled.
     Joget authentication will automatically check if the user exists in this table and prompt them with the "please enter OTP" message.
     

Users

1. Users can activate OTP Email MFA Authenticator in their respective user profiles by clicking the Activate button.
2. Before activating OTP Email MFA Authenticator, users should ensure that a valid and working email has been registered in their profile under the User Details section, as the email containing the OTP will be sent to this registered email.
3. A popup dialog shows a Password field to submit the email OTP sent to the user. If the code is valid, OTP Email MFA will be activated.
4. The users should never forget to save their user profile after activating MFA.
5. On subsequent logins, the users will be prompted for an OTP password, which will always be sent to the user's email.

Deactivating multi-factor authentication

1. 1. As a user, you can disable OTP Email MFA Authenticator by clicking the Deactivate button in your user profile.
2. Administrators can also disable MFA for a specific user by selecting the Setup Users under Users in the admin bar and clicking the Deactivate MFA button.

Disable the Deactivate MFA button for all users in their profile section

1. Administrators can hide/(disable) the Deactivate MFA button from all users' profile sections to prevent users from individually disabling the MFA.
2. To achieve this, you can add this CSS to the application UI that you want to hide the button from at UI Builder > Settings > Configure [theme name] > Custom CSS
   

   .form-input.deactivate .form-button.btn.button[value='Deactivate']{
     display: none !important;
   }

   

Expected outcome

The Deactivate MFA button is hidden/disabled so the user can access or view it.

Related documentation

• General Settings
• Security Enhanced Directory Manager

Download plugin

• OTP email MFA - Releases