Skip to content

docs(acl): document 3.3.0 top-menu Access Policy alignment #618

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Ibochkarev wants to merge 1 commit into
base: 3.x
Choose a base branch
from
Open

docs(acl): document 3.3.0 top-menu Access Policy alignment #618

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 11 additions & 11 deletions ...ing-sites/client-proofing/security/policies/permissions/administrator-policy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,19 +8,18 @@ _old_uri: "2.x/administering-your-site/security/policies/permissions/permissions

This policy is packaged into MODX and is given to users on the 'mgr' context who want to have full access to managing MODX content.

From MODX 3.3.0 the top-menu keys match the pages they open. Parent folders use `menu_*` keys. See [Upgrading to 3.3.0](getting-started/maintenance/upgrading/3.3.0).

## Default Permissions

| Name | Description of Access |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| about | The About page. |
| access\_permissions | Any Access Permission-related pages and actions. |
| access\_permissions | Pages under Access that use this key (Resource Groups, ACLs, Flush Permissions). The Access parent menu uses `menu_access`. |
| action\_ok |
| actions | The [Actions](extending-modx/menus/actions "Actions and Menus") page. |
| change\_password | User can change their user password. |
| change\_profile | User can change their profile. |
| content\_types | The [Content Types](building-sites/resources/content-types "Content Types") page. |
| create | Basic "create" access on objects. |
| credits | View the Credits page. |
| customize\_forms | View and manage the [Customizing the Manager](building-sites/client-proofing/form-customization "Customizing the Manager") page. |
| database | The System Info page |
| database\_truncate | The ability to truncate a database table. |
Expand Down Expand Up @@ -49,8 +48,8 @@ This policy is packaged into MODX and is given to users on the 'mgr' context who
| edit\_user | To edit any [User](building-sites/client-proofing/security/users "Users"). |
| element\_tree | The ability to view the Elements Tree on the left nav. |
| empty\_cache | To empty the site cache. |
| export\_static | To export the site to static HTML. |
| file\_manager | To use the file manager, including creating/deleting files. |
| error\_log\_view | View the Error Log under Reports (menu, `system/event`, and ErrorLog processors). |
| file\_manager | Use the Media Browser and related file manager actions. The Media parent menu uses `menu_media`. |
| file\_tree | To view the Files Tree on the left nav. |
| flush\_sessions | Can flush Sessions across the site. |
| frames | To use the MODX Manager UI at all. |
Expand All @@ -61,9 +60,11 @@ This policy is packaged into MODX and is given to users on the 'mgr' context who
| lexicons | To edit or view Lexicons and [Internationalization](extending-modx/internationalization "Internationalization"). |
| list | Basic permission to "list" any object. List means to get a collection of objects. |
| load | Basic permission to "load" any object, or be able to return it as an instance at all. |
| logout | To be able to logout as a user. |
| logs | To view the logs, such as error and manager logs. |
| menus | To edit or save any top Menu items. |
| menu\_access | Show the main menu item Access. |
| menu\_media | Show the main menu item Media. |
| menu\_system | Show the main menu item Gear (System). Does not grant System Settings (`settings`). |
| menus | View and manage Gear → Menus (`system/action` and Menu processors). |
| messages | To send or view any personal Messages. |
| namespaces | To edit or view [Namespaces](extending-modx/namespaces "Namespaces"). |
| new\_category | To create a new Category. |
Expand Down Expand Up @@ -96,15 +97,14 @@ This policy is packaged into MODX and is given to users on the 'mgr' context who
| save\_tv | To save any [Template Variables](building-sites/elements/template-variables "Template Variables"). |
| save\_user | To save any [User](building-sites/client-proofing/security/users "Users"). |
| search | To use the Search page. |
| settings | To view and edit any System Settings. |
| settings | To view and edit System Settings. The Gear parent menu uses `menu_system`. |
| steal\_locks | To "steal" locks, overriding a current lock on a document. |
| unlock\_element\_properties | To be able to edit the default properties for any Element. |
| view | Basic permission to "view" any object. |
| view\_category | To view any Categories. |
| view\_chunk | To view any [Chunks](building-sites/elements/chunks "Chunks"). |
| view\_context | To view any [Contexts](building-sites/contexts "Contexts"). |
| view\_document | To view any [Resources](building-sites/resources "Resources"). |
| view\_eventlog | To view the Event Log. |
| view\_offline |
| view\_plugin | To view any [Plugins](extending-modx/plugins "Plugins"). |
| view\_role | To view any [Roles](building-sites/client-proofing/security/roles "Roles"). |
Expand All @@ -117,7 +117,7 @@ This policy is packaged into MODX and is given to users on the 'mgr' context who

## Custom Permissions

If you have created your own actions and menu items (e.g. if you have created a [Custom Manager Page](extending-modx/custom-manager-pages "Custom Manager Pages Tutorial")), then you can define custom permission items when you create the menu item (System --> Actions --> Create Menu) that correspond to permissions listed here.
If you have created your own menu items (for example a [Custom Manager Page](extending-modx/custom-manager-pages "Custom Manager Pages Tutorial")), set a permission key on the menu item (System → Menus) that matches a permission on this policy.

![](modx+custom+permission.jpg)

Expand Down
2 changes: 2 additions & 0 deletions en/building-sites/client-proofing/security/policies/permissions/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@ Access Policies (ACLs) define lists of permissions (see Menu --> Access Controls
1. [Permissions - Administrator Policy](building-sites/client-proofing/security/policies/permissions/administrator-policy)
2. [Permissions - Resource Policy](building-sites/client-proofing/security/policies/permissions/resource-policy)

From MODX 3.3.0, top-menu parent folders and some report/system items use dedicated permission keys. See [Upgrading to 3.3.0](getting-started/maintenance/upgrading/3.3.0).

## See Also

1. [Users](building-sites/client-proofing/security/users)
Expand Down
6 changes: 4 additions & 2 deletions en/getting-started/maintenance/upgrading.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ It's a good idea to clear your browser cache after upgrading. Browsers often cac
For changes relating to specific versions, please see the following pages:

- [Upgrading from 2.x to 3.0](getting-started/upgrading-to-3.0) (required reading for any 2.x → 3.x move; includes the PHP 7.2 → **8.1 in 3.2** requirement notes)
- [Upgrading to 3.3.0](getting-started/maintenance/upgrading/3.3.0) (top-menu Access Policy keys)
- [Upgrading to 2.8.2 / 2.8.3](getting-started/maintenance/upgrading/2.8.2) (security-related behavioural changes still relevant before jumping to 3.x)
- Historical 2.x notes: [2.3](getting-started/maintenance/upgrading/2.3), [2.2](getting-started/maintenance/upgrading/2.2), [2.1](getting-started/maintenance/upgrading/2.1), [pre-2.0.5](getting-started/maintenance/upgrading/2.0.5), [2.0.0-rc2](getting-started/maintenance/upgrading/2.0.0-rc2)

Expand Down Expand Up @@ -100,5 +101,6 @@ See the note above about FTP clients that support directory merging.
1. [Troubleshooting Upgrades](getting-started/maintenance/upgrading/troubleshooting)
2. [Upgrading from 2.x to 3.0](getting-started/upgrading-to-3.0)
3. [Server Requirements](getting-started/server-requirements)
4. [Upgrading to 2.8.2 / 2.8.3](getting-started/maintenance/upgrading/2.8.2)
5. [Upgrading from MODX Evolution](getting-started/maintenance/upgrading/evolution)
4. [Upgrading to 3.3.0](getting-started/maintenance/upgrading/3.3.0)
5. [Upgrading to 2.8.2 / 2.8.3](getting-started/maintenance/upgrading/2.8.2)
6. [Upgrading from MODX Evolution](getting-started/maintenance/upgrading/evolution)
63 changes: 63 additions & 0 deletions en/getting-started/maintenance/upgrading/3.3.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
---
title: Upgrading to 3.3.0
sortorder: 95
---

MODX 3.3.0 aligns top-menu Access Policy keys with the pages and processors those menu items open. Parent folders no longer reuse a child page key, so denying System Settings no longer hides the whole Gear menu.

Shipped in [modxcms/revolution#17012](https://github.com/modxcms/revolution/pull/17012). Refs [modxcms/revolution#14498](https://github.com/modxcms/revolution/issues/14498). Existing installs get the change through the `3.3.0-pl` upgrade scripts.

See also the [Administrator Policy](building-sites/client-proofing/security/policies/permissions/administrator-policy) permission list.

## Menu and page keys that now match

| UI | Old menu key | New / shared key |
| --- | --- | --- |
| Reports → Error Log (menu, `system/event`, ErrorLog processors) | `view_eventlog` | `error_log_view` |
| Gear → Menus (menu, `system/action`, Menu processors) | `actions` | `menus` |
| User → Logout | `logout` | _(empty: logout is always allowed)_ |

Extras or custom code that call `hasPermission('view_eventlog')` or `hasPermission('actions')` must switch to `error_log_view` and `menus`.

The upgrade rewrites those menu rows. It does **not** grant `error_log_view` or `menus` to policies that only had the old menu aliases. A custom policy with only `view_eventlog` or `actions` loses that checkbox and does not gain the page key.

## Parent menus get their own keys

| Parent menu | Old shared key | New parent key | Child / page key (unchanged) |
| --- | --- | --- | --- |
| Media | `file_manager` | `menu_media` | `file_manager` (Media Browser) |
| Access | `access_permissions` | `menu_access` | `access_permissions` (Resource Groups, ACLs, Flush Permissions) |
| Gear (System) | `settings` | `menu_system` | `settings` (System Settings) |

After upgrade, a user who had the old shared key also gets the matching parent key, so the parent stays visible. Deny the page key and keep the parent key if you want the folder open but the page blocked.

Example: deny `settings`, keep `menu_system` → Gear stays visible, System Settings is blocked.

Left as they were: `menu_site` (Content), `menu_reports`, `menu_user`, `menu_trash`, `components`.

## Removed (dead) keys

These keys are removed from `AdministratorTemplate`, core policies, and matching `modAccessPermission` rows:

- `about`
- `credits`
- `export_static`
- `logout` (policy checkbox; exit from the manager no longer checks it)
- `view_eventlog`
- `actions`
- `menu_security`
- `menu_support`
- `menu_tools`

## Custom policies checklist

1. Grant `menu_media`, `menu_access`, and/or `menu_system` where users should see those parents.
2. Keep `file_manager`, `access_permissions`, and `settings` for the actual pages.
3. Replace `view_eventlog` with `error_log_view` and `actions` with `menus` if those users still need Error Log or Menus.
4. Flush permissions after you edit policies (Security → Flush Permissions).

## See also

- [Permissions](building-sites/client-proofing/security/policies/permissions)
- [Administrator Policy](building-sites/client-proofing/security/policies/permissions/administrator-policy)
- [Menus](extending-modx/menus)
Loading
Loading