Mandatory MFA Security Enhanced Directory Manager

Introduction

The Mandatory MFA Security Enhanced Directory Manager plugin extends Joget's default Security Enhanced Directory Manager plugin by requiring users to configure and activate Multi-Factor Authentication (MFA) upon logging in, when configured with a compatible mandatory MFA authenticator.

Plugin Information

Plugins Available in the Bundle:

• Mandatory MFA Security Enhanced Directory Manager (Directory Manager)

Supported Database: MySQL, PostgreSQL, Oracle, MS SQL Server
License: Apache License, Version 2.0

This plugin is compatible with Joget DX 8 and Joget DX 9.

Get Started

Prerequisites

• Joget DX 8 or Joget DX 9 Enterprise or Community Edition.
• A Joget instance acting as the Identity Provider (IdP).
• Developer or administrator access with permissions to manage plugins.

Where to get the plugin

You can download this plugin from the JogetOSS GitHub Repository.

How to install

1. Download the plugin .jar file from the GitHub release page.
2. Log in to your Joget Console.
3. Navigate to the Admin Bar and select Settings > Manage Plugins > Upload Plugin.
4. Under the Upload Plugin screen, select the downloaded JAR file and click Upload.

How to use it

1. Go to the Directory Manager Settings page by navigating to Settings > Directory Manager.
2. From the Select Plugin dropdown, select Mandatory MFA Security Enhanced Directory Manager.
   
3. Click Select to access the configuration properties.
   
4. In the Multi-Factor Authenticator dropdown, select Mandatory TOTP Authenticator.
5. Click Submit to apply the configuration. The system will confirm that the plugin is active, showing the active plugin class name as org.joget.marketplace.MandatoryMfaSecurityEnhancedDirectoryManager.
   

User Experience with Mandatory MFA

Once the Mandatory TOTP Authenticator is enabled, all users will be required to set up and verify MFA on their next login attempt.

Initial MFA Setup (Required for All Users)

1. Upon their next login, users enter their username and password as usual.
2. The system displays an MFA activation screen featuring a QR code and a secret key.
   
3. Using a compatible TOTP mobile app (such as Google Authenticator, Microsoft Authenticator, or Authy), the user scans the QR code or manually enters the secret key to create a new account entry.
4. The user enters the current 6-digit verification code from their TOTP mobile app into the OTP field and clicks Submit.
5. If the code is valid, the MFA activation is finalized, and the user gains secure access to the application.

Subsequent Logins

1. The user enters their username and password as usual.
2. The system automatically redirects them to the TOTP Verification screen.
   
3. The user retrieves the current 6-digit code displayed in their TOTP mobile app, inputs it into the OTP field, and clicks Submit to finish logging in.

Customizing Role-based Exceptions

Administrators can modify the plugin source code to exclude specific user roles (e.g., allowing administrative accounts to bypass mandatory MFA):

1. Access the plugin source code from the GitHub repository.
2. Locate and open the MandatoryMfaUserSecurityImpl.java file.
3. Uncomment and modify the role-based logic around line 49. For example, to bypass mandatory MFA for the admin role:

   RoleDao roleDao = (RoleDao) AppUtil.getApplicationContext().getBean("roleDao");
   Role adminRole = roleDao.getRole("ROLE_ADMIN");
   mandatoryMfa = !user.getRoles().contains(adminRole);

4. Rebuild the plugin with your changes and upload the updated JAR file to your Joget instance.

Customizing the MFA User Interface

The plugin utilizes customizable FreeMarker templates to render the MFA screens:

MFA Activation Screen Customization

Modify the forceEnableTotpAuth.ftl template file to customize:

• The QR code layout,
• Instructions text and messaging
• Company branding elements
• Help text and support information

MFA Verification Screen Customization

Modify the verifyPin.ftl template file to customize: 

• Input field styling
• Error message display
• User guidance text
• Recovery options presentation

Applying UI Customizations

1. Make the desired changes to the FreeMarker template files in the plugin source.
2. Rebuild the plugin incorporating your custom templates.
3. Upload the customized plugin JAR file via Settings > Manage Plugins > Upload Plugin.
4. The updated interface will take effect immediately for all users.

Related Documentation

• Security Enhanced Directory Manager
• Multi-Factor Authentication using TOTP

Download Plugin

Download the plugin from the official GitHub Release Page.