Migrate users, groups, and ACLs between AEM instances
This article provides various methods for migrating Users and Groups with ACL Permissions in AEM from one server to another or from one AEM instance to another.
Description description
Environment
Adobe Experience Manager 6.5 (AEM)
Issue/Symptoms
Migrate Users and Groups with ACL Permissions in AEM from one server to another or from one AEM instance to another.
Resolution resolution
Step 1: Find the admin and anonymous users
- Go to CRXDE lite app
/crx/de/index.jsp
and log in as admin user (on the source system). - Go to Tools
=>
Query. - In the bottom Query box, enter this query to find the admin user:
/jcr:root/home/users//element(*,rep:User)[ @rep:principalName="admin"]
. - Click Execute, and copy the path of the admin user node in the results to a text file.
- Repeat step 3 with a query for anonymous user:
/jcr:root/home/users//element(*,rep:User)[ @rep:principalName="anonymous"]
. - 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 2: Migrate users and groups (using packages)
If users were not imported automatically via LDAP/SAML authentication or Crx2Oak (step 2A above), 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).
Follow these steps:
-
Copy the path of the anonymous and admin user nodes from the results in Step 1 (Step 1: Find the admin and anonymous users) above.
For example:
/home/users/Q/QY5FIMXeQIbGpwZtQ3Dv
– admin user on the system where you’re creating the package, or/home/users/K/Kj1406Qo9IDODc_nk5Ib
– anonymous user on the system where you’re creating the package -
Go to the Package Manager,
http://host:port/crx/packmgr/index.jsp
, and log in as admin. -
Create package users.
-
Add a filter to the package config for
/home/users
with these exclude rules (on the/home/users
filter): (Note: The list might need to change if the product add/remove groups/users from the AEM)- exclude /home/users/.*/.tokens
- exclude /home/users/Q/QY5FIMXeQIbGpwZtQ3Dv
- exclude /home/users/K/Kj1406Qo9IDODc_nk5Ib
- exclude /home/users/a/admin
- exclude /home/users/a/anonymous
- exclude /home/users/system
- exclude /home/users/geometrixx
- exclude /home/users/media
- exclude /home/users/projects
- exclude /home/users/mac
-
Build the package.
-
Download the package.
-
Unzip the package zip file on your computer:
jar -xvf users.zip META-INF/vault/filter.xml
-
Open the file
META-INF/vault/filter.xml
in a text editor. -
Add mode = merge to the
<filter ...>
tag, for example:code language-none <?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>
-
Re-zip the modified package contents so it includes the change.
jar -uvf users.zip META-INF/vault/filter.xml
-
Create a groups package that contains a filter rule
/home/groups
. -
Repeat steps 1-10 for the groups package.
-
(Upgrade only) If performing migration to a newer AEM version, install a fresh local AEM instance of the old version (with
nosamplecontent
), and install both the users package, and 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. -
Install the users package on the new system.
-
Install the groups package on the new system.
-
If you are migrating from an older AEM version to 6.3, go to the
/useradmin
UI and add the user replication-receiver to the administrators group.
Step 3. Migrate ACLs
(NOTE: The package created should only include the ACLs that are needed) 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.
-
Go to
http://src-aem-host:port/crx/packmgr/index.jsp,
and log in as admin. -
Create a package named ACL-migration.
-
Click the Edit button.
-
Select the Advanced tab and set AC Handling mode to Merge.
-
Save.
-
Build the package and download it.
-
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
-
In the same directory, run this command to download a json file of the ACL paths under
/content
from the source instance (set the username, 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
-
Create a file
generate-package-filter.py
and paste the python code below inside it:\code language-none 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\">") form item in data[ "results"] : print("<filter root=\"{path}\" />" . format(path=item[ "path"] )) print("</workspaceFilter>")
-
Run the python script from the same folder where
data.json
was created and save the output toMETA-INF/vault/filter.xml
(replacing the existing contents offilter.xml
):python generate-packge-filter.py > META-INF/vault/filter.xml
-
Use this command to update the
filter.xml
within the zip file:jar -uvf ACL-migration-1.0.zip META-INF/vault/filter.xml
-
Upload the zip file to the source instance package manager:
http://src-aem-host:port/crx/packmgr/index.jsp
-
Click Build or Rebuild to build the package.
-
Download the package from the source AEM server.
-
Upload the package to the destination AEM server’s package manager:
http://dst-aem-host:port/crx/packmgr/index.jsp
-
Click Install to install it.
-
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