Joomla ACL Explained: Groups, Access Levels and Permissions

1. The Basics

1.1 Three Questions, Three Mechanisms

Joomla's access control answers three different questions with three different mechanisms. Keeping them apart is half the battle:

Groups are the foundation: both view levels and permissions are always granted to groups, never to individual users. If you ever think "I want to give this one person extra rights", the Joomla answer is: create a group for that role first.

1.2 Where ACL Lives in the Backend

• Users → Groups: the group tree.
• Users → Access Levels: who can see what.
• System → Global Configuration → Permissions: the site-wide permission defaults.
• Every component's Options → Permissions tab: component-level rules.
• Every category and many items: their own Permissions tab for fine-grained rules.

1.3 Why ACL Feels Difficult

Joomla ACL is not complicated because it is badly designed. It feels complicated because it is layered: a single "may Bob edit this article?" decision can involve the global defaults, the component rules, the category rules, the article rules, and every group Bob inherits from. Once you can read those layers in order, the system becomes predictable. That reading order is exactly what this article teaches.

3. The Four Permission States

3.1 What the Dropdown Really Means

Every permission dropdown in Joomla offers a small set of states, and two of them look more alike than they are:

3.2 The Golden Rule: Deny is Final

The single most important ACL rule in Joomla: an explicit Denied can never be undone at a lower level. If a group is denied core.edit on a component, no category rule, no item rule, and no child group can switch it back to allowed. Deeper levels can only restrict further, never re-open.

This is why experienced Joomla administrators treat "Denied" like a fire axe behind glass: almost never the right tool. The default state of every action is already "Not Allowed" - if you simply never grant a permission, the user cannot do it. Use Inherited and Allowed to build permissions up; reach for Denied only when you must carve an exception out of something already allowed higher up.

3.3 Not Allowed vs Denied

"Not Allowed" and "Denied" produce the same behaviour today (the user cannot do it) but behave completely differently tomorrow. "Not Allowed" flips to allowed the moment any parent grants the action. "Denied" stays denied forever, no matter what parents grant later. When you audit a site's ACL, every unnecessary "Denied" is a future support ticket.

5. The Assets Tree

5.1 Where Permissions Are Stored

Every object that can carry permissions - the site itself, each component, each category, each article - has one row in the #__assets table. The rows form a tree, stored as a nested set (with lft and rgt columns) so Joomla can fetch a whole branch in one query:

root.1                          the site (Global Configuration rules)
├─ com_content                 the component
│  ├─ com_content.category.14  a category
│  │  └─ com_content.article.42   one article
└─ com_banners
   └─ com_banners.category.3

The asset name follows a strict pattern: {component}.{type}.{id}. When you edit permissions on an article, you are editing the rules of asset com_content.article.42. When you edit the Global Configuration permissions, you are editing root.1.

5.2 Rules are JSON

Each asset row has a rules column holding a small JSON object: action → group ID → 1 (allow) or 0 (deny). Real examples from a fresh Joomla 6 database:

com_banners:
{"core.admin":{"7":1},"core.manage":{"6":1}}
  = Administrators (7) may configure it,
    Managers (6) may manage it.

root.1 (fragment):
{"core.admin":{"8":1},
 "core.manage":{"7":1},
 "core.login.site":{"6":1,"2":1},
 "core.login.admin":{"6":1},
 "core.login.api":{"8":1}}
  = only Super Users (8) hold the master key core.admin,
    Administrators (7) may manage; Managers and Registered
    may log in to the site, Managers to the backend,
    Super Users to the API.

com_installer:
{"core.manage":{"7":0},"core.delete":{"7":0},"core.edit.state":{"7":0}}
  = an explicit 0: core Joomla itself DENIES the
    Administrators group access to the extension installer.

An empty object {} means "no opinion at this level, inherit everything" - which is exactly what most categories and items should have. If you ever wondered what the Permissions tab really saves: it is this one JSON value.

The defaults are as interesting for what they do not say. On root.1 no group is granted core.options, and no group anywhere is granted core.edit.value (the custom fields action). Because nothing grants them, they calculate to "Not Allowed (Inherited)" for every group below Super Users - Administrators included. That is why an Administrator sees Configure Options as Not Allowed, and why on a fresh site only Super Users can fill in custom field values. And com_installer is the one place where core Joomla itself swings the fire axe from section 3.2: an explicit deny that keeps Administrators out of the installer, unchangeable at any deeper level.

5.3 Why the Tree Must Stay Healthy

Because assets form a nested set, a corrupted tree (after failed migrations or direct database edits) produces baffling symptoms: permissions that apply to the wrong items, categories that ignore their component rules. The fix is to rebuild the tree - see the debugging section below.

7. Real-World ACL Recipes

7.1 A Department That Manages Only Its Own Category

Goal: the Marketing team edits articles in the News category and nowhere else.

1. Create group Marketing with parent Registered (not Editor - you will grant rights explicitly).
2. In com_content → Options → Permissions, leave Marketing on Inherited everywhere.
3. Open the News category → Permissions, and set for Marketing: Create = Allowed, Edit = Allowed, Edit State = Allowed.
4. Assign the marketing users to the Marketing group.

Because the grants live on the category asset, they apply to that category and its children - and nothing else. No deny needed anywhere.

7.2 A Frontend-Only Content Manager

Goal: a client contact who can create, edit, and publish articles from the frontend, but never sees the backend.

1. Create group Content Manager under Registered.
2. In com_content permissions, allow Create, Edit, Edit State for the group.
3. Do not grant core.login.admin anywhere. Without the backend login action, the backend simply does not exist for them.

7.3 A Members-Only Area

Goal: paying members see premium content; everyone else sees a teaser.

1. Create group Members under Registered.
2. Create view access level Premium containing Members (and, deliberately, Super Users - see the pitfalls below).
3. Set the premium articles, modules, and menu items to level Premium.

Note that no permissions were touched at all: pure visibility problems need only groups and view levels. Reaching for the Permissions tab here would be over-engineering.

7.4 A Locked-Down API Integration User

Goal: an external system posts articles through the Web Services API with the least possible power.

1. Create group API Writer under Registered.
2. Global Configuration → Permissions: allow Site API Login (core.login.api) for the group.
3. com_content permissions: allow Create (and nothing else) for the group.
4. Create one user in only this group, enable an API token for it, and let the integration use that token.

If the token ever leaks, the attacker can create unpublished articles - and that is all.

9. Under the Hood (Developer View)

9.1 The Tables Involved

9.2 The Access Class

All calculation lives in Joomla\CMS\Access\Access, with Rules and Rule as the value objects that merge the JSON. The methods you will actually use:

use Joomla\CMS\Access\Access;

Access::check($userId, 'core.edit', 'com_content.article.42');
Access::checkGroup($groupId, 'core.manage', 'com_content');
Access::getAuthorisedViewLevels($userId);   // e.g. [1, 2, 5]
Access::getGroupsByUser($userId);           // includes inherited parents
Access::preload('com_content');             // warm the cache for a component

In everyday component code you rarely call Access directly; you ask the user object, which delegates and caches:

$user = $this->getUserFactory()->loadUserById($userId);

if ($user->authorise('core.edit.state', 'com_content.article.42')) {
    // may publish or unpublish this article
}

9.3 Filtering Lists by View Level

Permission checks guard actions; view levels guard queries. Every core content query filters on the user's levels, and yours should too:

$levels = $user->getAuthorisedViewLevels();

$query->whereIn($db->quoteName('a.access'), $levels);

Forgetting this filter is how "hidden" content leaks into custom modules and search results: the item was protected, but the query never asked.

9.4 Performance: One Tree, Well Cached

ACL looks expensive - a JSON merge across a tree for every check - but Joomla caches aggressively per request: the user's groups, the asset rules, and each authorise() verdict are computed once. The practical advice: call Access::preload() when you know you will check many items of one component, and never loop a thousand items calling a fresh check each time on cold caches.

11. ACL and the Web Services API

11.1 The Same Rules, No Exceptions

The Web Services API does not have its own permission system. An API request authenticates as a user (usually via a token), and from then on every endpoint enforces the exact same ACL as the website: the same groups, the same assets, the same deny rules. There is exactly one extra gate: the group needs core.login.api allowed on the Global Configuration level, or authentication fails before any endpoint runs.

11.2 Managing ACL Through the API

Users, groups, and view levels are themselves manageable over REST:

curl -H "X-Joomla-Token: <token>" \
     https://example.test/api/index.php/v1/users

curl -H "X-Joomla-Token: <token>" \
     https://example.test/api/index.php/v1/users/groups

curl -H "X-Joomla-Token: <token>" \
     https://example.test/api/index.php/v1/users/levels

All three support the usual CRUD verbs, so provisioning tools can create groups and levels programmatically. Treat these endpoints with respect: whoever can POST to v1/users/groups can reshape your entire permission model. Keep API access limited to dedicated, minimal accounts, exactly as in the recipe in section 7.4.

13. Common Mistakes and Pitfalls

13.1 Using Denied Where Not Allowed Already Works

Symptom: months later, a group mysteriously cannot do something no matter what you allow.

Fix: remember that deny is final down the whole tree. Audit for explicit denies (the SQL in section 8.3 finds them) and replace them with plain "Inherited" wherever the default "Not Allowed" already does the job.

13.2 An Extra Group Takes Rights Away

Symptom: you add a user to a second group to give them more access, and they lose abilities instead.

Fix: one of the new group's rules carries a deny, and any deny among a user's groups vetoes the allows of the others. Check both groups in Debug User and remove the deny.

13.3 Forgetting Super Users in a Custom View Level

Symptom: administrators report that premium content is "missing" while members see it fine.

Fix: view levels contain only the groups you put in them - Super Users bypass permissions, not view levels. Add the Super Users group to every custom level.

13.4 Granting core.admin Casually

Symptom: a "content" group can suddenly change permissions, or worse, has become a full super-user group.

Fix: core.admin on a component hands over that component's ACL; on the Global Configuration it creates Super Users. Grant it almost never, and audit who has it today.

13.5 Solving Visibility Problems with Permissions

Symptom: a tangle of item-level permission rules that only needed to hide content from some visitors.

Fix: visibility is the job of view access levels; permissions are for actions. If the requirement contains the word "see", think levels first.

13.6 Direct Database Edits Without a Rebuild

Symptom: after importing content or editing groups in SQL, permissions apply to the wrong things.

Fix: both #__assets and #__usergroups are nested sets whose lft/rgt values must stay consistent. Use the Rebuild button under Users → Groups and the database repair tools, and avoid hand-editing tree tables at all.

13.7 Expecting Administrators to Be Almost Super Users

Symptom: a user in the Administrators group cannot open the Global Configuration, cannot install extensions, and sees every custom field greyed out in the article edit form - the Permissions tabs show "Edit Custom Field Value" as Not Allowed (Inherited) everywhere, including on every newly created field.

Fix: nothing is broken; these are the shipped defaults (section 5.2). root.1 grants Administrators only core.manage, core.admin belongs to Super Users alone, com_installer carries an explicit deny for group 7, and no group at all is granted core.edit.value. Grant what your administrators really need, deliberately: set Edit Custom Field Value to Allowed at the component level (for example Content → Articles → Options → Permissions) so all fields inherit it. If Administrators must also install extensions, a Super User has to replace the explicit Denied on com_installer itself (System → Install → Extensions, then Options → Permissions) - remember from section 3.2 that no deeper allow can ever override it.

15. Quick Reference

MODEL        groups   = who you are        (#__usergroups, nested)
             levels   = what you can SEE   (#__viewlevels, group id list)
             actions  = what you can DO    (rules JSON on #__assets)

STATES       Inherited    no opinion, ask the parent
             Allowed      grant here
             Denied       forbid here - FINAL, wins over any allow below
             Not Allowed  the default result when nothing was granted

HIERARCHY    root.1 (Global Config) > component > category > item
             group tree inherits in parallel; any deny vetoes

ASSETS       name pattern: com_content.article.42
             rules: {"core.edit":{"4":1}}   action > group > 1/0

SUPER USER   any group with core.admin allowed on root.1
             bypasses permissions, NOT view levels
             emergency: root_user in configuration.php

ADMINS (7)   default: core.manage on root.1, most components
             NO Global Configuration (core.admin = 8 only)
             NO extension installer  (com_installer denies 7)
             NO custom field values  (core.edit.value never granted)

DEBUG        calculated setting column   (save first, then read)
             Users > Manage > Debug User / Debug Group
             SELECT name, rules FROM #__assets WHERE rules LIKE '%:0%';

RECIPES      department:  allow on their category only
             frontend mgr: content rights, no core.login.admin
             members area: group + view level, no permissions
             API user:     own group, core.login.api + one action

API          v1/users, v1/users/groups, v1/users/levels
             API requests obey normal ACL + core.login.api gate

DEV          access.xml declares actions
             <field type="rules"> shows the tab
             $user->authorise('core.edit', $assetName)
             filter queries by getAuthorisedViewLevels()