Skip to content

Instantly share code, notes, and snippets.

@andrewmkhoury
Last active July 15, 2019 12:32
Show Gist options
  • Save andrewmkhoury/c32e6bd4e339a7c9944e0399254eb2b5 to your computer and use it in GitHub Desktop.
Save andrewmkhoury/c32e6bd4e339a7c9944e0399254eb2b5 to your computer and use it in GitHub Desktop.
Migrating AEM Users, Groups and ACLs between instances
  1. Migrate users and groups (If users were not imported automatically via LDAP) Package users and groups (2 separate packages) on the old system (excluding admin and anonymous OOTB users)

    1. Go to CRXDE lite app /crx/de/index.jsp and log in as admin user (on the old 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 should have two paths, one for "admin" and one for "anonymous")

      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
    7. Go to the "Package Manager", http://host:port/crx/packmgr/index.jsp, and log in as admin

    8. Create a package "users"

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

      • 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
    10. Build the package

    11. Download the package

    12. Unzip the package zip file on your computer

    jar -xvf users.zip META-INF/vault/filter.xml
    
    1. Open the file META-INF/vault/filter.xml in a text editor
    2. 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>
    
    1. Re-zip the modified package contents so it includes the change
    jar -uvf users.zip META-INF/vault/filter.xml
    
    1. Create a "groups" package that contains a filter rule /home/groups
    2. Repeat steps 11-14 for the groups package
    3. (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.
    4. Install the users package on the new system
    5. Install the groups package on the new system
    6. 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
  2. Migrate ACLs

    1. 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 on the ACL package
      5. Click Edit
      6. Select the Advanced tab (see screenshot below)
      7. In the AC Handling dropdown 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).
    2. 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 new 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
      
      1. 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 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
      
      1. 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>")
      
      1. 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
      
      1. Use this command to update the filter.xml within the zip file:
       jar -uvf ACL-migration-1.0.zip META-INF/vault/filter.xml
      
      1. Upload the zip file to the source instance package manager: http://src-aem-host:port/crx/packmgr/index.jsp
      2. Click Build or Rebuild to build the package
      3. Download the package from the source AEM server
      4. Upload the package to the destination AEM server's package manager: http://dst-aem-host:port/crx/packmgr/index.jsp
      5. Click Install to install it
      6. 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
      
@pra201886
Copy link

There is a small issue while doing it for migration if other groups/Users are member of administrators group. The problem got solved by doing the following steps:

  1. Follow the same steps for group mentioned here at source AEM server.
  2. Remove the members of administrators group except "admin" user.
  3. After Installation at Destination server, add the members again in "admnistrators" groups at both source and destination AEM servers.

Note : I have assumed the source server is the server from where the users/groups needs to be migrated and the destination server is the server where groups/users needs to be installed/added.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment