Magento SUPEE-6788 Admin Routing

Since the release of Magento’s SUPEE-6788 security patch, admin routing for modules need to adhere to new conventions. Part of the patch includes protection for non-default admin URLs against automated attacks.

This means that if you have an admin module that has a URL defined like the following:

http://www.somesite.com/custommodule/index/index

It should be changed so that the “front name” part of the URL becomes admin, like the following example below.

http://www.somesite.com/admin/some/url

This means that the admin router configuration defined within the module’s config.xml needs to be changed. An admin module that uses the ‘old’ admin router configuration will probably look something like the following.

<admin>
    <routers>
        <custommodule>
            <use>admin</use>
            <args>
                <module>custom_modul</module>
                <frontName>custommodule</frontName>
            </args>
        </custommodule>
    </routers>
</admin>
[/xml

The patch requires this the router configuration to be changed to the below.

[xml title="file: app/code/local/Custom/Module/etc/config.xml"]
<admin>
    <routers>
        <adminhtml>
            <args>
                <modules>
                    <custom_module after="Mage_Adminhtml">CustomModule_Adminhtml</custom_module>
                </modules>
            </args>
        </adminhtml>
    </routers>
</admin>

However the example above is not enough to fix the module’s functionality within the Magento admin area.

If you are unfamiliar with Magento’s URL structure, the “custommodule” part of the first URL is called the “front name”, the first “index” part is the name of the controller (i.e. IndexController.php) and the second “index” part is the action method name inside the controller file (i.e. indexAction()).

This means that the custom module will have a “front name” which is defined in config.xml within a pair of frontName nodes like we saw above.

<admin>
    <routers>
        <custom_module>
            <use>admin</use>
            <args>
                <module>custom_module</module>
                <frontName>custommodule</frontName>
            </args>
        </custom_module>
    </routers>
</admin>

The custom module will also have an IndexController.php file located in the controllers directory within the module’s folder structure.

<?php
class Custom_Module_IndexController extends Mage_Adminhtml_Controller_Action
{
}

And finally, an indexAction() method should exist within the IndexController.php file.

<?php
class Custom_Module_IndexController extends Mage_Adminhtml_Controller_Action
{
    public function indexAction()
    {
        // Some code
    }
}

Within the new admin routing configuration, we have the following line.

<custom_module after="Mage_Adminhtml">Custom_Module_Adminhtml</custom_module>

The Custom_Module_Adminhtml value is known as the controller prefix and tells Magento where your controllers can be found. So instead of the controller file being located in controllers, it now needs to be located in controllers/Adminhtml.

Of course, you can change the prefix to Custom_Module to prevent the controller file from being moved, however there is another problem to address.

<custom_module after="Mage_Adminhtml">Custom_Module_Adminhtml</custom_module>

The after attribute is used for when Magento recognises there are two controllers named the same i.e. IndexController.php, Magento will load the custom module’s controller after any of Magento’s controllers.

This means you should ensure you have a unique name for your admin controllers since the possibility exists of conflicting with another controller.

With the example that’s used in this article the new admin route for our custom module: http://www.somesite.com/admin/index/index conflicts with Magento’s default admin URL which also uses admin/index/index.

Therefore the custom module admin controller should be renamed to something unique to your custom module, like CustommoduleController.php. When doing this, ensure that the class name is also renamed in the controller file.

<?php
class Custom_Module_Adminhtml_CustommoduleController extends Mage_Adminhtml_Controller_Action
{
}

Your custom module admin URL would then take the form of:

http://www.somesite.com/admin/custommodule/index

If your module creates menu items in the Magento admin using the adminhtml.xml file, ensure that you also change any of the URLs defined in here to match the front name, controller and action names.

If you have any admin layout files present in your modules and have changed the routing of the module as per the above, you may need to alter some of the layout handles defined in the file.

For example, using the previous admin routing, you may have an admin layout file that adds blocks that are defined under the following layout handle.

<?xml version="1.0"?>
<layout>
    <custommodule_index_index>
        <!-- Some layout updates here -->
    </custommodule_index_index>
</layout>

Using the new routing and following the example above, this would need to be changed to the below.

<?xml version="1.0"?>
<layout>
    <adminhtml_custommodule_index>
        <!-- Some layout updates here -->
    </adminhtml_custommodule_index>
</layout>

Note: This article is based on Magento Community/Open Source version 1.9.