Bob's Blog

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.

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 can download the file with FTP if necessary. 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 or a bad memory, 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.

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 and 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.

CAPTCHA Issues

Sometimes you can get locked out if you enable the CAPTCHA plugin and something is misconfigured so you can never pass the challenge. Usually, that results in you also being blocked for too may bad logins (see above). In this case, though, getting unblocked is not enough. You're just going to get blocked again since there's no way to get the CAPTCHA challenge correct.

In addition to unblocking yourself as described above, you also want to edit the core/cache/system_settings/config.cache.php file and turn off captcha by setting:

captcha.enabled = '0',

That will let you log in without the Captcha test, but as soon as you're in, go to System -> System Settings and turn off the captcha.enabled System Setting or you may be locked out again.

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 see what it is. You should be able to recognize it 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. If you have access to PhpMyAdmin, you can open the MODX database, click on the "SQL" tab and enter one of the following commands in the window, then click on the "Go" button at the lower right.

MODX 2.0.x

UPDATE modx_users SET password = MD5('12345') WHERE username = '<i>yourUserName</i>';

MODX 2.1.x

UPDATE modx_users SET hash_class = 'hashing.modMD5', password = MD5('12345') WHERE username = 'yourUsername';

After the query has run successfully, delete all files in the core/cache directory and log in.

Note that with the second method, your hashing method will be set to the weaker MD5 instead of MODX 2.1.x's default, PBKDF2. Once you're logged in, you can get and install the pbkdf2Convert Plugin via Package Management, which will update it. The next time you log in, the plugin will convert the hashing method to the more secure PBKDF2 and you can uninstall or disable the plugin.

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 the new site, open the modx_user tables of both sites. Cut and paste *all* fields for the admin user 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;

/* 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', '', '');

$user = $modx->getObject('modUser', array('username' => $username));

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->set('sudo', true);
    }
    $user->save();
    echo "User Updated";
} 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. Access it with your browser: https://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 in the assets/ directory just under the MODX root directory and execute it with https://yoursite.com/assets/filename.php.

I Don't Know the Username

It can happen. Maybe you're just forgetful. Maybe your web developer quit in a huff after deleting your user. As long as you have FTP access, you still may not be completely defeated. We just need to modify the file above to create a brand new user with rights to the Manager. To do that, the file should look like this:

<?php
$username = 'someUsername';
$password = 'somePassword';
$email = 'your@email';
$sudo = false;

/* 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', '', '');

$user = $modx->newObject('modUser');
$profile = $modx->newObject('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->set('sudo', 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 choose 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, you can find your original user and 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 probably change that user's password as well). 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 setting up 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. Just change the line near the top of either of the files above to this:

$sudo = true;

When the code runs, it will make you a sudo user and you should be able to log in after deleting the files in the core/cache directory. After you get access, if you'd rather not be a sudo user, just go to Security | Manage Users and update yourself. Uncheck the "Sudo User" checkbox at the upper right and click on the "Save" button.