Configuring multi-factor authentication

Multi-factor authentication adds an additional layer of security to the sign-in process. In addition to the basic password, users need to verify their identity using one or more additional security components.

The multi-factor authentication feature described on this page is supported only for the administration application. For the live site, you can implement your own multi-factor authentication functionality (for example, see the Two-factor authentication with ASP.NET Identity article).

By default, the administration interface provides support for a combination of standard forms authentication with a username and password, and a passcode generated by an authenticator application using the Time-based One-time Password Algorithm (TOTP), for example Google Authenticator.

The default multi-factor authentication process consists of the following steps:

1. A user wants to sign in and enters their username and password.
2. The system verifies the credentials, displays a secret key and requests a passcode.
3. The user enters the secret key into their TOTP authenticator application.
4. The application generates a temporary passcode.
5. The user types the passcode into the Xperience authentication form.
6. The system signs in the user.

The system only displays the secret key on the first sign-in after multi-factor authentication is enabled. The next time the user signs in, the steps related to the secret key are no longer required, and the user only generates a new passcode in their authenticator application.

Security and limitations

The multi-factor authentication is:

• Available only for the default forms authentication method.
• Not compatible with the Autocomplete functionality.

For security reasons, we strongly recommend limiting the maximum number of invalid sign-in attempts to a small value, for example 5. Incorrectly submitted passcodes count as invalid sign-in attempts, so potential attackers cannot guess a valid passcode in the specified number of attempts.

If the screen locking feature is enabled, entering of the passcode is also required when unlocking the screen.

Enabling multi-factor authentication

Enabling multi-factor authentication for selected users

1. Open the Settings application.
2. Select the Security & Membership -> Authentication category.
3. Select the Enable multi-factor authentication check box.
4. Click Save.
5. Open the Users application.
6. Edit the users for which you want to enable multi-factor authentication and enable the Multi-factor authentication is required option.

The given users will need to use multi-factor authentication when signing in to the Xperience administration interface.

You can also set up user account editing forms to allow users to choose whether to enable multi-factor authentication for their accounts. See Allowing users to enable or disable multi-factor authentication.

Enabling multi-factor authentication for all users in the system

To enforce multi-factor authentication for all users in the system:

1. Open the Settings application.
2. Select the Security & Membership -> Authentication category.
3. Select the following check boxes:
   • Enable multi-factor authentication
   • Multi-factor authentication is required globally
4. Click Save.

All users now need to use multi-factor authentication when signing in to the administration interface. The Multi-factor authentication is required option of individual user accounts has no effect with this configuration.

<add key="CMSAdminEmergencyReset" value="admin;password;true" />

Resetting the secret key for users

For multi-factor authentication to work, users need to enter a shared secret key into their authenticator application. The system displays this secret key to each user once during their first sign-in (after multi-factor authentication is enabled).

If a user loses the secret key before initializing their authenticator application, they will not be able to sign in. A new secret key is also required if a user wants to switch to a different authenticator application.

In these situations, administrators can reset the multi-factor secret of individual users:

1. Open the Users application.
2. Edit the given user account.
3. On the General tab, click the Reset button next to the Reset multi-factor secret field.

On the user’s next sign-in attempt, the system displays a new secret key, which the user can enter into their authenticator application.

Allowing users to enable or disable multi-factor authentication

If you have multi-factor authentication enabled only for selected users, you can allow users to choose whether to enable multi-factor authentication for their account via the My profile application. To achieve this, make the UserMFRequired field visible in the corresponding alternative form.

To configure the visibility of the UserMFRequired field in user alternative forms:

1. Open the Modules application.
2. Edit the Membership module.
3. Select the Classes tab and edit the User class.
4. On the Alternative forms tab, edit the Edit profile (MyDesk) form.
5. On the Fields tab, select the UserMFRequired field.
6. Enable the Display field in the editing form option.
7. Configure any required Field appearance settings.
8. Click Save.

Users can now enable or disable multi-factor authentication for their account in the My profile application on the Details tab.

Customizing multi-factor authentication

Developers can customize the parameters of the multi-factor authentication functionality by implementing a custom helper class that inherits from the CMS.Membership.MFAuthenticationHelper class.

The following example demonstrates how to register a custom helper that changes the length and validity interval of multi-factor authentication passcodes.

1. Open your administration application’s solution in Visual Studio.

2. Add a custom assembly (Class Library project) with class discovery enabled to the solution, or re-use an existing assembly.

3. Reference the project from the administration web project *(CMSApp**)*.

4. Add a new class under the project, inheriting from the MFAuthenticationHelper class.

   Example

   Copy

   
   
   
    using System;
   
    using CMS;
    using CMS.Membership;
   
    // Registers the custom MFAuthenticationHelper
    [assembly: RegisterCustomHelper(typeof(CustomMFAuthenticationHelper))]
   
    public class CustomMFAuthenticationHelper : MFAuthenticationHelper
    {
        /// <summary>
        /// The time interval for which the system considers multi-factor passcodes to be valid.
        /// Calculated as a time interval before or after the time of the authentication attempt. 
        /// The default value is 5 minutes.
        /// </summary>
        protected override TimeSpan ClockDriftTolerance
        {
            get
            {
                // Sets the passcode validity to 2 minutes before or after the time of the authentication
                return TimeSpan.FromMinutes(2);
            }
        }
   
        /// <summary>
        /// The length of the multi-factor passcode. The default value is 6.
        /// Important: For the authentication to work, the value must match the number of characters used 
        /// by the authenticator applications that generate passcodes for your users.
        /// </summary>
        protected override int PasscodeLength
        {
            get
            {
                // Sets the passcode length to 10 characters
                return 10;
            }
        }
    }
   
   
    

5. Save all changes and Rebuild the solution.

The custom helper in the example overrides the ClockDriftTolerance and PasscodeLength properties of the default MFAuthenticationHelper. When users attempt to sign-in with multi-factor authentication enabled, the system applies the customizations – passcodes must be 10 characters long and the validity tolerance is reduced to 2 minutes.