Enabling two-factor authentication in EspoCRM for regular users
EspoCRM has built-in two-factor authentication with TOTP, email and SMS methods, and the EspoCRM security docs recommend requiring 2FA for logins. If your admins or security lead are worried about stolen passwords reaching customer data, pipeline and quotes, this is the first control to switch on for regular users. It matters most where sales and service staff sign in from laptops and phones outside the office, where CRM exports and mass email are available to any user with the right role, and where a single compromised account could expose many customer records. The decision is not whether to use 2FA but which method each group can realistically use, and whether your identity provider will handle it instead.
Before you enable it, check one constraint that changes the design: EspoCRM's own 2FA is not compatible with OpenID Connect sign-in. If you have set up OIDC, the identity provider's MFA must enforce the second factor, and EspoCRM's built-in 2FA should not be relied on as a second layer. Confirm this with your EspoCRM version and your identity provider's documentation, since the two login paths interact differently for admins and fallback logins. Also decide which method is acceptable for your risk profile: TOTP apps are generally stronger than email codes, and SMS depends on your telephony and recovery arrangements. Plan how users with no smartphone or lost devices will recover access, because an unplanned lockout is the most common reason 2FA rollouts stall.
Plan the rollout as a short, written sequence rather than a single switch. Pilot with a small group of regular users, confirm the enrollment steps work on your actual devices, and document the recovery path for lost devices that admins will follow. Then require 2FA for the regular user population and keep admin and API accounts on their own controls, since those are covered in other sections. Recheck the setting after upgrades, because login behavior can change between EspoCRM releases. The EspoCRM security documentation is the right reference to confirm the current options for your installed version before you publish the policy to users.
Which 2FA method fits which user group
Time-based one-time passwords (TOTP) are the method to start with for most regular users. The user scans a QR code once with an authenticator app, and from then on the app generates a short-lived code that EspoCRM checks against the server clock. The method does not depend on mail delivery or a phone network, so a sign-in keeps working during a mail outage.
- Dependency: the user's device clock and the EspoCRM server clock must agree closely, so confirm server time synchronization before rollout.
- Recovery: plan how a locked-out user regains access, such as an administrator reset, and document who is allowed to perform it.
- Device change: a user who replaces a phone needs a re-enrollment path that does not rely on the old device.
- Shared accounts: TOTP is tied to a named person, so shared logins cannot be protected this way and should be removed first.
Before rollout, test enrollment, a failed code and a reset on a pilot group, and confirm the authenticator apps your staff use are supported by your EspoCRM version.
Some users, such as field staff, seasonal staff or people who cannot install apps on a work device, may not have an authenticator app available. EspoCRM offers email-based codes for this situation, and the sign-in succeeds only if the code arrives in a mailbox the user controls. That makes the mail system part of the authentication path.
- Dependency: outbound mail from your EspoCRM instance must be configured, authenticated and reliable, or users cannot complete sign-in.
- Mailbox security: a compromised mailbox defeats the second factor, so this method is weaker than a device-bound app and should be limited to users who truly need it.
- Delay: codes that arrive late will expire or frustrate users, so test delivery time to the mail providers your staff use.
- Monitoring: watch the mail queue and bounce handling, because a silent mail failure looks like a login failure to the user.
Confirm with your mail administrator how outbound mail is routed and whether the same mail service is used for other business functions before you depend on it.
When EspoCRM sign-in is delegated to an OpenID Connect identity provider, EspoCRM's own two-factor authentication is not compatible with that path. The identity provider's multi-factor authentication (MFA) becomes the control that applies to these users, and EspoCRM relies on the identity provider's assurance. Choosing this route means the MFA policy lives in the identity provider, not in EspoCRM settings.
- Policy location: confirm which MFA methods the identity provider offers and enforce them for every application that signs in to EspoCRM.
- Fallback login: OIDC configuration includes a fallback login method, so decide whether it is available and whether it must also be protected.
- Admin accounts: check whether administrators are routed through the same identity provider policy or sign in another way.
- Logout: verify backchannel logout behavior so that a disabled identity provider session also ends the EspoCRM session.
Confirm the identity provider's MFA options and their enrollment process with the team that runs it, and test a complete sign-in, fallback and logout before relying on it.
SMS is the third option in EspoCRM's method list, but it depends on something outside the CRM: a working SMS gateway that your organization has approved and paid for. The documentation and your environment decide whether SMS is available to you, so do not assume it is ready because it appears in the interface. Treat SMS as a method to confirm, not a default.
- Gateway: confirm the SMS provider, the integration method and the countries and carriers you need to reach.
- Cost and contract: message costs and contract terms come from your gateway provider, so request them in writing.
- Phone numbers: users must maintain accurate mobile numbers in their profiles, which needs an owner and a process.
- Interception risk: SMS is generally considered weaker than app-based codes, so document why you accept it for any user group.
Before planning around SMS, confirm with your EspoCRM administrator and gateway provider that the feature is supported in your version and works in your network, including outbound access from the server.
Configuration options and when each fits
This table compares the main ways to turn on two-factor authentication in EspoCRM, from TOTP apps to email and SMS codes, mandatory enforcement for regular users, and the identity provider's MFA route. Read each row for the situation it suits and the trade-off you accept, then decide which combination matches your sign-in model.
| Option | When it fits | Trade-off to plan for |
|---|---|---|
| Enable TOTP | Teams that want an authenticator app on each user's device without depending on mail or phone networks | Users must enroll before enforcement, and lost devices need an admin recovery path that you define in advance |
| Enable email or SMS codes | Users who cannot install an authenticator app, or a short-term fallback during rollout | Sign-in depends on mail delivery or SMS reachability, so delivery delays or outages block logins; confirm which methods your build supports |
| Require 2FA for regular users | Environments where every user must meet the same second-factor standard, such as customer data in sales and service | Users who have not enrolled may be locked out until they complete setup, so schedule enrollment before enforcement |
| Use the identity provider's MFA with OIDC | Organizations that already run central MFA and single sign-on for all applications | EspoCRM's own 2FA is not compatible with OIDC, so you lose built-in second-factor controls and rely on the identity provider's policy and recovery |
| Keep admin accounts on built-in 2FA | Administrators who hold the strongest permissions and need a second factor even when regular users sign in through OIDC | Only applies when OIDC is not the sign-in path for those accounts, so confirm the login route for each admin before relying on it |
Setup sequence for 2FA in EspoCRM
This sequence turns on two-factor authentication in a controlled order, starting with the sign-in method you already use and ending with every regular user enrolled. Each step closes with a check so that a lockout is caught on a test account, not in front of the whole team.
Confirm the sign-in method
Before changing any setting, confirm whether users sign in with EspoCRM local accounts, LDAP, or OpenID Connect. EspoCRM's own two-factor authentication is not compatible with OIDC, so OIDC deployments will rely on the identity provider's MFA instead. Document the method, the identity provider or directory in use, and which accounts are admin accounts. The output is a short written record that the rest of the sequence refers back to. Ask your identity team to confirm how their MFA is enforced if OIDC is in use.
Confirm server time and recovery access
TOTP codes depend on the clock on the EspoCRM server, so check that the server time is synchronized before enrolling anyone. Then confirm a recovery path for administrators: a second admin account that is not used for daily work, and access to the server or database from which an admin can reset a locked account. Verify both by logging in to the recovery account and by confirming shell or database access works. Do not proceed until both checks pass.
Enable the 2FA methods in administration
In the EspoCRM administration area, open the two-factor authentication settings and enable the methods your policy allows: TOTP authenticator apps, email codes, or SMS codes. Email and SMS depend on mail or SMS delivery being configured and tested, so confirm that outbound email works before enabling them. Save the settings and record which methods are active. The check is a saved configuration that matches your written decision from the first step.
Test with an admin account first
Enable two-factor authentication for an admin test account and enroll it through the normal user flow. Sign out, then sign in again and complete the second factor. Test each method you enabled, including a failed code, so you know how the error appears to users. The checkpoint is a successful login from a clean browser session, plus confirmation that the test account can still reach administration. Keep the second admin account enrolled as well.
Require 2FA for regular users
Once the admin test passes, set two-factor authentication to be required for regular users in the administration settings, and decide whether to require it for every user type or only for certain roles. Communicate the enrollment steps and the expected first sign-in experience to users before the change takes effect, and name a contact for lockouts. The output is a saved requirement setting and a notice that users received. Confirm the setting applies to the group you intended.
Verify enrollment from a clean session
After the requirement is active, check a sample of regular users from different roles and teams. Ask each to sign in from a clean browser session and complete enrollment, then review the enrollment status in administration to find anyone who has not finished. Confirm that a user who has not enrolled is prompted to do so and cannot skip the step. The checkpoint is a list of enrolled users with no unexplained gaps.
Document the lockout and recovery procedure
Write down how a locked-out user is recovered: who can reset second factors, how that request is verified, and how the reset is logged. Include the admin recovery path tested in the second step, and make sure it does not depend on a single person. Store the procedure with your access records and review it after each change to 2FA or the identity provider. The output is a tested runbook that the support team can follow without guessing.
Why TOTP codes fail when server time drifts
TOTP codes are only valid for a short time window, so a clock that is slightly wrong on either side can make a correct code fail. A TOTP code is derived from the current time and a shared secret. EspoCRM checks the code against the time on its server, and the user's authenticator app computes it from the time on the phone or computer. If the EspoCRM host has drifted, codes generated by a correctly synchronized app will fall outside the accepted window and be rejected. Users then report that 2FA works on one day and not the next, or that it fails for everyone at once, which usually points to the server rather than to the people using it.
Check the server first. On a Linux host, confirm that the system clock is synchronized with NTP or the host's time service, for example by reviewing the status output of timedatectl and confirming that network time synchronization is active. On a managed cloud instance, the platform may run its own time service, so confirm which one applies and whether the instance uses it. Also confirm the time zone and hardware clock settings, since a correct clock with the wrong zone can confuse logs and audit trails even though TOTP itself uses UTC. If the EspoCRM stack runs in containers, check the time service on the container host, because containers share the host kernel clock. Compare the server time against a trusted reference after any change to virtualization, snapshots or VM restores, since those are common sources of drift.
The exact time-sync approach depends on your hosting platform, whether that is bare metal, a hypervisor, a public cloud or a Docker host, and on your network policy for outbound NTP. Confirm with your infrastructure team which time source is authoritative, how drift is monitored and who is alerted when it exceeds your tolerance. Build that check into your operations routine so that a failed login spike is investigated against the clock first. Confirm the TOTP settings and any time-window behavior in the EspoCRM 2FA documentation for your installed version before you rely on them in the rollout plan.
Security and operational risks of 2FA
Turning on two-factor authentication changes how people sign in, recover access and get audited. The risks below connect because each one can lock out administrators or leave enforcement gaps, so plan the recovery path and the identity provider boundary before you enforce anything.
Admin lockout and recovery paths
If an administrator loses the only second factor, nobody may be able to sign in to fix it. Before enforcement, confirm which administrator accounts exist, which methods each one uses, and who can reset another user's 2FA from inside EspoCRM. Keep at least two administrator accounts that are tested and enrolled, and store a documented break-glass procedure that your team can run without depending on one person. Avoid using admin accounts for daily work, as the EspoCRM security docs recommend.
Dependence on email and SMS delivery
Email and SMS codes depend on mail servers and carrier networks that you do not fully control. A mail outage, a misconfigured sender or a number change can block every user at once. Test each delivery method end to end with real accounts, confirm your outbound mail path works from the EspoCRM host, and decide which method is the default and which is the fallback. Where SMS is used, document who owns the phone number records and how they are updated.
TOTP time drift
Time-based one-time passwords only validate when the server and the user's device agree on the time. A server clock that drifts from accurate time can reject valid codes for many users, and the failure looks like a bad password. Confirm that the EspoCRM host and its database server synchronize time through a managed NTP service, and include clock checks in your runbook for login failures. Test enrollment from several device types before the rollout.
MFA enforced at the identity provider
EspoCRM's own two-factor authentication is not compatible with OpenID Connect sign-in. If you route users through an identity provider, the MFA policy must live there, and EspoCRM's 2FA settings do not protect those logins. Check that the identity provider requires MFA for every EspoCRM client, that the fallback login method is controlled, and that users cannot bypass the provider through a local EspoCRM password path.
Lost device recovery
A user who loses a phone or authenticator app needs a controlled way back in without a helpdesk shortcut that an attacker could imitate. Define the identity check the helpdesk must complete, who may reset a second factor, and how the reset is logged. Ask whether recovery codes are issued and how they are stored. Keep the process the same for every user, including executives, so that the reset path cannot become a weak point.
Auditing enforcement across users
Turning on 2FA as a policy does not prove that every account complies. Some users may have enrolled late, others may use exempt accounts such as API users, and portal users may follow different sign-in paths. Build a recurring report of enrolled and unenrolled accounts by user type, review exceptions with a named owner, and keep the evidence with your access review records. Ask your implementation partner which EspoCRM screens and logs you will use for this check.
Questions buyers ask before enabling EspoCRM 2FA
Does enabling two-factor authentication in EspoCRM cost money?
The EspoCRM open-source edition is free to download and self-host, so the software itself adds no licence fee. Cost comes from the work around it: configuring 2FA methods, deciding the policy for regular users, testing sign-in paths, and training staff. If you run EspoCRM Cloud, plans are priced per user per month, with the Basic plan at 15 US dollars per user per month (minimum 3 users) according to the EspoCRM pricing page. Any services quote should itemize configuration, testing, mail or SMS setup, and documentation separately, and should state whether it is one-time or ongoing support.
How much effort does a 2FA rollout take in EspoCRM?
Effort depends on the chosen methods and how many sign-in paths exist. Turning on TOTP is a configuration task, but it must be tested with real authenticator apps, a correct server clock, and a recovery plan for lost devices. Email or SMS methods add dependencies on your mail relay or messaging provider. If OpenID Connect is in use, the work shifts to confirming the identity provider's MFA policy and checking that EspoCRM's own 2FA is not relied on in that path. Ask any provider to list the methods, sign-in paths and test cases they will cover before quoting.
Can an internal admin enable 2FA without outside help?
Yes, a competent EspoCRM administrator can enable 2FA on a standard instance, because the settings live in the administration area and the steps are documented. The harder part is the surrounding decisions: which methods to allow, whether to require 2FA for all regular users or a subset, how to handle users without a device, and how to test without locking out administrators. Teams without a second administrator, or those with mail, identity and compliance dependencies, often find an outside review useful to confirm the rollout order and rollback steps before users are affected.
What does the business need to provide for the 2FA work?
Plan to provide three things. First, an owner for the identity provider if OIDC or LDAP is involved, because MFA policy may already be set there. Second, the details for the methods you intend to use: a working outbound mail server for email codes, and an SMS provider account and sender details if SMS is in scope, with any data-residency or approval rules that apply. Third, a group of test users covering administrators, regular staff and any portal or API accounts, along with a time window when disruption is acceptable. Ask for these inputs to be listed in the written scope.
Does EspoCRM two-factor authentication work with OIDC sign-in?
Not in the same way. EspoCRM's documentation states that its own 2FA is not compatible with OpenID Connect sign-in, which supports user creation on first login, team mapping from identity provider groups, backchannel logout and a fallback login method. For OIDC users, MFA should be enforced by the identity provider. Confirm the fallback login method carefully, because it can become a path around MFA if it is not governed. Your engineers should test each login route, including the fallback, after any change.
Why does server time matter for TOTP codes in EspoCRM?
TOTP codes are generated from the current time, so the server clock and the user's device must agree closely enough for codes to validate. If the server drifts, valid codes will be rejected and users will appear to be locked out. Check time synchronization on the application host, and test with several devices before the policy is enforced. This is an engineering check that should be included in the written test plan, not a one-off assumption.
How long should a 2FA rollout take for a team?
No duration can be stated here without knowing the instance, the number of users and the identity setup. Rollout length is driven by how many methods are offered, whether email or SMS depends on external providers, how many sign-in paths need testing, and how much user communication and device enrollment is needed. A phased approach, starting with administrators and a pilot group before enforcing for all regular users, is usually easier to reverse if something fails. Ask any provider for a dated plan tied to these phases.
Where to read the official EspoCRM security and OIDC guidance
Before you finalize the 2FA design, read the official EspoCRM security documentation and the OIDC documentation side by side, because they answer different parts of the same access question. The security guidance recommends requiring 2FA for users and restricting access by IP address, and it also covers password policy, avoiding admin accounts for daily work and limiting auth token lifetime. Treat those recommendations as the baseline your own policy is measured against, not as a checklist you can tick off without deciding how each one applies to your user types.
The EspoCRM security documentation is the next read for the controls this topic depends on: enforcing 2FA for regular users, deciding whether admins keep their own second factor, and pairing 2FA with an IP allowlist for office or VPN access. Read it with your identity owner in the room, and confirm in your own test instance which settings apply to your EspoCRM version, since the menu names and defaults can change between releases.
The EspoCRM OIDC documentation is the read to do before you decide where MFA lives. It describes sign-in through an external identity provider, optional user creation on first login, group-to-team mapping, backchannel logout and a fallback login method. It also states that EspoCRM's own 2FA is not compatible with OIDC, so your identity provider's MFA becomes the control that matters. Confirm the fallback login behavior with a test before rollout, because it determines how administrators sign in when the identity provider is unavailable.
How DeployOpen scopes and delivers EspoCRM 2FA
DeployOpen plans and implements EspoCRM two-factor authentication inside your own infrastructure, starting from the login methods your users need and the identity provider you already run. Engagements are fixed-scope, with the method choice, policy settings, testing and handover agreed in writing before any configuration changes are made.
How we scope
- Confirm which 2FA methods (TOTP, email, SMS) your user types and regions can actually use before choosing them
- Decide whether EspoCRM native 2FA or your identity provider's MFA applies, since the two are not compatible when OIDC is enabled
- Agree in writing which user groups must enroll, the enforcement date, and how admin and API accounts are handled
How we build
- Configure the chosen 2FA methods and required-for-users policy in a staging instance that mirrors your production setup
- Verify server time synchronization on the application host, since TOTP codes depend on accurate clocks
- Test enrollment, recovery and login paths for each role, including portal users and the fallback login method if OIDC is in use
How we hand over
- Document the final login policy, enrollment steps and recovery procedure in a runbook your help desk can follow
- Walk your administrators through changing 2FA settings, resetting a user's second factor and reviewing the configuration
- Record every setting changed so your security team can compare the deployed state with the agreed scope
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover
- Re-check 2FA behavior when you upgrade EspoCRM or change your identity provider, since login flows can shift
- Ask any partner, including us, to confirm current EspoCRM documentation before relying on a specific setting
