Support

Documentation

This documentation page is for Joomla! 3.x

This documentation page does not apply to our software versions for Joomla! 4.0 and later versions. If you are not using Joomla 3 please consult the documentation index to find and read the correct version of the documentation.

Rescue Mode

Overview

Sometimes an overzealous Admin Tools configuration can result in accidentally blocking yourself, a Super User, from the site. Normally that would require you to rename the main.php file of Admin Tools' system plugin to unblock yourself. This can be rather daunting for novice site administrators.

The Rescue URL feature works around that problem in a secure and elegant manner. First you visit a special URL, including your Super User email address. An email is sent to you with a "magic" link called the Rescue URL. Clicking on that link lets you log in to your site's administrator area without Admin Tools' protections getting in your way. You can then unblock yourself and / or modify the Admin Tools configuration which caused your IP address to be blocked in the first place.

How to use the Rescue Mode

[Important]Important

Rescue Mode is only available on sites running Joomla! 3.6.0 and later and Admin Tools 4.3.0 or later. Also note that if you are not the only Super User on your site, or if you used another company / freelancer to build your site, it's possible that they have turned off Rescue Mode. If these instructions don't work you should assume Rescue Mode is not available or disabled on your site.

Assuming that your site's URL is http://www.example.com and your Super User email address is [email protected] you need to visit the following URL to request a Rescue URL to be sent to you:

http://www.example.com/administrator/index.php?admintools_rescue=[email protected]

You will see the message "Check your email for Rescue URL information" printed on your screen.

Check your email. You will receive an email from your site with a Rescue URL.

[Important]Important

You will only receive the email to activate Rescue Mode if your IP is being blocked by Admin Tools. If your IP is NOT blocked by Admin Tools you will NOT receive any email. This is by design. It doesn't make sense to temporarily unblock yourself with Rescue Mode when you are not blocked!

The Rescue URL looks like this:

http://www.example.com/administrator/index.php?admintools_rescue_token=4vJPFH8pkpFdVkjz0Ej7VUi6gUt39lmkMS36sjmQV6hCTZZ36b2snqWVY6PrxqHdvyb4B3DI8VSUyLbMuYcgNrrZ0WPgDDPB

Do note that the part after admintools_rescue_token is very long and completely random. Also note that it's only valid for use from the SAME browser and IP address that you requested a Rescue URL to be sent to you. The link is only valid for a short period of time (default: 15 minutes). All of that is done for security reasons!

Visit the Rescue URL either by clicking on it or by copying it and pasting it to your browser's address bar. If all goes well you will see your site's administrator backend login page or the Joomla! administrator control panel. If you see the login page just log in with the Super User account which corresponds to the email you used when requesting a Rescue URL to be sent to you.

[Tip]Tip

If you were logged in as a different Super User account you will still be blocked. You will need to repeat this process using the email address of the Super User account you were logged in with on your site. Alternatively, use your browser's Private Browsing mode to request and visit the Rescue URL.

Now you can go to Components, Admin Tools and unblock yourself. Remember that you have a limited period of time (default: 15 minutes) for security reasons!

[Tip]Tip

Don't know how to unblock yourself? No problem! Going to Components, Admin Tools you'll see a message with a link to step by step instructions.

Rescue Mode and security

Rescue Mode was designed with security in mind. There's no point having a security extension if there's an easy backdoor to it! We have ensured security by taking several measures.

First and foremost, the Rescue Mode only applies to the administrator backend. The frontend of your site is not affected. This means that nobody can abuse it to subvert Admin Tools' protection of your public site.

When you are requesting a Rescue URL you must be already blocked from accessing the backend of the site and know the Super User's email address. If your backend login page is protected by a .htaccess password (a.k.a. Administrator Password Protection) you will need to supply that before the request has any effect.

A very long (96 random alphanumeric character), single use, limited validity time (default: 15 minutes) token is generated when you make the request. This has about 160 bits of randomness which means that there are more than 1,460,000,000,000,000,000,000,000,000,000,000,000,000,000,000,000 possible combinations. This is practically impossible to guess. Moreover, it's stored hashed using the same technology as your Joomla Super User password to prevent side-channel attacks, i.e. an attacker using a possible vulnerability in any part of your site / server to perform an unauthorized read of database information.

The token itself can only be used by the same browser and IP address that requested the Rescue URL. This means that phishing attacks wouldn't work. An attacker cannot fool you into opening a backdoor to your site for them. In fact, a potential attacker would need full access to your email to pull of an attack. Of course if they have full access to your email account they can do far more dangerous things, like having your hosting company hand over control of the domain to them, i.e. you'd be thoroughly hacked. Therefore the email portion of Rescue Mode does not constitute a viable attack vector.

When you visit the Rescue URL the token is immediately invalidated (it cannot be used again) and data is written to your session. This data is what acts as a temporary key to disable Admin Tools' protections only for you and only for the site's administrator. Furthermore you MUST log in, or already be logged in, with the same Super User as the one whose email you used when requesting a Rescue URL. If you try to log in with a different user the Rescue Mode is immediately canceled.

The Rescue Mode only temporarily disables Admin Tools' security checks. It does not remove Joomla's own security checks or any third party extensions. Therefore if you are using Two Factor Authentication / Two Step Authentication to verify your login it will still be required for you to log in to your site. This means that even in the unlikely event of you being fully compromised (including control of your email account AND your Super User username and password) the attacker would still be stumped by Two Factor Authentication.

Furthermore, the Rescue Mode is only active for a limited amount of time (default: 15 minutes) since you access the Rescue URL. This means that even if you use a loaner computer you won't end up with a browser that has a backdoor to your site's login page. We also include a button in the Admin Tools control panel page to immediately end Rescue Mode -even if it's not expired- for additional control and security.

Finally, Rescue Mode is opt-out. This means that you can disable it by editing the System - Admin Tools plugin options and setting the Rescue URL option to No.

Discoverability and message customization

Features like this are useless if they are simply buried in the documentation. Admin Tools displays information about the Rescue URL in three places, as long as you have not modified the default options.

First on all, when a blocked request is raised the visitors see a message informing them they did something they shouldn't have done. You can customize this in the Configure WAF page, Customisation tab, Custom Message option. If that option is left blank the default message generated by Admin Tools contains information about unblocking yourself.

The second place where this is displayed is the message shown to blocked IPs. You can customize that in the Configure WAF page, Auto-ban Repeat Offenders tab, Show This Message To Blocked IPs option. If you leave this blank or if you use the default message ("You are a spammer, hacker or an otherwise bad person.") the information about unblocking yourself will be appended to the end of the message.

Moreover, Admin Tools will automatically append the information about unblocking yourself to the default content of the blocked request and IP auto-ban emails (i.e. reasons all and ipautoban) shipped with Admin Tools. You can customize these emails from the Web Application Firewall, Email Templates page.

If you customize these messages and / or emails you can instruct Admin Tools to include the default Rescue URL information by adding the code [RESCUEINFO] in all caps, including the brackets, anywhere in the two messages or the body of the email templates. The rescue info typically reads something like:

If you are the administrator of this site and have blocked yourself on accident please visit https://www.example.com/administrator/[email protected] where [email protected] is the email address of your (Super User) account.

You can customize this information message by creating a standard Joomla! language override for the translation string ADMINTOOLS_BLOCKED_MESSAGE_RESCUEINFO.

[Important]Important

For security reasons, we strongly recommend that you change the Custom message and Show This Message To Blocked IPs messages described above to NOT include any reference to Admin Tools and / or the procedure to unblock yourself. You MUST NOT tell the world how you are protecting your site. Not disclosing this information is yet another hurdle for a potential attacker, making it less likely that they will spend time to attack your site.