The MFA (Multi-Factor Authentication) module enhances iTop's security by adding multiple authentication methods and robust management options. This document provides an in-depth overview of the MFA module's capabilities, including configuration, user experience scenarios, and key security rules for administrators and users.

This extension provides Multi-Factor Authentication (MFA).

• iTop Administrator can force Users based on organizations and profiles to use a multi-factor authentication mode when login to iTop, out of those four supports modes:
  • Time-based One-Time Password (TOTP) Authentication
  • Email-Based Verification Code
  • Account Recovery via recovery codes

• Every User can choose the modes he prefers to use.

MFA usage is controlled by Multi-Factor Authentication rules

• A rule allow to force, enable or deny usage of MFA to Users matching the Profiles and Organizations of the rule
  • Forced: on next User login, once he has provided his login/password, he must configure the default MFA mode set in rule
  • Optional: once logged, User eligible to that rule, can opt-in for a MFA
  • Denied: once logged, User eligible to that rule, cannot configure any MFA mode.
• A rule specifies the denied MFA modes and the default one (new mode brought by an extension, would be allowed by default)

• They can be managed by Users with write access to “ResourceMFAMenu” class.

• Application tokens and user tokens are not affected by MFA.
• It is not possible to configure multiple security key (physical key and Hello windows for instance)

• iTop 3.2.1 minimum
• User menu “My Account” must be enabled to support gradual MFA deployment and user MFA modes configuration

Use the Standard installation process for this extension.

The configuration is located in the combodo-mfa-base part of $MyModuleSettings

Example of configuration for the extension:

'combodo-mfa-base' => array (
        'enabled' => true,
        'allowed-login-types' => array (
          0 => 'form',
          1 => 'basic',
          2 => 'url',
          3 => 'external',
        ),
),

While we do not recommend to uninstall the MFA module, it can be disabled using "enabled" => false, to use a third party MFA extension for eg.

If you want to activate de debug Mode you have to add the option 'MFA' ⇒ 'Debug' in the parameter 'log_level_min' of the global iTop configuration.
Debug messages are displayed in the error.log file

To activate MFA, the administrator must create Multi-Factor Authentication rules

Define them based on your company security requirements, with specific rules by profiles and/or organization, thus enforcing MFA for high-risk roles.
Later enforced authentication modes could be changed as security policies evolve.

Operational state:

• Forced: on next User login, once he has provided his login/password, he must configure the default MFA mode set in rule
• Optional: once logged, User eligible to that rule, can opt-in for a MFA
• Denied: once logged, User eligible to that rule, cannot configure any MFA mode.

In order to do this, administrator needs to modify every rule, adding the revoked MFA mode to the “Denied modes”.
If a User was using a revoked mode, he will be forced to use another mode (or none if rule “operational state” is “Optional”).

With “Operational state = Forced” and an “Activation date” set in the future, admins allow users to set up MFA modes without requiring immediate enforcement, facilitating gradual deployment. After login the user will be warned that MFA was enabled and will be mandatory after a scheduled date.

Once Multi-Factor Authentication rules are configured:

• some Users can be forced to configure the default MFA mode for themselves
• other Users can be allowed to add MFA modes for themselves
• and the denied Users would see no change, (no MFA configuration tab in “My Account” / “My profile”)

• Users with MFA modes configured, will have to login with MFA

If when a User login without any MFA configured and MFA is mandatory for him, then after authentication with login/password, he will be asked to configure an MFA mode.

This step varies by MFA default mode, user Operating System and browser

• TOTP: the second login form contains Configure your TOTP by App
  1. scan the QR code or enter the secret in your Authenticator App (any application supporting TOTP works)
  2. Copy the code generated by your application into the “Code” input field
  3. If iTop let you get in, the MFA is configured successfully.

• Email-Based Verification Code: the second login form asks for a Code received by email (the email of the Person associated to your User)
  1. within 10 minutes you must copy the email received code in the “Code” input field
  2. If iTop let you get in, the MFA is configured successfully.

MFA modes can be configured by Users

• Console Users through the User menu “My Account” and the tab “Multi-Factor Authentication”
• Portal users have access to MFA configuration in their “My profile” page.

Console users	Portal users

Users can configure additional MFA modes and select their preferred mode from the list of available ones.
Users cannot add a totally new MFA mode, they can only configure the ones which are proposed.

This mode is use to application like Google Authenticator, Microsoft Authenticator or Chrome Authenticator plugin for instance
It is often more secure than using a basic code via Email

Configure your TOTP by App

1. scan the QR code or enter the secret in your Authenticator App (any application supporting TOTP works)
2. Copy the code generated by your application into the “Code” input field
3. then get a confirmation message
4. Exit this page using the left menus or the breadcrum

This mode is used to send a unique code via email

Email-Based Verification Code: There is two steps for the configuration

Step 1 (optional)

1. enter an email address different than the one on your iTop User and press “CHANGE MFA EMAIL ” button. This step is used if you want to use an alternative email for MFA

Step 2:

1. Press button “Send code by email”
2. within 10 minutes you must copy the email received code in the “Code” input field
3. then get a confirmation message
4. Exit this page using the left menus or the breadcrum

MFA Recovery codes

1. Copy in a safe place the displayed Recovery codes

• Store your security key securely and avoid sharing it with others.
• Use trusted authentication apps only for TOTP-based methods.
• In case of a lost authentication device, use your recovery codes or contact the administrator for account recovery options.

All those actions are available on Portal and on Console, the only differences are cosmetics

Changing default mode	Removing an MFA mode & Restore a removed mode

Users with MFA enabled, after they have provided a valid login/password, will be prompt with their default MFA mode. They can switch to another MFA configured modes if they wish.

1. Copy the code generated by your Authenticator application into the “Code” input field
2. iTop should let you get in as soon as the code is copied
3. If it does not maybe the code was expired, so try again to copy the next code from your Authenticator App.

1. Press button “Send code by email”
2. within 10 minutes you must copy the email received code in the “Code” input field
3. iTop should let you get in as soon as the code is copied

1. Retrieve your saved Recovery codes from the safe place where you stored them
2. Copy one of those Recovery code into the “Code” input field
3. iTop should let you get in as soon as the code is copied
4. Removed the used code from your saved Recovery codes, as once used one time, it is dead and cannot be reused.

Question: How can i deactivate my MFA configuration if i'm the only administrator and i lost my MFA access
Answer: This may happen for instance if you have configure a physical security key and you lose it, and you have no alternative MFA mode configured (recovery code for instance) In that case you have to follow the below steps:

1. deactive MFA in the configuration file
2. connect to iTop with your login and password
3. search the Object using the followinf query SELECT MFAUserSettings WHERE user_id_friendlyname='your login'
4. delete the corresponding element
5. reactivate MFA in the configuration file
6. Reconfigure MFA for your account

Question: How can i change the mail format when a code is sent by email
Answer: There is two entries in the iTop dictionary that can be changed if you want to adapt de subjet or the body of the email:

MFATOTP:Mail:EmailSubject : '%1$s - Code to connect. Expires at %3$s',

MFATOTP:Mail:EmailBody : '<body><p>The code to connect to %1$s as %2$s is</p><strong>%4$s</strong><p></p><p>This code is valid until %3$s</p><p>If you are not trying to connect to %1$s, please contact your administrator.</p>',

• %1$s = name of the iTop application
• %2$s = user corresponding to the code
• %3$s = expiration hour and minutes
• %4$s = MFA code