AEM - How to configure NetCentric AC Tool with AEMCaaS ?

It's time for #AEMGyaan. I know it has been a long time since we met. I hope all of you are staying healthy and safe. Wish you a very happy 2022. Let's hope and pray only the best for all of us this year.

If you are as new to AEMCaaS as me, then you might/have struggled at some point to figure out a lot of things. The concern is that there are not a lot of tutorials yet available out there. We have to spend a lot of time searching and stitching together the information to solve our issues.

One such topic is migrating the user permissions. Migrating users and permissions are always a troubling issue for all of us. And the best solution so far for the same is NetCentric AC Tool. You can find a lot of blogs on the same. I am listing a few below.

Perficient has a good set of blog posts that helps you understand all about Netcentric and YAML files.

Post 1 - Getting started with Netcentric tool - https://blogs.perficient.com/2020/04/23/getting-started-with-the-netcentric-access-control-tool/

Post 2 - Adding Service Users to YAML - https://blogs.perficient.com/2020/04/30/netcentric-ac-tool-adding-service-users-to-your-yaml-files/

Post 3 - https://blogs.perficient.com/2020/05/11/getting-started-with-the-netcentric-access-control-tool-2/

Also you can read

In this article, we will discuss; how we can configure the Netcentric with the AEMCaaS. Basically, for AEMCaaS, the entire AC Tool should be integrated into the deployment package. The official documentation for the same can be found here .

Even after following the above documentation, if some things are not working as expected, you can verify using the below steps.

It is just a few pom.xml configurations, but let me explain that step by step.

You might have to read the requirements before you start making the changes.

STEP 1

1) Main pom.xml

Under DEPENDENCIES add the below

<!-- ====================================================================== --
<!-- D E P E N D E N C I E S -->
<!-- ====================================================================== -->
<dependencyManagement>
    <dependencies>
        
          ....
          ....
          ....


        <!--Netcentric ACL Tool -->
        <dependency>
            <groupId>biz.netcentric.cq.tools.accesscontroltool</groupId>
            <artifactId>accesscontroltool-package</artifactId>
            <classifier>cloud</classifier>
            <type>content-package</type>
            <version>${netcentric.actool}</version>
        </dependency>
        <!--Oak Index for netcentric ACL Tool -->
        <dependency>
            <groupId>biz.netcentric.cq.tools.accesscontroltool</groupId>
            <artifactId>accesscontroltool-oakindex-package</artifactId>
            <classifier>cloud</classifier>
            <type>zip</type>
            <version>${netcentric.actool}</version>
        </dependency>
    </dependencies>
</dependencyManagement>        

Note :- ${netcentric.actool} is added as a property under the parent pm.xml's <properties> section

<properties>
    ......
    ......
    ......

    <netcentric.actool>3.0.4</netcentric.actool>
</properties>        

STEP 2

all/pom.xml

1) Under VAULT PACKAGE PLUGINS --> first plugin section's <embeddeds> add the below

<!-- Netcentric -->
<embedded>
    <groupId>biz.netcentric.cq.tools.accesscontroltool</groupId>
    <artifactId>accesscontroltool-package</artifactId>
    <classifier>cloud</classifier>
    <type>content-package</type>
    <target>/apps/<project>-packages/application/install</target>
</embedded>
<embedded>
    <groupId>biz.netcentric.cq.tools.accesscontroltool</groupId>
    <artifactId>accesscontroltool-oakindex-package</artifactId>
    <classifier>cloud</classifier>
    <type>zip</type>
    <target>/apps/<project>-packages/application/install</target>
</embedded>        

2) UNDER DEPENDENCIES add below

<!-- Netcentric ACL Tool -->
<dependency>
    <groupId>biz.netcentric.cq.tools.accesscontroltool</groupId>
    <artifactId>accesscontroltool-package</artifactId>
    <type>content-package</type>
    <classifier>cloud</classifier>
</dependency>
<!-- Oak Index for Netcentric ACL Tool -->
<dependency>
    <groupId>biz.netcentric.cq.tools.accesscontroltool</groupId>
    <artifactId>accesscontroltool-oakindex-package</artifactId>
    <type>zip</type>
    <classifier>cloud</classifier>
</dependency>        

STEP 3

ui.apps/pom.xml

1) Under VAULT PACKAGE PLUGINS section's filevault-package-maven-plugin add

• Installhook under <properties>

<installhook.actool.class>biz.netcentric.cq.tools.actool.installhook.AcToolInstallHook</installhook.actool.class>        

• Change the <packageType> to mixed

<packageType>mixed</packageType>        

• Add <accessControlHandling> as merge ( careful with this one , it can throw error , if you forget to add the YAML files)

<accessControlHandling>merge</accessControlHandling>        

• Under dependencies add

<!--Netcentric ACL Tool -->
<dependency>
    <groupId>biz.netcentric.cq.tools.accesscontroltool</groupId>
    <artifactId>accesscontroltool-package</artifactId>
    <!-- without classifier leave our for on-premise -->
    <classifier>cloud</classifier>
</dependency>        

2) Under DEPENDENCIES section , add the below

<!-- Netcentric ACL Tool -->
<dependency>
    <groupId>biz.netcentric.cq.tools.accesscontroltool</groupId>
    <artifactId>accesscontroltool-package</artifactId>
    <classifier>cloud</classifier>
    <type>content-package</type>
    <scope>provided</scope>
    <version>${netcentric.actool}</version>
</dependency>
<!--Oak Index for Netcentric ACL Tool -->
<dependency>
    <groupId>biz.netcentric.cq.tools.accesscontroltool</groupId>
    <artifactId>accesscontroltool-oakindex-package</artifactId>
    <classifier>cloud</classifier>
    <type>zip</type>
</dependency>        

Once these steps are done , make sure you add your YAML files under your project. You can take a look at this blog https://shinesolutions.com/2018/10/02/managing-user-permissions-in-aem/ or you can use the sample YAMLs for learning from NetCentric which you can find at https://github.com/Netcentric/accesscontroltool/tree/develop/accesscontroltool-exampleconfig-package/src/main/jcr_root/apps/netcentric/actool-exampleconfig/realProject

Build and install the package after adding the YAML files with correct ACLs. Once successfully installed, your users and groups should be created successfully. This you can verify by checking it under Groups or Users.?

Also take a note to consider best practices while writing the YAML https://www.netcentric.biz/insights/2020/01/ac-tool-with-aem-cloud-service.html

Since we are using the startup-hook , once you build the project and install , the startup hook runs exactly twice in AEMCaaS. You can read further details at https://github.com/Netcentric/accesscontroltool/blob/develop/docs/ApplyConfig.md#startup-hook

The startup hook?runs twice?in AEM as a Cloud Service. Once during building the docker images (for the immutable content) and then during the start of the actual Kubernetes pods. At run time you can see the log of the first execution in?/apps/netcentric/achistory?while all subsequent executions are logged in?/var/netcentric/achistory.

Also as per the official website ; https://www.netcentric.biz/insights/2020/01/ac-tool-with-aem-cloud-service.html

As part of the new system, a Startup Hook has been introduced that triggers the AC Tool on startup. The startup hook runs on start level 27 (the stage when all packages are deployed), just before the system’s ready checks report that the instance is ready:

"

The ACLs for the /apps and /libs will be written only once during the Container Image Build . After this step , /apps and /libs will become read-only and ACL will not be modified on them.

The second time the startup hook runs during Container Deployment during which the /apps and /libs are read only and hence any ACLs for the same will be ignored. As per the official website

Container Deployment typically happens when a new software version is deployed by k8s, but it will also occur when new containers are added due to auto-scaling. In order to avoid unnecessary load, the Startup Hook creates a hash over the YAML configuration files and only runs if that hash has changed.

DEBUGGING

With AEM as a Cloud Service, the Apache Felix system console is not directly available?. Hence the NetCentric AC Tool is available at https://localhost:4502/mnt/overlay/netcentric/actool/content/overview.html/actool

Image Courtesy : https://www.netcentric.biz/insights/2020/01/ac-tool-with-aem-cloud-service.html

I hope this might have helped you all. I am also learning to write the YAML files. Time being, I am referring to the official sample files ????

Please feel free to drop your suggestions and corrections, if any ??