Migrate users, groups, and ACLs between AEM instances

Description

How to Migrate Users and Groups With ACL Permissions in AEM from one server to another or from one AEM instance to another.

Resolution

Step 1: Find the admin and anonymous users

1. Go to CRXDE lite app /crx/de/index.jsp and log in as admin user (on the source system).

2. Go to “Tools” = “Query”

3. In the bottom “Query” box, enter this query to find the admin user: /jcr:root/home/users//element(*,rep:User)@rep:principalName=“admin”

4. Click “Execute” and copy the path of the admin user node in the results to a text file.

5. Repeat step 3 with a query for anonymous user: /jcr:root/home/users//element(*,rep:User)@rep:principalName=“anonymous”.

6. Click “Execute” and copy the path of the anonymous user node in the results to a text file (so now you  have two paths, one for “admin” and one for “anonymous”)

   For example:

   /home/users/Q/QY5FIMXeQIbGpwZtQ3Dv – admin user on the source system

   /home/users/K/Kj1406Qo9IDODc_nk5Ib – anonymous user on the source system

Step 2A: Migrate users and groups (using crx2oak or oak-upgrade)

Users and groups can be migrated between AEM instances using the crx2oak or oak-upgrade tools.

1. Download the crx2oak or oak-upgrade jar matching the Oak version you are using:
   1. Oak-upgrade: https://repo1.maven.org/maven2/org/apache/jackrabbit/oak-upgrade
   2. Crx2Oak: https://repo.adobe.com/nexus/content/groups/public/com/adobe/granite/crx2oak/
2. Upload the jar file to the AEM server
3. Stop AEM (source and destination instances)
4. Replace the name of the jar file in the command below.
5. Replace /home/users/Q/QY5FIMXeQIbGpwZtQ3Dv,/home/users/K/Kj1406Qo9IDODc_nk5Ib in the –exclude-paths part parameter of the command below with the paths of the admin and anonymous users from your source system.
6. Modify the paths on line to match your instance (add segment-old: before the path if required, see here https://jackrabbit.apache.org/oak/docs/migration.html): /opt/aem-source/crx-quickstart/repository /opt/aem-destination/crx-quickstart/repository
7. Then run the command on the server’s shell.  java -Xms2g -Xmx2g -jar oak-upgrade-1.8.12.jar \
--include-paths=/home \
--merge-paths=/home \
--exclude-paths=/home/users/Q/QY5FIMXeQIbGpwZtQ3Dv,/home/users/K/Kj1406Qo9IDODc_nk5Ib,/home/groups/a/administrators,/home/groups/a/analytics-administrators,/home/groups/c/community-moderators,/home/groups/c/content-authors,/home/groups/c/contributor,/home/groups/community/community-groupadmin,/home/groups/community/community-sitecontentmanager,/home/groups/community/community-sitemembers,/home/groups/d/dam-users,/home/groups/default/order-administrators,/home/groups/e/everyone,/home/groups/f/forms-users,/home/groups/forms/fd-administrators,/home/groups/forms/forms-users,/home/groups/geometrixx,/home/groups/media,/home/groups/o/operators,/home/groups/projects,/home/groups/t/tag-administrators,/home/groups/t/target-activity-authors,/home/groups/u/user-administrators,/home/groups/w/workflow-editors,/home/groups/w/workflow-users,/home/users/a/admin,/home/users/a/anonymous,/home/users/mac,/home/users/media,/home/users/projects,/home/users/system,/home/rep:policy,/home/users/rep:policy,/home/groups/rep:policy \
segment-old:/opt/aem-source/crx-quickstart/repository /opt/aem-destination/crx-quickstart/repository  upgradeusers.log &
8. Once completed, then go to step 3 to migrate the ACLs.  If you are unable to migrate using crx2oak then follow the package migration steps below instead.

Step 2B: Migrate users and groups (using packages)

If users were not imported automatically via LDAP / SAML authentication or CRX2Oak (method A above) then you can package users and groups.  In this case you create two separate packages on the old system (excluding admin and anonymous out-of-the-box users).

1. Copy the path of the anonymous and admin user nodes from the results in Step 1 (“Find the admin and anonymous users”) above.

   For example:

   /home/users/Q/QY5FIMXeQIbGpwZtQ3Dv – admin user on the system where I am creating the package

   /home/users/K/Kj1406Qo9IDODc_nk5Ib – anonymous user on the system where I am creating the package

2. Go to the “Package Manager”, http://host:port/crx/packmgr/index.jsp, and log in as admin.

3. Create package “users”

4. Add a filter to the package config for /home/users with these exclude rules (on the /home/users filter):

   1. exclude /home/users/.*/.tokens
   2. exclude /home/users/Q/QY5FIMXeQIbGpwZtQ3Dv
   3. exclude /home/users/K/Kj1406Qo9IDODc_nk5Ib
   4. exclude /home/users/a/admin
   5. exclude /home/users/a/anonymous
   6. exclude /home/users/system
   7. exclude /home/users/geometrixx
   8. exclude /home/users/media
   9. exclude /home/users/projects
   10. exclude /home/users/mac

5. Build the package.

6. Download the package.

7. Unzip the package zip file on your computer: jar -xvf users.zip META-INF/vault/filter.xml

8. Open the file META-INF/vault/filter.xml in a text editor.

9. Add mode=“merge” to the filter … tag, for example:

   ?xml version="1.0" encoding="UTF-8"?    workspaceFilter version="1.0"    filter root="/home/users" mode="merge"    exclude pattern="/home/users/.*/.tokens"/    exclude pattern="/home/users/Q/QY5FIMXeQIbGpwZtQ3Dv"/    exclude pattern="/home/users/K/Kj1406Qo9IDODc_nk5Ib"/    exclude pattern="/home/users/a/admin"/    exclude pattern="/home/users/a/anonymous"/    exclude pattern="/home/users/system"/    exclude pattern="/home/users/geometrixx"/    exclude pattern="/home/users/media"/    exclude pattern="/home/users/projects"/    exclude pattern="/home/users/mac"/    /filter    /workspaceFilter
   

10. Re-zip the modified package contents so it includes the change.

    jar -uvf users.zip META-INF/vault/filter.xml

11. Create a “groups” package that contains a filter rule /home/groups.

12. Repeat steps 11-14 for the groups package.

13. (Upgrade only) If performing migration to newer AEM version, then install a fresh local AEM instance of the old version(with nosamplecontent), and install the users package, and then the groups package there. Then, perform an in-place upgrade to the new version on that instance. This converts the users to the new Oak representation. After the in-place upgrade, repackage the users again to port them to your intended upgraded instance. Do the same for the user groups.

14. Install the users package on the new system.

15. Install the groups package on the new system.

16. If you are migrating from an older AEM version to 6.3, then go to the /useradmin UI and add the user replication-receiver to the “administrators” group.

Step 3. Migrate ACLs

If you are able to install tools (ACS Commons) to AEM, then follow these steps:

1. Download and install ACS Commons.
2. Follow the steps provided here to create an ACL package.
3. Go to http://aem-host:port/crx/packmgr/index.jsp and log in as admin.
4. Click the ACL package.
5. Click Edit.
6. Select the Advanced tab (see screenshot below).
7. In the AC Handling drop-down menu select Merge to avoid removing existing ACLs on the destination system. This is especially important when migrating ACLs between different versions of AEM (as it avoids removing out of the box ACLs).

If you are not able to install tools (ACS Commons) to AEM, then follow these steps. Note that the machine where you run these commands must be Mac OS, Linux, or Windows (using Cygwin) with cURL, python, and Java SDK installed.

1. Go to http://src-aem-host:port/crx/packmgr/index.jsp and log in as admin.

2. Create a package named “ACL-migration”

3. Click the Edit button.

4. Select the Advanced tab and set AC Handling mode to Merge.

5. Save.

6. Build the package and download it.

7. On the file system run this command on the package to extract the META-INF/vault/filter.xml file:

   jar -xvf ACL-migration-1.0.zip META-INF/vault/filter.xml

8. In the same directory, run this command to download a json file of the ACL paths under /content from the source instance (set the user name and password and correct host):

   curl -u admin:admin 'http://aemhost/crx/de/query.jsp?' -G --data-urlencode '_dc=1507011481908&_charset_=utf-8&type=xpath&stmt=/jcr:root/content//element(*,rep:ACL)&showResults=true'  data.json

9. Create a file generate-package-filter.py and paste the python code below inside it:

   import json

   from pprint import pprint

   with open ( 'data.json') as data_file:

       data = json.load(data_file)

   print("?xml version=\"1.0\" encoding=\"UTF-8\"?")

   print( "workspaceFilter version=\"1.0\"" )

   for item  in data "results" :

        print( "filter root=\"{path}\" /" . format (path=item "path" ))

   print( "/workspaceFilter" )

10. Run the python script from the same folder where data.json was created and save the output to META-INF/vault/filter.xml (replacing the existing contents of filter.xml):

    python generate-packge-filter.py META-INF/vault/filter.xml

11. Use this command to update the filter.xml within the zip file:

    jar -uvf ACL-migration-1.0.zip META-INF/vault/filter.xml

12. Upload the zip file to the source instance package manager: http://src-aem-host:port/crx/packmgr/index.jsp

13. Click Build or Rebuild to build the package.

14. Download the package from the source AEM server.

15. Upload the package to the destination AEM server’s package manager: http://dst-aem-host:port/crx/packmgr/index.jsp

16. Click Install to install it.

17. Repeat steps 8-16 for any other paths changing the path curl command. For example, this would get the ACLs under /etc instead of /content:

    curl -u admin:admin 'http://aemhost/crx/de/query.jsp?' -G --data-urlencode '_dc=1507011481908&_charset_=utf-8&type=xpath&stmt=/jcr:root/etc//element(*,rep:ACL)&showResults=true'  data.json