Why teams turn on two-factor authentication in ERPNext
ERPNext can require a second factor for desk users, enforced by role, and that control only holds up when it is paired with a plan for website users, API logins and lockouts. In most ERPNext sites, general ledger, stock valuation, supplier bank details and payroll data sit behind the same login, so a stolen or reused password gives an attacker a wide view of the business. A second factor makes that stolen password far less useful on its own, which is why finance and HR leaders usually ask for it first.
Frappe's documentation describes two-factor authentication as a setting that can be applied to users and enforced by role, with the second step delivered through an authenticator app or an email or SMS code. The exact options, labels and enforcement behavior vary by version, so confirm the setting names and supported methods against the documentation for the version you run before you write a rollout plan. Enabling the feature is worth the effort for any site where desk users can reach financial or personnel records, and it becomes more important as the number of roles and users grows.
Two-factor authentication is one control among the login policies, password rules and single sign-on options covered in the rest of this hub. It does not replace them. Treat it as part of a single decision about how people sign in, and check how it interacts with your identity provider before you turn it on for everyone at once.
Choosing between authenticator apps, email codes and SMS codes
This table compares the second-factor methods you can offer ERPNext users: TOTP authenticator apps, email codes and SMS codes. Read each row against your own user base, and confirm which methods your ERPNext version and mail or messaging setup actually support before you commit to a policy.
| Factor | Authenticator app (TOTP) | Email code | SMS code |
|---|---|---|---|
| Security strength | Codes are generated on the device from a shared secret, so they do not travel over the network at login | Code depends on the security of the mailbox and mail transport, so a compromised mailbox defeats it | Codes can be intercepted or redirected through SIM swap or messaging-channel attacks, so it is generally the weakest option |
| Dependence on phone or mailbox | Depends on the user's phone or a device holding the authenticator, not on mail or carrier coverage | Depends on the user's mailbox being reachable and on your outbound email delivery working | Depends on the user's mobile number, carrier coverage and your messaging provider's delivery |
| User effort | One-time enrollment by scanning a QR code, then typing a six-digit code at each login | No enrollment, but every login waits on an email that may land in spam or be delayed | No enrollment beyond saving a number, but codes can be slow to arrive and users may need to retry |
| Cost of operation | Mostly one-time setup and user support; no per-message charges | Recurring mail volume and monitoring of your mail server or relay | Recurring per-message charges from your messaging provider, which vary by country and carrier; ask for current rates |
| When the user changes devices | The secret must be re-enrolled on the new device, so plan a recovery or reset step before the switch | Works on any device that can read the mailbox, with no re-enrollment | Works on any phone that holds the registered number, but a new number needs a profile update |
| What to confirm in your version | Confirm the TOTP option, enrollment screen and any recovery codes in your ERPNext version | Confirm whether email codes are offered as a login method and how your mail setup affects delivery | Confirm whether SMS is available at all in your version and how your messaging provider and carrier rules apply |
How to enable and enforce two-factor authentication by role
This sequence moves two-factor authentication from a pilot to an enforced policy for the roles that need it, with a test and a check at each stage so no one is locked out by accident. The output is a documented setting, tested login methods, and a confirmed list of exempt accounts.
Confirm the ERPNext version and delivery path
Record the ERPNext and Frappe Framework version your site runs, then confirm which two-factor methods and email or SMS delivery options that version offers. Check that outbound email works from the site's Email Account configuration, since email codes depend on it. Confirm the exact field names and menu locations in your version before changing anything, because they differ between releases. Done when you have a written note of the version, the methods available, and a successful test email sent from the site.
Pilot each method with a test account
Create a dedicated test user with no privileged roles and enable two-factor authentication for that account only. Sign in with each method you plan to offer, such as an authenticator app that supports time-based one-time codes, or email codes if your site sends them. Confirm the code arrives or generates, the login completes, and a wrong code is rejected. Done when every method you intend to allow has a recorded successful test login and the test account can recover through its own steps.
Enable two-factor authentication in System Settings
As a System Manager, open System Settings and turn on the two-factor authentication option, choosing the delivery method for the site as your version presents it. Save the change and check the setting persists after reloading the page. Keep your own session open in a second browser so you can revert the change if a problem appears. Done when the setting is saved, the test account is prompted at its next login, and you have confirmed the change in the audit or version history if your site records it.
Set the enforcement scope by role or user type
Decide which roles or user types must use two-factor authentication, and apply the requirement at the level your version supports, usually the user record or a role-based setting. Start with the highest-risk roles such as those that approve payments, change master data or export financial reports. Confirm the exact enforcement mechanism in your version's documentation before relying on it. Done when a written matrix lists each role, whether it is enforced, and the method it uses.
Test that users outside the scope are unaffected
Sign in as a user who does not hold an enforced role and confirm they are not prompted for a second factor. Then sign in as a user who does hold an enforced role and confirm the prompt appears and the login completes. Check that normal document access and reports behave the same for both accounts. Done when both test logins produce the expected result and you have noted which roles were checked.
Decide exempt roles and accounts
List any accounts that should be exempt, such as service or integration users, and document why each one is exempt and who approves the exemption. Remember that API logins and website user logins may not follow the same rules as desk logins, so confirm how each login path is treated in your version and compensate with other controls where needed. Done when the exemption list is approved, each entry has a stated reason, and you have checked each API or website login path against the policy.
Review System Manager accounts and recovery
Review every account that holds the System Manager role, confirm each one has two-factor authentication enabled, and remove the role from anyone who does not need it. Record the recovery path for each privileged account, including backup codes or a second device, and confirm who can reset a locked account. Done when the System Manager list is reviewed, every privileged account has a tested recovery route, and the list is stored with the access review records.
Where two-factor authentication reaches users and where it does not
Desk users are staff who sign in to the ERPNext desk with a username and password. This is the path the two-factor setting in System Settings is most often used to protect, but you should confirm how it behaves in your version, including which code methods it accepts and whether it can be required for specific roles or individual users.
- Setting scope: Check whether the setting applies to all desk users or can be restricted, and which code methods (authenticator app, email or SMS) your release supports.
- Role enforcement: Confirm whether enforcement by role is available. If it is not, plan to set the requirement per user and keep a register of who has it.
- Administrator account: Verify that the Administrator account is covered and that its recovery path is written down before you enable the setting.
- Existing sessions: Test whether sessions created before the change keep working without a second factor, and when the prompt next appears.
On a staging site running your version, sign in as a non-administrative user with a sensitive role, confirm the second-factor prompt appears on a fresh login, and confirm it cannot be bypassed by going straight to a desk URL.
Website and portal users sign in through the public login page to reach portals, web forms and customer or supplier pages. They are separate accounts from desk users, and they are often far more numerous. Do not assume that the desk configuration protects them. Confirm in your version whether the two-factor setting applies to the website login flow and whether portal accounts can be enrolled at all.
- Separate population: Count portal accounts by type before deciding. Customer and supplier accounts created in bulk can outnumber staff accounts.
- Login flow: Test the website login page with a portal user account, separately from the desk login page.
- Self-registration: If sign-up is open, confirm whether a new account can be created and used without enrolling a second factor.
- Compensating control: Where portal access must be protected, place the portal behind an identity provider or gateway that enforces a second factor, and confirm that its session covers the ERPNext portal pages.
List which portal pages expose financial or personal data, and treat any page that the second factor does not reach as a finding to close before go-live.
API access uses tokens or API keys and secrets, typically from integrations, scripts, reporting tools or mobile clients. A machine cannot answer an interactive second-factor prompt, so the two-factor setting does not protect these calls in the way it protects a person at a login form. Confirm how your version authenticates each integration and who owns each credential.
- Credential inventory: List every API key and token user, the role behind each, and whether the account belongs to a person or a service.
- Rotation and revocation: Confirm how keys are rotated, revoked and audited in your version, and assign an owner to each key.
- Session reuse: Test whether calls that reuse a browser session inherit a session that already passed the second factor, and whether that holds for your setup.
- Compensating control: Limit each API user with roles and user permissions, keep secrets out of source code, and where your architecture allows, place the API behind a gateway that enforces network allow lists or client certificates.
Ask the team to demonstrate that a revoked key stops working and that a key with a narrow role cannot read records belonging to another company or territory.
Users who sign in through LDAP or a social login never type a password into the ERPNext form. ERPNext checks LDAP credentials against Active Directory or OpenLDAP and maps directory groups to roles at each login, as described in the ERPNext LDAP integration documentation. Whether ERPNext's own second-factor prompt runs after these logins must be tested, and the stronger control usually sits at the directory or identity provider.
- Directory enforcement: Confirm whether your directory or identity provider requires a second factor for the accounts ERPNext uses, and whether that requirement applies to every sign-in path.
- Post-login prompt: Sign in through LDAP and through each Social Login Key on a test site, and record whether ERPNext asks for a second factor afterward.
- Provider configuration: Review the multi-factor policy of each provider you register through Frappe's Social Login Key guide, including any custom OAuth or OpenID Connect endpoint.
- Local fallback: Confirm whether a local ERPNext password still works for these accounts. If it does, the provider's controls can be bypassed.
Set enforcement at the directory or provider level, and keep a documented break-glass account whose second factor you have tested.
Security risks to close around two-factor authentication
Two-factor authentication only protects an ERPNext site if the weaker paths around it are closed. The risks below share one pattern: an attacker reaches a session, a fallback, or an exempt account without meeting the strong second check. Test each control in your own environment before you rely on it.
Weak fallback methods
If email or SMS codes remain available next to an authenticator app, an attacker only needs to defeat the weakest option you still allow. Review which second-factor methods each role can choose, and confirm that the login policy for your users requires the method you have approved. Test a login with each permitted method and record which ones succeed.
Email codes and mailbox compromise
Email codes are only as secure as the mailbox that receives them. An attacker who controls a user's inbox can read the code and complete the login, even with a strong password. Ask whether mailboxes used for ERPNext accounts have their own MFA, and check that outgoing login email is delivered only to the intended address.
Shared authenticator devices
When several people use one phone or one TOTP entry for a shared account, the second factor no longer identifies one person. This breaks audit trails for postings, approvals and payments. Require one enrolled authenticator per named user, and review accounts that show logins from several locations at the same time.
API keys and tokens that skip the prompt
API keys and OAuth tokens authenticate without the interactive login, so 2FA does not apply to them. A leaked key can read or write records long after a user has passed the second check. Inventory every API key and token, assign an owner, set a rotation schedule, and revoke any key that no active integration uses.
Exempt roles left without review
Roles or accounts excluded from 2FA, such as service users, integration accounts or administrators added for convenience, often stay exempt after the project that needed them has ended. Build a periodic access review that lists every exempt account, its roles and its owner, and removes exemptions that no longer have a documented reason.
Session lifetime beyond the second check
A session that stays valid for a long time means the 2FA check happens once and then protects little. A user who leaves an unlocked workstation, or a stolen session cookie, keeps access. Set session expiry and single-session rules in System Settings to match your risk, and test that an idle session is closed after the configured period.
Recovery planning before you enforce two-factor authentication
Enforcing two-factor authentication without a recovery process locks out the people who must fix the system. Decide who can reset a second factor and how that reset is verified before anyone is required to enroll. The cases to plan for are a lost or replaced phone, a departed employee whose authenticator is still registered, a failed email or SMS provider that cannot deliver codes, and an administrator who is locked out after enforcement is switched on. Each one needs a named owner and a documented step, not a conversation during an outage.
Write the recovery process as a short runbook that your security and IT leads sign off. It should name the roles allowed to reset another user's second factor, the identity check required before a reset (for example, a call-back to a known number or a manager confirmation recorded in your ticketing system), and the audit trail kept for each reset. Confirm with your own environment how your ERPNext version handles resetting two-factor settings for a user and whether the reset is logged, since the exact steps depend on your version and configuration. Also confirm what happens to codes sent by email or SMS when your mail or SMS provider is down, and whether a user can fall back to another method.
Before you turn on enforcement, keep a break-glass path and test it in a non-production copy of the site. The path should cover a second administrator account with its own strong credential and a second factor held by a different person, stored under dual control. Rehearse both the normal reset and the break-glass login so you know they work. Then link this work to the admin lockout recovery topic in this hub, because removing your own System Manager role or losing the Administrator password is a separate failure that two-factor enforcement makes more likely. Treat the rehearsal result as a go or no-go gate for the enforcement date.
Limits to confirm in your ERPNext version and hosting
Two-factor authentication in ERPNext depends on the version you run, how you host it, and which login paths your users take. The cards below list the questions to answer in vendor documentation or a test environment before you write the enforcement policy.
Which second-factor methods are offered
Confirm which methods your ERPNext version offers for the second factor, including authenticator apps that generate time-based one-time codes and email-delivered codes. Check whether each method is available at the system level, per user, or both. Record the exact menu path and setting names so your runbook matches the version you deploy, not a memory of an earlier release.
SMS delivery support
Ask whether your version sends SMS codes natively or only through a custom integration with an SMS gateway. If a gateway is needed, identify who builds, licenses and monitors it, how phone numbers are validated, and what happens to codes when the gateway is down. Do not assume SMS is available just because email codes are.
Enforcement for users with several roles
Test how a role-based enforcement rule behaves when one user holds several roles, some enforced and some not. Confirm whether the strictest rule wins, whether role profiles inherit the setting, and whether a change to a role takes effect at the next login or only for new sessions. Use a test user with a mixed role set and document the result.
Public or shared cloud hosting limits
Confirm with your hosting provider whether the chosen configuration is allowed on shared or public cloud benches. Some hosted plans restrict server-side code or outbound email and SMS, which can block the delivery path for codes. Check whether you can change these settings yourself or must request them, and whether a dedicated environment is needed to match your policy.
Coverage for website and API logins
Confirm whether the second factor applies to desk logins only or also to website users, portal logins and token-based API access. API keys and OAuth bearer tokens may bypass an interactive prompt entirely, so list every login path your integrations use and decide how each is protected, rotated and revoked.
Second factor already enforced upstream
If you sign in through LDAP or a social login provider, confirm whether your identity provider already requires a second factor. Enforcing a second prompt in both places can cause lockouts and confusing support tickets, while enforcing it in neither leaves a gap. Map which login path each user takes and assign one owner for the factor.
Questions teams ask before enabling two-factor authentication in ERPNext
Can our own team enable two-factor authentication in ERPNext without outside help?
Yes, for a single site with a small set of internal users, an in-house administrator can usually turn on two-factor authentication from the System Settings and test it with a few accounts. The work becomes harder when you need role-based enforcement across many users, custom delivery of codes, coverage for website users or API logins, and a recovery process that your staff have rehearsed. Decide early who owns the change, who approves it, and who can reset a locked-out user. A partner is most useful when those decisions are still open and the team lacks time to test each login path.
What makes the effort for 2FA rise or fall?
The main drivers are the number of roles that must be enforced, the identity sources in use, the delivery method for codes, and the scope of logins to cover. Enforcing 2FA for a few internal roles is far simpler than enforcing it for every user, including website users and API consumers. Single sign-on through LDAP or social login changes where passwords and second factors are checked, so it must be designed together with 2FA. SMS or custom delivery adds provider access, contracts and testing. Testing across browsers, mobile authenticator apps and recovery paths also adds effort.
Does enabling two-factor authentication require a paid plan or a hosting change?
The supplied pricing information shows that self-hosting ERPNext is free, and that Frappe Cloud has shared and dedicated hosting options at listed monthly starting prices. It does not state that two-factor authentication itself is tied to a particular plan, so confirm this with Frappe for the version and hosting model you plan to use. If you run ERPNext yourself, cost comes from your own infrastructure, the time of your staff, and any SMS or email provider you choose to add. If you plan to use custom delivery or external services, those vendors will have their own pricing.
How long does a pilot and full rollout take?
Timing depends on phases rather than a fixed duration, so ask for a plan built around them. A typical sequence includes confirming the version and identity setup, enabling two-factor authentication on a test site, piloting with a small group of internal roles, and then extending enforcement role by role. Each phase needs time for user communication, help desk support and fixes. Website users and API logins often take the longest because they need separate decisions. Your quote should show the phases, the exit criteria for each one, and the dependencies on your identity team and delivery provider.
What must our team provide before the work starts?
Prepare a role inventory that lists each ERPNext role, who holds it, and whether it needs stronger sign-in. Name administrators who can approve changes and reset accounts. Provide test accounts for each role and for website users if they are in scope. If you plan to use SMS or a custom email provider, give access to the provider account or a sandbox, and confirm who signs its contract. You should also share the hosting model, the current login methods, and any LDAP or social login settings, so the design reflects what already runs.
What should a fixed-scope quote for 2FA include?
A fixed-scope quote should state the ERPNext version and hosting model in scope, the roles and user groups covered, and whether website users and API logins are included or excluded. It should list the delivery methods, the test environments, the phases with deliverables, and the testing approach for each login path. Look for a recovery plan with documented steps for lost devices and locked accounts, a handover of configuration and runbooks, and the responsibilities for any third-party provider. Ask what is one-time work and what recurs, such as support or review after upgrades.
What risks should we check before enforcing two-factor authentication?
The most common risks are locking out every administrator, leaving an API or website login path unprotected, and assuming SSO users are covered when they are not. Before enforcement, confirm that at least two people can recover access, that a break-glass path exists, and that you know which logins bypass the checks. Test code delivery with real users, including those who change phones often. Also review how 2FA interacts with login policies, session settings and any external identity provider, so that one change does not silently weaken another.
How DeployOpen scopes and delivers two-factor authentication for ERPNext
DeployOpen treats two-factor authentication for ERPNext as a configuration change with access-policy consequences. We start from the roles, website users and API integrations that exist in your environment, then write down how each group will sign in, how it is enforced and how it recovers. The delivery is planned and documented inside your own infrastructure.
How we scope
- Inventory every role, desk user, website user and API integration that signs in to your ERPNext site
- Agree in writing which methods each role may use, such as authenticator apps or email codes
- Record the gaps for website users and API logins and decide how each one is handled
- Define the recovery path for lost devices before enforcement is switched on
How we build
- Configure two-factor authentication on a non-production site that mirrors your production role setup
- Enforce the policy by role and test the login flow for each role with real accounts you provide
- Verify the Server Scripts or login controls you depend on are enabled in your version before relying on them
- Document each setting change so it can be reproduced during upgrades and new site builds
How we hand over
- Deliver a written configuration record listing each setting, role mapping and test result
- Provide a user guide for enrolling authenticator apps and for requesting help during a lockout
- Walk administrators through the break-glass and recovery steps agreed in the scope
- Hand over the test scripts so your team can repeat the login checks after future changes
How we support
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts
- Ongoing support, version upgrades and continuous testing are available as a retainer
- Retainer scope can cover reviewing 2FA behavior after each ERPNext minor release
- Quotes follow from the written scope, so ask for the cost of each component listed in it
