[From the Editor] The article that follows contains Bob’s expert tried-and-true strategies for recovering access to your MODX Manager on traditional web hosting environments.
MODX Cloud enables you to easily create a new Manager Administrator User from the MODX Cloud Dasboard, or our friendly, expert support team will help you regain access to your MODX Cloud site if you are having difficulty. If you’ve never tried MODX Cloud for yourself, now’s the time. [JG]
Getting locked out of the MODX Revolution Manager is a nasty turn of events, especially if you have a looming deadline. It has several causes and a number of possible solutions. In some of the steps below, it’s assumed that the table prefix for your MODX database is modx_. If it’s not, use the correct prefix. It will be easy to tell because it will be the prefix on all, or almost all, of the tables in the MODX database.
You should read through all the methods below before doing anything, and start with the easiest method that’s appropriate for your situation.
Database Name
In some of the solutions below, you’ll need to work with the database for your site. If you’re not absolutely sure what it’s called, just look in the core/config/config.inc.php file. You see the file in cPanel’s File Manager (or the equivalent). Around line 10, you should see $dbase =. The value after the equals sign is the name of your database. While you’re there, make a note of the $database_user and $database_password values, you’ll need them to get access to the database. Also, check the $table_prefix value if it’s not modx_. If you don’t have cPanel access (or the equivalent), there may still be ways to get in using FTP. We’ll discuss that later.
Blocked
By default, you can only screw up your login credentials a certain number of times before the curtain comes down to prevent brute-force password-guessing attacks on the site. Once you’re blocked, even the correct username and password won’t get you in. The default number is 5, but you may have changed it at some point. It’s determined by the failed_login_attempts System Setting. If you get blocked because of bad typing, the simplest solution is to just wait an hour (unless you’ve changed the blocked_minutes System Setting to something other than 60). After your time in the penalty box has expired, you should be able to log in with the correct Manager credentials.
If you’d rather not wait, and you have cPanel access, you can use PhpMyAdmin to cancel the block. First, check the database name and credentials as described above. Then open that database in PhpMyAdmin (usually found in the Database section of cPanel). Open the modx_users table and find your username. Make a note of the user ID (if you're the main admin, it’s almost always 1). If you know your ID already, you can skip the previous step.
Open the modx_user_attributes table (which holds the User profile). Find your ID in the internalKey column. That row is you. Click on the “Edit” link for that row. Change the values in the blocked, blockeduntil, and blockedafter fields to 0, then click on the “Go” button. Delete all files in the core cache directory and log in. If you think you might need more than 5 trys to get the credentials right, you can go to the modx_system_settings table and change the failed_login_attempts System Setting to a larger number.
Be sure to clear the site cache by manually deleting all files in the core/cache directory so your changes will take effect. Remember to change the failed_login_attempts System Setting back once you get back into the Manager (if you changed it).
Forgot Username
If you log in to a lot of sites and just aren’t sure of your username, use the technique described above to get into the database. You should be able to recognize your username when you see it in the modx_users table. If you're the main admin, it should be at the top of the grid.
Forgot Password
MODX has a “Forgot Password” option on the login screen that’s designed to email you a new password, but it may not be enabled, and it doesn’t always work.
The Ugly Method
This is kind of a brute-force method, but it can be used if you get stuck, and you have PhpMyAdmin access through cPanel or the equivalent. Create a brand new install of the same version of MODX somewhere else—it doesn’t matter where. After making sure you can log in to that new site, open the modx_user tables of both sites. Cut and paste all fields for your user (find it as describe above) from the new site to the problem site. Be sure not to do it backwards. Once you’ve done that, you should be able to log in to the problem site with the credentials you used to log in to the new site.
No PhpMyAdmin Access
If you can’t get into PhpMyAdmin, you still have a shot if you have FTP access to the site (without that, you’re pretty much dead in the water unless the host will help you out). The secret is to create a PHP file that will let you in and upload it to the server with FTP, then execute it. Important: as soon as you can log in, delete the .PHP file. It’s not a good thing to leave lying around.
Using any text editor (not a word processor) create a file with a name ending in .php. I won’t suggest a name because only you should know it. Paste in the following code:
<?php
$username = 'yourUserName';
$password = 'somePassword';
$sudo = false; /* See below for when to change this */
/* Find out where the MODX core is */
require "config.core.php";
/* get the MODX class file */
require MODX_CORE_PATH . 'model/modx/modx.class.php';
/* instantiate the $modx object */
$modx = new modX();
if ((!$modx) || (!$modx instanceof modX)) {
echo 'Could not create MODX class';
}
/* initialize MODX and set current context */
$modx->initialize('mgr');
/* load the error handler */
$modx->getService('error', 'error.modError', '', '');
/* Make this work in future versions of MODX */
$prefix = $modx->getVersionData()['version'] >= 3
? 'MODX\Revolution\\'
: '';
/* Get your user object *;
$user = $modx->getObject($prefix . 'modUser', array('username' => $username));
/* Update the password and remove any blocks */
if ($user) {
$profile = $user->getOne('Profile');
$user->set('password', $password);
$profile->set('blocked', 0);
$profile->set('blockeduntil', 0);
$profile->set('blockedafter', 0);
if ($sudo) {
$user->setSudo(true);
}
if ($user->save()) {
echo "User Updated";
} else {
echo "Could not Save User";
}
} else {
echo "Could not find that user";
}Change the username and password values in quotes at the top of the file. Save the file, then upload it to the MODX root directory with FTP (or cPanel’s File Manager if that’s available. Access it with your browser: http://yoursite.com/filename.php. Replace yoursite.com with whatever you usually use to access the site. The file should modify your password, and after deleting all the files in the core/cache directory, you should be able to log in with the username and password specified in the file.
If the file won’t execute in the root directory, try putting in the assets/ directory just under the MODX root directory. Change the require "config.core.php" line to this:
require "../config.core.php";Run the script with http://yoursite.com/assets/filename.php.
If You Don’t Know the Username
It can happen. Maybe your web developer quit in a huff after deleting your user. As long as you have FTP or cPanel access, you still may not be completely defeated. We just need to modify the file above to create a new user with rights to the Manager. To do that, the file should look like this:
<?php
/* Set these, but do not use your
previous username! */
$username = 'someUsername';
$password = 'somePassword';
$email = 'your@email';
$sudo = false;
/* Find out where the MODX core is */
require "config.core.php";
/* Or, if you're running it in the assets directory */
/*
require "../assets/config.core.php";
*/
/* Get the MODX class file */
require MODX_CORE_PATH . 'model/modx/modx.class.php';
/* instantiate the $modx object */
$modx = new modX();
if ((!$modx) || (!$modx instanceof modX)) {
echo 'Could not create MODX class';
}
/* initialize MODX and set current context */
$modx->initialize('mgr');
/* load the error handler */
$modx->getService('error', 'error.modError', '', '');
/* Make this work in future versions of MODX */
$prefix = $modx->getVersionData()['version'] >= 3
? 'MODX\Revolution\\'
: '';
$user = $modx->newObject($prefix . 'modUser');
$profile = $modx->newObject($prefix . 'modUserProfile');
if ($user && $profile) {
$user->set('username', $username);
$user->set('password', $password);
$profile->set('blocked', 0);
$profile->set('blockeduntil', 0);
$profile->set('blockedafter', 0);
$profile->set('email', $email);
$user->addOne($profile);
if ($sudo) {
$user->setSudo(true);
}
if ($user->save()) {
echo "User Created";
$user->joinGroup('Administrator');
} else {
echo "Could not create specified user";
}
} else {
echo "Could not create a new user and/or profile object";
}Make sure the username you chose is not already in the database or the creation will fail, and don’t forget to set the email address. Upload and run the file as described above, then delete all the files in the core/cache directory and log in with the credentials in the file.
After logging in, if you can find your original username, you can reset that user’s password. After you’re sure you can log in as the original user, you can delete the user created by the file (or leave it there for future emergencies, though for security, you should probably change that user’s password as well).
Important: Once things are back to normal, don’t forget to delete the file you created.
Sudo-ify yourself
If none of the above worked for you, you may be locked out because of a mistake you made when modifying the MODX security system. Maybe you accidentally removed yourself from a user group or deleted an important ACL entry. The way around that is to make yourself a “sudo” user (or create a new sudo user). “Sudo” users have full rights to everything regardless of any security settings. They will pass any permission checks in the Manager.
If you have a username and password that you know will work, you can just make yourself a sudo user without creating a new user. The easiest and most reliable is to go into the modx_users table in the DB and change the sudo field in your user record to 1. Then delete all the files in the core cache directory and log in.
If you have no DB access, you can modify either of the files above to modify an existing user or create a new sudo user. Just change the line near the top of either of the files above to this, and run the file:
$sudo = true;Important: If it’s a new user you’ll need to use a new username or the user won’t be created.
When the code runs, it will make the user a sudo user. As a sudo user, you should be able to log in after deleting all files in the core/cache directory.
After you get access, if you’d rather not be a sudo user just go to Manage —> Users and update yourself. Uncheck the “Sudo User” box at the upper right and click on the “Save” button. It’s strongly recommended that no one (including you) should be a sudo user except temporarily to solve a particular problem.
Important Reminder
Once you can log in successfully, delete any PHP files you created in earlier attempts.
Bob Ray is the author of the MODX: The Official Guide and dozens of MODX Extras including QuickEmail, NewsPublisher, SiteCheck, GoRevo, Personalize, EZfaq, MyComponent and many more. His website is Bob’s Guides. It not only includes a plethora of MODX tutorials but there are some really great bread recipes there, as well.