Two-Factor Authentication (2FA) in ERPNext

Two-Factor Authentication (2FA) adds an additional layer of security to ERPNext by requiring users to verify their identity using a one-time password (OTP) after entering their login credentials.

With 2FA enabled, users must successfully complete both password authentication and OTP verification before accessing the system.

Two-Factor Authentication significantly improves account security by protecting against unauthorized access even if a password is compromised.

1. Enabling Two-Factor Authentication

To activate Two-Factor Authentication, run the following command on your ERPNext server:

bench --site [sitename] set-config enable_two_factor_auth true

After enabling the configuration, open System Settings and configure the following:

• OTP Validation Method
• QR Code Expiry Time (for OTP App authentication)
• OTP Issuer Name

Supported authentication methods include:

• OTP App (TOTP-based authentication)
• Email OTP
• SMS OTP

2. Authentication Methods

ERPNext supports multiple OTP verification methods depending on your organization’s security requirements.

2.1 OTP App Authentication

OTP App authentication uses the Time-based One-Time Password (TOTP) standard.

Users can authenticate using applications such as:

• Google Authenticator
• Microsoft Authenticator
• Authy
• Other TOTP-compatible authenticator apps

When a user logs in for the first time after 2FA is enabled, an email containing a QR Code registration link is automatically sent.

After scanning the QR Code using an authenticator application, the app begins generating time-based verification codes that can be used during login.

OTP App authentication is generally considered the most secure 2FA option because it does not rely on email delivery or SMS networks.

2.2 Email Authentication

If Email OTP is selected as the authentication method, ERPNext sends a one-time password to the user’s registered email address during login.

Before using Email OTP, ensure that:

• An outgoing email account is configured.
• Email delivery is functioning correctly.
• Users have access to their registered email accounts.

2.3 SMS Authentication

If SMS OTP is selected, users receive a one-time password via text message.

Before enabling SMS authentication, verify that:

• SMS Gateway settings are configured.
• The SMS provider is active.
• Users have valid mobile numbers registered in ERPNext.

3. Role-Based Two-Factor Authentication

When Two-Factor Authentication is enabled, ERPNext automatically activates it for the All role.

As a result:

• All System Users must complete OTP verification.
• The Administrator account is also protected by 2FA.

Administrators can customize this behavior by:

1. Opening the Role document.
2. Disabling Two Factor Authentication for the All role.
3. Enabling it only for specific roles.

This allows organizations to enforce stronger authentication requirements only for sensitive roles.

Examples include:

• System Manager
• Accounts Manager
• HR Manager
• Compliance Officers

4. User Registration Process

For OTP App authentication, the first login process includes an additional registration step.

The workflow is:

1. User enters username and password.
2. ERPNext sends an email containing a QR Code registration link.
3. User opens the QR Code page.
4. User scans the QR Code using an authenticator app.
5. The app starts generating OTP tokens.
6. User enters the generated token to complete login.

Once configured, the authenticator application can be used for all future logins.

5. Email and SMS Notifications

When Email or SMS authentication methods are used, ERPNext automatically sends OTP notifications during the login process.

Users receive:

• Email-based verification codes for Email OTP.
• SMS-based verification codes for SMS OTP.

The generated OTP must be entered before access to ERPNext is granted.

6. Security Benefits of 2FA

Implementing Two-Factor Authentication provides several security advantages:

• Protects accounts even when passwords are exposed.
• Reduces risks associated with phishing attacks.
• Improves compliance with security standards.
• Provides additional protection for privileged users.
• Strengthens overall ERPNext system security.

Frequently Asked Questions

Q. I am unable to log in even after completing the setup process.

Answer:

ERPNext uses the TOTP (Time-Based One-Time Password) algorithm for authenticator applications.

Since TOTP depends on accurate system time, ensure that:

• Your device’s date and time are correct.
• Automatic time synchronization is enabled.
• The ERPNext server time matches your device time.

Even a small difference between device time and server time can cause OTP validation failures.

Related Topics

• User Management
• Role and Role Profile
• Role Based Permissions
• System Settings
• Email Account Setup
• SMS Settings