Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 42 ยท Admin, APIs and Backend Services

Admin Controllers, Menus and ACL

Build a Magento admin page: adminhtml routes, controllers with ADMIN_RESOURCE, menu.xml entries, acl.xml permissions and secret keys, with runnable ACL stand-ins.

Customers see the storefront, but the people who run the shop live in the admin panel. If your module manages anything, such as badges, vendors or export jobs, it needs admin pages, a menu entry to reach them, and a way to decide who may use them. Magento separates these concerns into three small pieces: an admin route and controller, a menu.xml entry, and an acl.xml permission tree.

In this lesson you will learn how each file works and how they point at each other through one shared string: the ACL resource id. You will also learn why admin URLs carry a secret key. The real Magento code is read-only here because Magento cannot run on this site. The runnable examples are plain PHP stand-ins that check permissions in a resource tree and guard URLs with keys. For background on controllers in general, see Routing and Controllers.

The three files that make an admin page

Suppose you want an admin page for a made-up Acme_Badge module. You write:

  1. etc/adminhtml/routes.xml registers a URL prefix for admin controllers.
  2. Controller/Adminhtml/Badge/Index.php handles the request and names the resource it needs.
  3. etc/acl.xml declares that resource, so it appears in the role editor.
  4. etc/adminhtml/menu.xml adds the menu item, guarded by the same resource.
flowchart LR
    M["menu.xml<br/>resource Acme_Badge::badges"] --> U["Admin URL<br/>/admin/acme_badge/badge/index/key/..."]
    U --> R["routes.xml<br/>frontName acme_badge"]
    R --> C["Controller<br/>ADMIN_RESOURCE"]
    L["acl.xml<br/>resource tree"] -. "isAllowed()" .-> C
    L -. "hides menu item" .-> M

The menu item, the controller and the role editor all use the same ACL resource id.

Admin routes

The admin router is a different router from the storefront one. Routes go into etc/adminhtml/routes.xml (read-only):

XML
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:App/etc/routes.xsd">
    <router id="admin">
        <route id="acme_badge" frontName="acme_badge">
            <module name="Acme_Badge"/>
        </route>
    </router>
</config>

The frontName becomes the first URL segment after the admin path. A request to /admin/acme_badge/badge/index is routed to the Index action of the Badge controller in Acme\Badge\Controller\Adminhtml\Badge. Note the extra Adminhtml folder: admin controllers live there, and the class name is the same as for a storefront action, so the folder tells Magento which area they belong to.

The path segment admin is configurable. Production stores are encouraged to change it during installation (to something like admin_k29fj) so that bots do not find it so easily. This is a small obstacle, not real security.

The controller and ADMIN_RESOURCE

Admin controllers extend Magento\Backend\App\Action. The key line is the ADMIN_RESOURCE constant, which names the permission needed to run the action. This is a typical read-only example:

PHP
namespace Acme\Badge\Controller\Adminhtml\Badge;

use Magento\Backend\App\Action;
use Magento\Backend\App\Action\Context;
use Magento\Framework\App\Action\HttpGetActionInterface;
use Magento\Framework\View\Result\PageFactory;

class Index extends Action implements HttpGetActionInterface
{
    public const ADMIN_RESOURCE = 'Acme_Badge::badges';

    public function __construct(
        Context $context,
        private PageFactory $resultPageFactory
    ) {
        parent::__construct($context);
    }

    public function execute()
    {
        $page = $this->resultPageFactory->create();
        $page->setActiveMenu('Acme_Badge::badges');
        $page->getConfig()->getTitle()->prepend(__('Badges'));
        return $page;
    }
}

The base class has a method _isAllowed() that calls $this->_authorization->isAllowed(static::ADMIN_RESOURCE). If the logged-in admin user's role does not include that resource, Magento refuses the request. You rarely override _isAllowed(). Forgetting ADMIN_RESOURCE is a classic mistake: the base class then falls back to the generic admin resource and every admin user who can log in can run your action. Always set a specific resource, and use a more specific one for dangerous actions such as delete.

acl.xml: the permission tree

etc/acl.xml declares resources as a nested tree. Each resource has an id and a title shown in System > Permissions > User Roles > Role Resources (read-only):

XML
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Acl/etc/acl.xsd">
    <acl>
        <resources>
            <resource id="Magento_Backend::admin">
                <resource id="Acme_Badge::badges" title="Badges" sortOrder="50">
                    <resource id="Acme_Badge::badge_save" title="Save badges" sortOrder="10"/>
                    <resource id="Acme_Badge::badge_delete" title="Delete badges" sortOrder="20"/>
                    <resource id="Acme_Badge::config" title="Badge settings" sortOrder="30"/>
                </resource>
            </resource>
        </resources>
    </acl>
</config>

The root Magento_Backend::admin is the top of the whole tree. Your own resources hang below it, or below an existing resource if your feature belongs in an existing area, for example under the catalog branch. The id convention is Vendor_Module::name.

A role stores the list of resources it may use. The role editor's tree checks parent nodes automatically when you tick a child, so a role can never have a child permission without its parent. A role with Magento_Backend::all ("Resource Access: All") may use everything. The <resource> element in system.xml from System Configuration (system.xml) uses the same ids, which is how a settings page gets its own permission.

The stand-in below builds this tree as nested arrays, expands a role's checked boxes the way the admin UI does, and checks access for different roles. It is a model of the idea, not Magento's Laminas\Permissions\Acl code.

PHP An ACL resource tree and role checker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The Editor ticked only "Save badges", but the expansion added the parent nodes, so the Editor can open the Badges page (Acme_Badge::badges) as well. Without that parent, the page would be forbidden although the Save button is allowed, which would make no sense.

The admin navigation is built from etc/adminhtml/menu.xml files (read-only):

XML
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Backend:etc/menu.xsd">
    <menu>
        <add id="Acme_Badge::badges" title="Badges" module="Acme_Badge"
             sortOrder="50" parent="Magento_Catalog::catalog"
             action="acme_badge/badge" resource="Acme_Badge::badges"/>
    </menu>
</config>

add creates an item (remove deletes one and update changes one). parent places it under another item, here the Catalog menu. action is the route path of the page without the admin prefix. resource is the ACL id; items the current user may not use are simply not drawn. Hiding a menu item is a convenience, not a lock: the controller check is the real protection, because anybody can type a URL.

Secret keys

Admin URLs normally contain a key segment, like /admin/acme_badge/badge/index/key/3f9a.... This secret key is a hash tied to the route and the admin user's session. A link without the right key is refused (the user is redirected to the dashboard), which blocks attackers from tricking a logged-in admin to click a bare link such as "delete badge 5" on another site. Forms use a similar protection, a form_key field. The setting Add Secret Key to URLs in the admin security configuration controls the feature, and it is on by default, so leave it on. Use $this->getUrl(...) in blocks and $this->_url->getUrl(...) in controllers, since they add the key for you. Hand-built URLs get no key and fail.

The stand-in builds an HMAC key from the route and a session secret. Magento's real algorithm differs in detail, but the effect is the same: the key cannot be guessed, and a key for one route does not work on another.

PHP Secret-key protected admin URLs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Only the URL generated with the right secret is accepted. The forged, reused and bare links are refused, which is exactly what the secret-key check in Magento does for a dangerous action like delete.

Putting it together

When you add an admin feature, work through this checklist:

  • A route in etc/adminhtml/routes.xml and controllers in Controller/Adminhtml/.
  • An ADMIN_RESOURCE on every controller, with finer resources for save and delete.
  • The same resources in acl.xml, with clear titles, since merchants read them.
  • A menu.xml entry that uses the page's resource.
  • Mutating actions only on POST, with form_key validated (see Performance and Security).

After changing XML, run bin/magento cache:clean. If a new resource does not appear in the role editor, the config or ACL cache is usually stale. Existing roles also do not receive your new resource automatically unless they have full access; an admin must tick it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the ADMIN_RESOURCE constant in an admin controller do?

    The base class checks that the logged-in user's role includes this resource. Without a specific value, the check is far too broad.
  2. 2. A role has the resource Acme_Badge::badge_save but not Acme_Badge::badge_delete. What happens when the user requests a controller that needs badge_delete?

    Permissions are checked per resource id. Having a sibling or a parent does not grant the child.
  3. 3. Why does hiding a menu item not protect an admin page?

    The menu is a convenience. The controller's isAllowed() check, plus the secret key, is what actually protects the action.
  4. 4. What is the purpose of the secret key in admin URLs?

    The key is tied to the route and the session. A forged or reused link does not match and is refused.

Summary

  • An admin page needs a route (etc/adminhtml/routes.xml, router admin), a controller under Controller/Adminhtml/, and an ADMIN_RESOURCE constant.
  • acl.xml declares a tree of resources below Magento_Backend::admin; roles store which resources are allowed, and the role editor ticks parents automatically.
  • menu.xml adds, updates or removes menu items; the resource attribute hides items from users without permission.
  • Hiding a menu item is cosmetic. The controller check is the real protection.
  • Secret keys in admin URLs and form_key in forms block forged requests; build URLs with the URL builder so keys are added.
  • The same resource id ties together menu, controller, system.xml and role editor.

Next: The REST API