Installing Advanced Admin Permissions

Advanced Admin Permissions is generally available with Hyvä Commerce 1.4.0 (hyva-themes/commerce-module-advanced-admin-permissions version 1.0.0).

This guide covers installing the Advanced Admin Permissions module with Composer, what changes in the admin panel once it's installed, and how to remove it again safely.

Installation via Hyvä Commerce Metapackage Recommended

Advanced Admin Permissions is included in the Hyvä Commerce metapackage. The steps below install Advanced Admin Permissions only. While this is supported to provide greater flexibility and control over installed features, in most cases, we recommend installing all Hyvä Commerce features using the metapackage. On Adobe Commerce, the Hyvä Enterprise metapackage includes the Adobe Commerce compatibility package as well.

Requirements

Advanced Admin Permissions needs PHP 8.1 or newer and Magento Open Source 2.4.4 or newer, or the matching Mage-OS release. It builds on Magento's own Magento_Authorization, Magento_User, Magento_Backend, Magento_Integration and Magento_Webapi modules. For the general prerequisites, see the Hyvä Commerce Installation Page.

Advanced Admin Permissions 1.0.0 is tested on Magento Open Source 2.4.4 with PHP 8.1, and on Magento Open Source and Mage-OS 2.4.7 to 2.4.9.

GraphQL on the Magento 2.4.7 Application Server is not supported

On Magento 2.4.7, the Application Server does not reset the permissions and scopes that Advanced Admin Permissions remembers between requests, so one API caller's permissions could carry over into the next GraphQL request a worker serves. Don't serve GraphQL from the Application Server on Magento 2.4.7 with Advanced Admin Permissions installed. Magento 2.4.8 and later are not affected.

Requirements on Adobe Commerce

On Adobe Commerce, Advanced Admin Permissions needs the additional Adobe Commerce compatibility package hyva-themes/enterprise-module-advanced-admin-permissions, which requires a Hyvä Enterprise license. It has the same PHP requirement as Advanced Admin Permissions itself. The Adobe Commerce compatibility module is tested on Adobe Commerce 2.4.8 and 2.4.9.

Install the Adobe Commerce compatibility module on Adobe Commerce

Without the Adobe Commerce compatibility module, Adobe Commerce's own role scopes apply on top of the Advanced Admin Permissions scope restriction, and the role edit page shows two scope editors that save independently. See Adobe Commerce Support for what the compatibility module changes.

Installing the Module with Composer

Require the hyva-themes/commerce-module-advanced-admin-permissions package:

composer require hyva-themes/commerce-module-advanced-admin-permissions:^1.0

Run a setup upgrade to enable the modules and create their database tables:
```
bin/magento setup:upgrade
```
Recompile and flush the cache, as you would after any module install:
```
bin/magento setup:di:compile
bin/magento cache:flush
```

Installing on Adobe Commerce

On Adobe Commerce, first check What Changes for Restricted Admins on Adobe Commerce, because the scope restriction limits some areas differently from Adobe Commerce role scopes. Then require the Adobe Commerce compatibility package instead of the base package. It requires hyva-themes/commerce-module-advanced-admin-permissions itself, so Composer installs both packages:

composer require hyva-themes/enterprise-module-advanced-admin-permissions:^1.0
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

The setup:upgrade imports your existing Adobe Commerce role scopes into Advanced Admin Permissions scope restrictions. Check the result with bin/magento hyva:admin-permissions:import-role-scopes afterwards, and settle any role the import left alone. See Importing Existing Adobe Commerce Role Scopes.

What the Package Installs

The hyva-themes/commerce-module-advanced-admin-permissions package contains two Magento modules, and both are enabled by bin/magento setup:upgrade:

Hyva_AdvancedAdminPermissions - multiple roles per admin user, negative (deny) roles, expiring role grants, bulk role assignment, roles for integrations, the role assignment audit log and the effective-permissions viewer.
Hyva_AdvancedAdminPermissionsScope - the website and store view restriction, and everything that enforces it across grids, edit pages, saves, configuration screens and the REST and SOAP APIs.

On Adobe Commerce, the hyva-themes/enterprise-module-advanced-admin-permissions package adds a third module:

Hyva_AdvancedAdminPermissionsEnterprise - replaces Adobe Commerce role scopes with the scope restriction, imports the existing role scopes, and restricts customer segments, dynamic blocks and the CMS hierarchy. It builds on Hyva_AdvancedAdminPermissionsScope, so disable it too if you disable the scope module.

Scope restriction lives in its own module on purpose, because it is the part that touches the most of Magento. If you only want the role features, disable Hyva_AdvancedAdminPermissionsScope and leave the other module enabled:

bin/magento module:disable Hyva_AdvancedAdminPermissionsScope
bin/magento setup:upgrade

Disabling Hyva_AdvancedAdminPermissionsScope on a store that already uses scope restrictions lifts all of them and deletes them for good. See Disabling Only the Scope Module before you run these commands.

After Installing

Your existing roles and assignments are unchanged after installing Advanced Admin Permissions. The one exception is Adobe Commerce, where your role scopes are imported into scope restrictions. There is no configuration section to fill in and no feature flag to switch on:

Every existing admin user keeps the single role they already had.
No role is a negative (deny) role, no grant has an expiry, and nothing is scope restricted until you set it.
The Role Assignment Audit grid starts empty and fills up as roles change from this point on.

The permission guardrails apply immediately

The permission guardrails are active straight after install: no admin can change their own roles, and an admin can only change, delete or unlock an account whose roles they could grant themselves.

Grant the Hyva_AdvancedAdminPermissions::audit ACL resource to the roles that should be able to open the audit grid. You'll find it in the role resource tree under System → Permissions, as Role Assignment Audit Log.

Start with a test user

Scope restriction changes what an admin sees across the whole panel. Before restricting anyone real, create a throwaway admin user, restrict it to one store view, and log in as it to see the result. The Effective Permissions viewer shows what a user can reach without logging in as them, which covers the permission side but not the scope side.

Uninstalling Advanced Admin Permissions

Removing Advanced Admin Permissions hands permission checks back to plain Magento, and plain Magento knows nothing about multiple roles, negative roles, expiries or scope restrictions. The data the module stored is not converted back into something Magento understands, so prepare your roles before you remove the module, not after.

What Changes When Advanced Admin Permissions Is Removed

Once the modules are gone, Magento reads your admin roles the way it always did:

Each admin user gets exactly one role. Magento reads only one role per admin user, and which of a multi-role user's roles it picks is not defined. The next time the user, or any of their roles, is saved, the other roles are dropped for good. Any save of the user, including a password change on User Info, keeps one role, and saving a role, even only to rename it or change its resources, leaves every user of that role with that role alone.
Negative (deny) roles become ordinary roles. The resources a negative role denied are granted instead, because Magento reads the role's resource tree as a list of grants. This is the most important change to prepare for.
Expiries stop applying. Time-boxed grants become permanent, and so does any lapsed grant the hourly cleanup has not removed yet.
Scope restrictions are lifted. Restricted admins and integrations reach every website and store view their roles allow, and the areas denied to restricted admins, such as Data Transfer and Taxes, become reachable again.
Integrations lose the roles granted to them. An integration set to Roles on its API tab has no resources of its own, so its API calls are refused until you give it resources again. Integrations set to Custom or All are unaffected.
The permission guardrails are gone. Any admin who may edit roles can again assign any role to anyone, including themselves.
On Adobe Commerce, your former role scopes don't come back. The roles the import took over are left at "all scopes" in Adobe Commerce's own role scopes. See Removing Advanced Admin Permissions from Adobe Commerce.

The bin/magento setup:upgrade that runs after the modules are disabled, while their code is still installed, also drops the module's database tables, because Magento's declarative schema removes the tables of modules that are disabled. That deletes the role assignment audit log, the expiries, the negative flags, the integration role grants and the scope restrictions. Installing Advanced Admin Permissions again later starts from empty tables. The removal commands run setup:upgrade in exactly that order.

Remove the code only after setup:upgrade

Magento only drops the tables of a module whose code is still installed. If you remove the package first and run setup:upgrade afterwards, the six hyva_permissions_* tables stay in the database. A later reinstall then brings back the old scope restrictions, the negative flags of roles that still exist, and expiries for user and role pairs that still exist, so a grant you kept as permanent can end again if its old date has passed.

Preparing to Remove Advanced Admin Permissions

Work through these steps while the module is still installed, so the panel and the guardrails are still there to help:

Keep the audit log if you need it. Back up the hyva_permissions_role_assignment_audit table, for example with mysqldump, because it is dropped with the module.
Take every negative role away from every user and integration. Once the module is gone, a negative role would grant what it used to deny. Deleting the negative roles works too.
Reduce every admin user to the one role they should keep. Where a user needs the access of several roles, create a single role that combines them first. Your own roles have to be changed by another administrator, because nobody edits their own access.
Decide on time-boxed grants. Remove the grants that should end soon rather than letting them become permanent, and run bin/magento hyva:admin-permissions:revoke-expired-grants to clear the ones that have already lapsed.
Switch integrations from Roles to Custom. Set Resource Access to Custom on each integration that uses roles, and tick the resources it needs.
Review your restricted admins. Every restricted admin will reach all websites and store views their role allows. Narrow their roles first if that is more than they should have.
On Adobe Commerce, record every role's restriction. You'll need it to set Adobe Commerce's role scopes again after the removal, as described in Removing Advanced Admin Permissions from Adobe Commerce.

Removing the Modules

Remove the modules in two stages. On Adobe Commerce, follow Removing Advanced Admin Permissions from Adobe Commerce instead, because a third module and a second package are involved. First disable both modules and run setup:upgrade while their code is still installed, so Magento drops the module's database tables:

bin/magento module:disable Hyva_AdvancedAdminPermissionsScope Hyva_AdvancedAdminPermissions
bin/magento setup:upgrade

Then remove the code with Composer. How you do that depends on how you installed Advanced Admin Permissions.

Installed on its ownInstalled with the Hyvä Commerce metapackage

If your project's composer.json requires hyva-themes/commerce-module-advanced-admin-permissions directly, remove the package and rebuild:

composer remove hyva-themes/commerce-module-advanced-admin-permissions
bin/magento setup:di:compile
bin/magento cache:flush

The Hyvä Commerce metapackage requires hyva-themes/commerce-module-advanced-admin-permissions, so composer remove refuses to remove it and leaves the package installed. Instead, declare in your project's composer.json that your project replaces the package. Composer then treats the metapackage's requirement as fulfilled and no longer installs the package:

composer.json

{
    "replace": {
        "hyva-themes/commerce-module-advanced-admin-permissions": "*"
    }
}

Add the replace entry next to your existing require section, then update the package and rebuild:

composer update hyva-themes/commerce-module-advanced-admin-permissions
bin/magento setup:di:compile
bin/magento cache:flush

Keep the replace entry for as long as you don't want Advanced Admin Permissions. Remove it again to reinstall the module with the next composer update.

Removing Advanced Admin Permissions from Adobe Commerce

On Adobe Commerce, Advanced Admin Permissions comes with a third module, Hyva_AdvancedAdminPermissionsEnterprise, from the hyva-themes/enterprise-module-advanced-admin-permissions package. That module took your Adobe Commerce role scopes over into Advanced Admin Permissions scope restrictions when it was installed, and set each role it imported to "all scopes" in Adobe Commerce. Removing Advanced Admin Permissions doesn't reverse that import:

Imported roles stay at "all scopes" in Adobe Commerce. The websites and store groups those roles were limited to before the import were cleared, so their admins reach every website until you set the role scopes again. The roles the import left alone keep their Adobe Commerce role scope, and Adobe Commerce keeps narrowing them by it.
Not every restriction has an Adobe Commerce equivalent. Adobe Commerce role scopes belong to a role and list websites or store groups. A restriction stored on an admin user or an integration has no counterpart, and a store view restriction can only be approximated by its store group, which is wider.

Before removing the modules, print the restriction of every restricted role and keep the output:

bin/magento hyva:admin-permissions:scope role <role-id>

Then disable all three modules and run setup:upgrade while their code is still installed:

bin/magento module:disable Hyva_AdvancedAdminPermissionsEnterprise Hyva_AdvancedAdminPermissionsScope Hyva_AdvancedAdminPermissions
bin/magento setup:upgrade

Remove the code of both packages with Composer:

Installed on their ownInstalled with the Hyvä metapackages

composer remove hyva-themes/enterprise-module-advanced-admin-permissions hyva-themes/commerce-module-advanced-admin-permissions
bin/magento setup:di:compile
bin/magento cache:flush

The Hyvä Commerce and Hyvä Enterprise metapackages require the two packages, so replace both in your project's composer.json:

composer.json

{
    "replace": {
        "hyva-themes/commerce-module-advanced-admin-permissions": "*",
        "hyva-themes/enterprise-module-advanced-admin-permissions": "*"
    }
}

Then update the two packages and rebuild:

composer update hyva-themes/commerce-module-advanced-admin-permissions hyva-themes/enterprise-module-advanced-admin-permissions
bin/magento setup:di:compile
bin/magento cache:flush

Finally, set the role scopes again in Adobe Commerce. Open each role at System → Permissions → User Roles → [role] → Role Scopes, which is available again now that the modules are gone, and select the websites or store groups from the output you kept. Do this straight after the removal, because until then every restricted admin can reach every website.

Disabling Only the Scope Module

Disabling Hyva_AdvancedAdminPermissionsScope on its own, as described in What the Package Installs, affects existing scope restrictions too. On Adobe Commerce, disable Hyva_AdvancedAdminPermissionsEnterprise along with it, because that module builds on the scope module.

Disabling only the scope module drops its restrictions too

Disabling Hyva_AdvancedAdminPermissionsScope on its own lifts every scope restriction, and the next setup:upgrade drops the scope restriction tables. Enabling the module again later starts with no restrictions at all.

User Guides - how to assign multiple roles, restrict scope, time-box a grant and read the audit log.
Command Line Reference - the bin/magento hyva:admin-permissions:* commands for scripting and deployment.
FAQs - upgrade safety, performance, and how the module interacts with existing roles.