How to recover a lost EspoCRM admin password without losing data
When the only admin password is lost and sales, service and reporting depend on the instance, the work is done on the server, not through the login page. Recovery is a documented, server-side procedure: you reset the password from the command line, re-enable admin password recovery if your policy allows it, and keep a break-glass admin account so the next lost password does not stop the business. This page covers the set-password command, the passwordRecoveryForAdminDisabled setting in data/config.php, and how to plan a break-glass account. DeployOpen implements, hardens and supports EspoCRM in your infrastructure, but it does not issue audit reports, attestations or certifications. Any recovery action changes an authentication control, so record who performed it, when, and why, and keep that record with your change log.
Before touching the server, confirm who has shell access to the host, which database and data/config.php file belong to the production instance, and whether a current backup exists. Recovery changes the admin credential, so treat it as a privileged change. The security documentation recommends disabling password recovery for admins, which is why admin self-service recovery is often off. Decide in advance whether your organization will allow the setting to be turned back on, for how long, and who approves it. Keep that decision short and documented, and set the setting back to its hardened value once access is restored.
The longer-term fix is a break-glass admin: a named, non-daily account that holds admin rights, has a strong credential stored in your secrets vault, and is tested on a schedule. Daily work should happen in other accounts, as the security guide advises. Ask your implementation team to confirm how that account interacts with your SSO and two-factor settings, because a break-glass login that depends on the same identity provider it is meant to back up may fail in the same outage. Test the account in a non-production copy before you rely on it.
Recovery options and when each fits
This table compares the three ways to regain admin access: resetting the password from the server shell, temporarily re-enabling admin password recovery, and using a break-glass admin account prepared in advance. Read each row against your own server access model and your tolerance for reopening a recovery path. The main takeaway is that the first option depends on shell access, the second weakens a control you chose to turn off, and the third is only useful if it was set up before the lockout.
| Path | When it fits | Who needs server access | Main trade-off |
|---|---|---|---|
| Set password from the CLI | The admin password is lost, the instance is reachable by your operations team, and no other admin can sign in | Someone with shell access to the EspoCRM server or container who can run the console command as the web server user | Requires shell access and a documented change process, and the new password should be rotated once access is restored |
| Re-enable admin password recovery | Recovery is disabled by policy and the CLI route is not available to you, so you need the reset email flow back temporarily | Someone who can edit data/config.php and then reverse the change, plus whoever controls the mailbox that receives the reset link | Reopens a self-service recovery path the security guide recommends disabling for admins, so it must be switched back off after use |
| Pre-provisioned break-glass admin | You want a second admin path that works when the main admin account is locked, the email route is down or the primary identity provider fails | Created and stored by the administrators ahead of time, with access held by a small named group and not used for daily work | Only protects you if it was created, tested and kept current before an incident, and it becomes another privileged account to monitor |
| Recovery by email reset | Mail delivery to the admin address works and the account is still reachable through the login page | The admin's own mailbox owner, with no server access needed | Depends on mail flow and mailbox security, so a compromised or unmonitored mailbox becomes an admin takeover path |
Steps to regain admin access on the server
This sequence restores a working administrator login on a self-hosted EspoCRM instance while keeping a recoverable copy of the system and leaving the recovery setting back in its secure state. Each step ends with a check so the next change is made on confirmed ground.
Confirm shell access to the host or container
Before anything else, confirm who can reach the server, the Docker host or the container running EspoCRM, and that you can open a shell there with rights to the EspoCRM directory. Your team lead or platform owner should approve the access window in writing, and the person doing the work should be the one who will log the change. Done means you can list the EspoCRM application directory and see the data folder, which holds the configuration file. If you cannot reach it, stop here, because every later step depends on it.
Identify the running instance and its owner
Confirm which EspoCRM instance is affected, its version, the web server user and where the database lives. The version matters because CLI commands and configuration keys can change between releases, so check the EspoCRM documentation for your exact version before you run anything. Record the hostname, install path, PHP version and the account that owns the files. Done means the record is written into the change ticket and matches what the server reports.
Back up files and database before changing anything
Take a full copy of the EspoCRM files, including data/config.php, and a dump of the database before you edit configuration or reset any account. Store the copy somewhere the change does not touch, and verify the archive opens and the dump is not empty. If the instance runs in Docker, capture the relevant volumes as well. Done means you have a labeled copy with a checksum recorded in the ticket, and someone other than the operator has confirmed it is readable.
Reset the admin password or re-enable recovery
Choose one of two routes. The first uses the EspoCRM command-line tool to set a new password for the admin account, with the exact syntax confirmed against the documentation for your version. The second sets passwordRecoveryForAdminDisabled to false in data/config.php so the admin recovery flow is available again. Make only the change you need and record the exact line you changed. Done means the command reports success or the configuration key shows the expected value when you read the file back.
Check the configuration file and permissions
Read data/config.php again and confirm the edited value is saved, the file still parses as valid PHP, and the web server user can read it. A file that the web server cannot read can cause the application to fail to load, which can look like a login problem. Check the file owner and mode against your baseline from the backup step. Done means the file reads cleanly, the value is correct, and a simple request to the login page loads without a server error.
Sign in and verify administrator rights
Sign in with the admin account using the new password or through the recovery flow, then open the administration panel and confirm the account can reach it. Check that the user has the expected admin role and can view system settings. Confirm the action appears in the EspoCRM application log or your server logs so there is a record of who signed in and when. Done means the administration panel opens and the sign-in event is visible in the logs.
Revert the recovery setting and record the change
Once you have verified access, set passwordRecoveryForAdminDisabled back to true in data/config.php, following the security guidance to disable password recovery for admins, and check that the file saves and the web server user can still read it. Then update the ticket with the steps taken, the backup location, the account used and the time of each change. Done means the setting is back in its secure state, the file checks pass again and the record is complete.
Plan a break-glass admin account
Schedule a follow-up to create a separate, named emergency administrator account with a strong, stored credential and multi-factor protection where the platform supports it, so this procedure is not needed again. Use a personal admin account for daily work, and keep the emergency account for recovery only. Confirm the current EspoCRM security documentation for how to restrict admin use and how to test that the emergency account signs in. Done means the account exists, its credential is held under your secrets process, and a sign-in test is scheduled.
Security risks when recovery is re-enabled or an admin is kept in reserve
Recovering the admin password usually means temporarily weakening a control, and a break-glass admin is a deliberately powerful account. Both need to be closed or tightly governed once access is restored. The cards below cover the risks that tend to outlive the incident.
Recovery left switched on
Setting passwordRecoveryForAdminDisabled to false in data/config.php re-enables password recovery for admin accounts. The EspoCRM security guidance recommends disabling admin password recovery, so the change should be reverted as soon as the account is back under control. Check the file after the incident, confirm the setting is back to its hardened value, and record who made the change and when. An attacker who controls an admin mailbox could otherwise reset the password through the normal recovery flow.
Break-glass credentials stored carelessly
A break-glass admin only helps if its credentials are reachable during an outage and protected the rest of the time. Store the password in a sealed, access-logged vault that more than one authorized person can open, not in a shared spreadsheet, a chat thread or a developer's notes. Rotate the credential after every use and after any staff change. Ask who can retrieve it, how that access is logged, and how the vault itself is recovered if your identity provider is down.
One admin shared by several people
When several staff use the same admin login, changes cannot be attributed and revoking one person's access means changing the password for everyone. Give each administrator a named account with the admin role, and keep the break-glass account separate and used only by an approved owner. Shared logins also undermine the two-factor controls the security guidance recommends, because the second factor is tied to one device. Review the list of admin users after the incident and remove any accounts that are no longer needed.
Sessions surviving a password change
Changing a password does not necessarily end sessions or API tokens that were issued before the change. The security guidance recommends limiting authentication token lifetime, so confirm the configured lifetime and check whether an attacker's session could still be active after the reset. Also review API users and their keys, because those are not tied to a person's login. Test by signing in from a second browser after the reset and confirming the old session is rejected. Confirm the exact behavior for your version with EspoCRM's documentation before you rely on it.
Daily work on the admin account
If the admin account is also used for routine tasks such as editing records, reviewing email or building workflows, a phishing or malware compromise on that browser gives an attacker full control. The security guidance recommends avoiding admin accounts for daily work, so the recovered admin should be used for configuration only, and a standard user account for everything else. Keep the break-glass account out of daily use entirely. Ask who signs in as admin and from which networks, and restrict access by IP address where your network allows it.
SSO without a planned fallback
EspoCRM's own two-factor authentication is not compatible with OpenID Connect sign-in. On an SSO deployment, the identity provider carries the second factor, so a password-only local admin path becomes the exception that bypasses it. Plan a break-glass admin that can sign in without the identity provider, protect it with a strong password policy and a hardware-backed second factor where your tooling allows, and test that it works before an outage. Document the fallback login method your OIDC configuration uses, and confirm how it behaves when the identity provider is unreachable.
Designing a break-glass admin account
On a single-server instance, the break-glass account is a second administrator that exists only for emergencies, separate from the daily admin and from any named staff account. Create it with a long, unique password and a username nobody uses day to day. Keep the account off the working roster of users, and do not give it a personal mailbox that someone reads every day. The password should be held in a sealed record controlled by two or more people, not in a browser on the administrator's laptop. Because the server is the only access path, restrict the EspoCRM login to known networks where your policy allows it, and confirm with your team how the admin panel is reached. Test the account on a fixed schedule by signing in, confirming admin rights, and rotating the password afterward.
- Dedicated account: Create one admin user whose only purpose is emergency access, with no routine use.
- Sealed credentials: Store the password in a vault or sealed envelope with named custodians and a documented access log.
- IP restriction: Limit admin panel access to approved address ranges through your web server or firewall, and confirm what EspoCRM itself enforces in the security settings.
- Scheduled test: Sign in on a fixed calendar interval and record the result, then rotate the password.
- Recovery path: Document the command-line route to set a password in case the break-glass account is also locked out.
Check that the account still works after your last upgrade or server change, and that the custodians can reach the vault without the server.
An instance deployed by the installation script runs as a Docker-based stack with Nginx and MariaDB, and it is often managed with the bundled command.sh utility. The break-glass design has to account for the container layer: the account is held in the same database as every other user, so restoring a database restores the account too, and that can bring back an old password. Keep the credential record outside the host, and make sure the test is run against the live stack, not a copy. Limit who can run docker exec and who can reach the host over SSH, because those paths can change any password. Because the stack is containerized, record which image version the account was last verified on, since upgrades can change behavior.
- Dedicated account: Create the break-glass admin inside the running EspoCRM, separate from daily administrators.
- Host access control: Restrict SSH and docker exec to named operators, since those paths can reset any password.
- Backup awareness: Note that restoring a database backup can restore an older break-glass password, so update the vault after every restore.
- IP restriction: Enforce source-address limits at the Nginx layer or the host firewall, and confirm the rules survive container restarts.
- Scheduled test: Sign in through the public URL after each upgrade and on a fixed interval, then log the result.
Confirm the account works after a restore on a staging copy, and that the vault entry matches the password active in production.
When users sign in through OpenID Connect, the identity provider controls day-to-day access, and EspoCRM's fallback login method becomes the break-glass path. EspoCRM documents a fallback login option for OIDC, so the design must confirm that the local admin remains reachable when the identity provider is down, misconfigured or unreachable. The fallback account should not depend on the identity provider, must not be mapped from identity groups, and should not be granted rights through team mapping. Note that EspoCRM's own two-factor authentication is not compatible with OIDC, so the break-glass account's protection has to come from a strong password, a restricted network path and a sealed record. Test both that the identity provider login works and that the fallback login works, because a failure in either one matters.
- Local fallback account: Keep a native EspoCRM admin that does not authenticate through the identity provider, and confirm the fallback login is enabled in configuration.
- No group mapping: Keep the break-glass user out of identity-provider group mappings so that directory changes cannot alter its rights.
- Two-factor limits: Since EspoCRM's own two-factor authentication does not work with OIDC, rely on a long password, network restriction and sealed custody.
- Access path restriction: Restrict the fallback login path to approved networks where your setup allows it, and document who can reach it.
- Scheduled test: Test the fallback login separately from the identity provider on a fixed schedule, including after identity-provider changes.
Verify that the fallback login works while the identity provider is intentionally unavailable in a test window, and that the account is still excluded from directory-driven roles.
Limits to confirm in your environment before you rely on recovery
Recovery steps depend on the exact EspoCRM version, where its configuration file sits, and whether your backups and login paths work. Each check below is cheap to run now and expensive to discover during an outage, so confirm them while you still have admin access.
Confirm the config key for your version
The documented path is to set passwordRecoveryForAdminDisabled to false in data/config.php, as described in the security guide. Confirm that key name and the surrounding syntax against the documentation for the exact EspoCRM version you run, because configuration keys can change between releases. Record the working procedure in your runbook so the person doing the recovery is not reading the file for the first time under pressure.
Locate the config file in your deployment
data/config.php lives in the application directory on a manual install, but in a Docker-based stack it sits inside a container volume or a bind mount. Identify which path your installation uses, confirm that the web server user can write to it, and check that your deployment tooling will not overwrite the file on the next upgrade or redeploy. Note the exact host path in the runbook.
Test that backups restore
A recovery plan that depends on the database or files is only as good as the most recent restorable backup. Restore a copy of your backup into a separate environment and confirm that you can sign in with a known admin account and that user records, roles and teams are present. Check whether your backup includes the configuration file, since recovery settings stored there may be missing after a restore.
Check PHP and database versions
Confirm that your PHP version, database engine and version fall within the range listed in the server configuration documentation before you run any CLI recovery command. A mismatch can make the CLI fail in ways that look like a password problem. Check the database engine as well, since MySQL, MariaDB and PostgreSQL each have their own minimum versions.
Verify the OIDC fallback login
If you sign in through OpenID Connect, confirm that the fallback login method works before you depend on it as a break-glass path. Test it with a non-production account, check that the fallback account is not tied to the identity provider that might be down, and confirm that your identity provider policies do not block it. Remember that EspoCRM's own two-factor authentication is not compatible with OIDC, so plan the second factor at the identity provider.
Questions about recovering an EspoCRM admin password
Do you need a vendor to recover a lost EspoCRM admin password?
No. Recovery is usually a task for whoever administers the server, because it requires shell access to the host where EspoCRM runs. The documented route is a command-line reset of the admin password, and the person running it needs the same level of access they would use for any server maintenance. A vendor becomes useful when nobody on your team has that access, when the change must be audited or approved by an outside party, or when the recovery exposes a wider problem that needs a review of your access model. If you do involve a partner, ask for the written scope to name the hosts, the accounts touched and the evidence you will receive afterward.
Can our own team recover the EspoCRM admin password without help?
In most self-hosted setups, yes, provided someone can log in to the server with appropriate rights and can read and edit the EspoCRM configuration file. The steps are short, but they touch production, so the team should first take a backup, record who performed the change and confirm which admin account is affected. Teams without a second administrator or without documented server access often find the real delay is locating credentials and approvals, not the reset itself. Check the EspoCRM security documentation for the current procedure before you run it on a live instance.
How long does an EspoCRM admin password recovery take?
The reset itself is a short operation, and the duration depends mostly on access rather than on EspoCRM. The main drivers are how quickly someone with server access can be reached, whether change approval is required, and how many environments need the same fix, such as staging and production. Instances with custom deployments, containers or separate application and database hosts take longer to verify. We do not publish durations for this work. Ask any provider to state the expected time in the written scope, along with what starts the clock and what counts as done.
What makes an EspoCRM admin recovery more complex?
Complexity grows with the number of ways a person can sign in. If your instance uses single sign-on through OpenID Connect or LDAP, the local admin password may not be the account users rely on, so you need to confirm which login path is failing and whether the identity provider still maps an administrator. Heavily customized instances, several instances sharing one database, and deployments where the configuration file is managed by automation add further checks. Plan for a verification step that confirms admin login, role permissions and the fallback login method before closing the change.
Does single sign-on change how we recover the admin account?
Yes. When EspoCRM accepts OpenID Connect sign-in, users may never type the local admin password in daily use, so a lost password may not block everyone. Still, the local admin account is often the fallback when the identity provider is down. Confirm which accounts can sign in through each method, keep at least one local administrator reserved for emergencies, and test that fallback login path after any identity change. Also note that EspoCRM's own two-factor authentication is not compatible with OpenID Connect, so the second factor must come from your identity provider.
What changes if the EspoCRM database was also corrupted?
A corrupted database turns a password reset into a recovery project. Resetting the admin password only works if the user table is readable and the instance can start, so you should first check database integrity and locate the most recent good backup. Restoring from backup may bring back an older admin password, older user records and older customizations, which needs to be reconciled with work done since the backup. Ask any provider to scope the restore, the validation of restored data and the handling of records changed after the backup point.
What should we ask for in a written scope for admin recovery?
Ask for a scope that names the affected instances, the access method, the accounts to be reset, and the verification steps. Cost is driven by the number of environments, the state of backups, the presence of single sign-on and the amount of follow-up hardening, such as a break-glass admin account, password policy checks and an access review. Request one-time and recurring items separately, state the evidence you will receive, and confirm what happens if the investigation finds additional issues. Quotes should follow from this written scope, not from a general estimate.
How DeployOpen handles EspoCRM access recovery and break-glass design
DeployOpen treats a lost EspoCRM admin password as an access design problem, not only a recovery task. We scope the recovery path, build a break-glass admin account with controlled use, and hand over the runbook your team needs to repeat the process safely. Engagements are fixed-scope, with ongoing support available as a retainer.
How we scope
- We confirm who holds server and database access and who may approve an admin reset.
- We record the EspoCRM version, hosting layout and location of data/config.php in the written scope.
- We agree which admin accounts exist, which must stay, and which should move to named roles.
How we build
- We set up a break-glass admin account with a long, stored credential and no daily use.
- We review whether admin password recovery should be re-enabled temporarily or kept disabled, and document the trade-off.
- We test the set-password procedure from the command line on a copy of your instance before it is needed.
How we hand over
- We deliver a written runbook covering recovery steps, approvals, logging and when to restore the disabled setting.
- We walk your administrators through the break-glass login and the audit trail it should leave behind.
- We document where the break-glass credential is stored and who can release it under your own controls.
How we support
- Ongoing support is available as a retainer for periodic review of admin accounts and recovery settings.
- We can re-test the recovery runbook after EspoCRM upgrades, server moves or staff changes.
- We help you confirm recovery steps against your own environment and the current EspoCRM documentation.
