Steps on migrating Users and Groups with ACL Permissions in AEM

The focus of this tutorial is to show How to Migrate Users and Groups using ACL Permissions in AEM from one server to another or from one AEM instance to another in the 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 purposes, we want to keep all environments in sync. In such a scenario, you have to copy over both user groups and the ACL’s permission to lower versions like (DEV, QA, PROD, etc.), that we are going to learn in the tutorials and troubleshoot most of the common errors or mistakes that you might face.

There are two ways to migrate users 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 a package for using a 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 users and groups it’s important to understand what do you mean by rights, ACL’s 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 the permissions tab. The 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 the node level as per requirement.

Create a 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-commons 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 templates available under this folder.
§ Query Packager – Utility for creating a 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 anywhere under the 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 the 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 instances where you want to migrate users and groups with ACL permissions.
Congratulations you have successfully created Users and groups with appropriate ACL’s permissions.

Steps to Migrate User and groups with ACL Permissions using the 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 the filter.
· Go to the crx package manager.
· Create a new package and enter the below details in the Filters tab.
§ Root path: /home.

§ 

Rules: /home/users/.*/.tokens

Note:- If we don’t exclude tokens then we will get jcr to constrain violation exception as shown below.
· Add one more exclude rule to remove admin user and replication-receiver user, as these users have lockable node property hence cannot be copied on destination instance. If still, you are getting the same error check where the admin user is stored in destination instance and excludes that path also.
· Add rep: policy to include permissions of individual nodes as a part of the package.
Note:- Add all rep: policy nodes where you have stored 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 ACL’s permissions.
Important Points to remember while migrating Users and Groups with ACL 

Permissions:
· Always take a backup of /home folder at both instances.
· 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 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: - The above method replaces users and groups folder to the destination instance. Carefully use exclude scripts.