Migrate Users and Groups with ACL Permissions in AEM

The focus of this tutorial is to show How to Migrate Users and Groups With ACL Permissions in AEM from one server to another or from one AEM instance to another in project.

In a real time scenario, Most of us used to have multiple CQ Publisher instances in different environments (DEV, QA, PROD, etc.). And for testing purpose we want to keep all environments in sync . In such scenario, you have to copy over both user group and the acls permission to lower versions like (DEV, QA, PROD, etc.), that we are going to learn in this tutorials and troubleshoot most of the common errors or mistakes that you might face.

There are two ways to migrate user and groups with ACL in aem, the best and simple approach is to use acs common package.
Migrate users using ACL Packager from acs common package.
Manually create package for using package manager(least preferred and prone to errors)

Steps to Migrate User and groups with ACL Permissions and privileges using ACL Packager from ACS common:
Before starting to migrate user and groups its important to understand what do you mean by rights, acl permissions and privileges and where they are stored.
Login to AEM.
Navigate to User Admin Console(http://localhost:4502/useradmin).
Double click any user and go to permissions tab. Below diagram explains it in detail.
JCR Rights(Part of ACL Permission only): Read,Modify,Create,Delete
ACL Permissions: Read ACL, Edit ACL
ACL Privileges: Replicate
More Privileges can be added at node level as per requirement.

Create package using ACS common packager:
Pre-requisite:
Install ACS commons package

Create a Package using ACL Packager:
Login to AEM author instance.
From the Touch UI, Navigate to Tools -> Operations ->Configuration, From Classic UI open Tools Console(http://localhost:4502/miscadmin#/etc/acs-commons/packagers)
Under the acs-commmons folder, create a folder named packagers (NOTE: As of 1.6.0, this folder is created automatically)
Under the content packagers folder, create a new Page using “ACL Packager” Template.
There are 3 template available under this folder.
Query Packager – Utility for creating package using queries.
Authorizable Packager – Used to Migrate only User and Groups (only authorizable nodes).
ACL Packager – Used to Migrate User/Groups with acl permissions from any where under root node.(authorizable nodes + acl nodes).
Click on Create.


Double click and open the page(Migrate Users)
Edit ACL Packager Configuration rules and configuration, as shown in below screenshot. and click OK.

Click Preview Button, to view the filter paths that are included as part of this package.

Once you are satisfied with preview results, click on Create Package button.

Go to crx package manager and download your package, so that it can be installed on other instance where you want to migrate users and groups with acl permissions.

Congratulations you have successfully created User and groups with appropriate Acls permissions.

Steps to Migrate User and groups with ACL Permissions using crx package manager:
For migrating or copying users and groups definition from one AEM instance to another, we follow the approach of creating a package of users/groups definition , then install the package to the destination AEM instance.

Note: Take a back of existing User/group definitions . By adding /home in filter.
Go to crx package manager.
Create a new package and enter below details in Filters tab.
Root path: /home.
Rules: /home/users/.*/.tokens

Note: If we don’t exclude tokens then we will get jcr constrain violation exception as shown below.

Add one more exclude rule to remove admin user and replication-receiver user, as these users has lockable node property hence cannot be copied on destination instance. If still you are getting same error check where admin user is stored in destination instance and exclude that path also.
Add rep:policy to include permissions of individual nodes as a part of package.

Note: Add all rep:policy nodes where you have stores the permissions like /content/rep:policy.

Go to the Advanced tab and set ACL Handling to overwrite from the dropdown.

Note: The Overwrite access control tells Jcr Package to overwrite the ACLs in the destination AEM instance during installation
Click Save.
Build the package and click download.
Your package is ready to upload it on a new AEM instance and your users and groups will be migrated with appropriate Acls permissions.

Important Points to remember while migrating Users and Groups with ACL Permissions:
Always take a backup of /home folder at both instances.
The same user should not be present on both instances else it’s password will be overwritten.

The above method will replace users and groups with Users of the new instance, if users are present on destination instance which are not available at source instance then they will be deleted. To resolve it take an individual backup of users and groups in a separate package and run this package on top of our package.

Note: Above method replaces users and groups folder to the destination instance. Carefully use exclude scripts.