The following steps are performed during the installation of authorizables and ACEs:
- All AC entries are removed from the repository which refer to an authorizable (user/group) being mentioned in the YAML configuration file (no matter to which path those entries refer).
- All authorizables being mentioned in the YAML configuration get created (if necessary, i.e. if they do no exist yet).
- All AC entries generated from the YAML configuration get persisted in the repository. If there are already existing entries for one path (and referring to another authorizable) those are not touched. New AC entries are added at the end of the list. All new AC entries are sorted, so that the Deny entries are listed above the Allow entries. Since the AC entry nodes are evaluated bottom-to-top this sorting order leads to less restrictions (E.g. a user might be member of two groups where one group sets a Deny and the other one sets an Allow. This order ensures that the Allow has a higher priority.).
If at any point during the installation an exception occurs, no changes get persisted in the system. This prevents ending up having a undefined state in the repository.
During the installation a history containing the most important events gets created and persisted in CRX for later examination.
Due to usage of a composite node store the installation of authorizables and ACEs is slightly more complex in AEMaaCS
- During the Docker build ("Build Images") in Cloud Manager the ACLs are applied via Startup Hook
- Afterwards all mutable content is discarded (authorizables in
/homeand ACEs in mutable content) - During deployment the authorizables and ACEs in mutable locations of the repository are installed on the target mutable node store via the Startup Hook
Theoretically step 1 is only necessary if ACEs for immutable content are required. In addition you should configure the Installation Hook in the package containing the YAML configuration to be able to also install on a local AEM SDK instance. The install hook is automatically skipped in AEMaaCS instances.
The following section explain how you can trigger the installation of authorizables and ACEs.
You can automatically install authorizables and ACEs defined in YAML files within a package using the Content Package Install Hook mechanism. If you use the content-package-maven-plugin for building the package, enable the installation hook via:
<plugin>
<groupId>com.day.jcr.vault</groupId>
<artifactId>content-package-maven-plugin</artifactId>
<configuration>
<properties>
<installhook.actool.class>biz.netcentric.cq.tools.actool.installhook.AcToolInstallHook</installhook.actool.class>
</properties>
</configuration>
</plugin>
If you would rather use the filevault-package-maven-plugin for building the package, enable the installation hook via:
<plugin>
<groupId>org.apache.jackrabbit</groupId>
<artifactId>filevault-package-maven-plugin</artifactId>
<configuration>
<properties>
<installhook.actool.class>biz.netcentric.cq.tools.actool.installhook.AcToolInstallHook</installhook.actool.class>
</properties>
</configuration>
</plugin>
The *.yaml files are installed directly from the package content and respect the run mode semantics. Otherwise there is no limitation, so the YAML files will be picked up from anywhere in the package (as long as the parent node does not contain a . followed by one or multiple not matching run modes).
If you wish to limit which YAML files are picked up by the installation hook, you can add one or more regular expressions as package properties that start with the prefix actool.installhook.configFilesPattern.
If the path of a file within its content package (excluding the /jcr_root prefix) matches any of the provided patterns, it will be picked up by the installation hook:
<plugin>
<groupId>org.apache.jackrabbit</groupId>
<artifactId>filevault-package-maven-plugin</artifactId>
<configuration>
<properties>
<installhook.actool.class>biz.netcentric.cq.tools.actool.installhook.AcToolInstallHook</installhook.actool.class>
<actool.installhook.configFilesPattern.groups>/apps/myapp/acl/groups.*</actool.installhook.configFilesPattern.groups>
<actool.installhook.configFilesPattern.users>/apps/myapp/acl/users.*</actool.installhook.configFilesPattern.users>
</properties>
</configuration>
</plugin>
Although it is not necessary that the YAML files are covered by the filter rules of the filter.xml, this is recommended practice. That way you can see afterwards in the repository which YAML files have been processed. However if you would not let the filter.xml cover your YAML files, those files would still be processed by the installation hook.
The installation takes place in phase "PREPARE" by default, i.e. before any other content from the package has been installed. Optionally you can make the hook kick in in phase "INSTALLED" (i.e. after the content has been installed) by additionally setting the package property actool.atInstalledPhase to true. This is helpful if the initial content on which you want to set ACEs is created via classical package content (instead of inline yaml initialContent). That is only properly supported since AEM 6.4.2 (for details look at issue 287) and since ACTool 2.4.0.
An install hook is ignored in the Cloud because the startup hook is to be used for that use case.
Notice: Packages with install hooks can only be installed by admin users (compare with JCRVLT-427)! This is either a user with id admin, system or every member of group administrators.
A Felix Web Console UI is available at "Main" -> "AC Tool". The web console provides fewer operations as JMX, but for manual testing it provides better usability for applying config changes continuously.
The same interface as available via Web Console is also available via Touch UI at Tools -> Security -> Netcentric AC Tool if you are admin on the instance. When using AEM as a Cloud Service, the console will be available if you are in the admin group for the AEM env as set up in adminconsole.
See JMX apply() method.
Curl call
Trigger the 'apply' method of the AC JMX service through HTTP Post
curl -sS --retry 1 -u ${CQ_ADMINUSER}:${CQ_ADMINPW} -X POST "http://${CQ_SERVER}:${CQ_PORT}/system/console/jmx/biz.netcentric.cq.tools:type=ACTool/op/apply/"
When using the Sling Feature Model, the AC tool is automatically triggered upon startup. The startup hook is auto-activated for the case the Sling OSGi installer is not present which is usually the case when using the Sling Feature Model. The behaviour can be adjusted via OSGi config AC Tool Startup Hook (PID biz.netcentric.cq.tools.actool.startuphook.impl.AcToolStartupHookServiceImpl) but the default is usually correct.
The startup hook requires the AC Tool Installation Service (PID biz.netcentric.cq.tools.actool.impl.AcInstallationServiceImpl) to be configured correctly, i.e. its configuration path must point to the nodes containing the YAML files.
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.
The AC Tool handles a composite node store repository correctly (it will automatically only run with paths that are not ready-only). To avoid overhead for the case a configuration has already been applied, an MD5 checksum is created over all configuration files and the configuration is only applied for the case the checksum has changed.
The startup hook is the only way to automatically apply ACLs during startup and is therefore necessary for installing authorizables and applying ACEs on mutable content in AEM as a Cloud Service. This mechanism should be combined with the Installation Hookto be able to use the same package with a local AEM SDK.
Use Touch UI to validate your results.
The Upload Listener Service allows to automatically apply the configuration upon changes in the yaml files in CRX. It registers a JCR listener per configured path in AC Tool Installation Service and applies the corresponding changes with a configured delay (to aggregate multiple change events into installation). By default it is disabled.
NOTE: Usually it is better to rely on the install hook and manual executions via the user interface when needed.
The upload listener service requires the AC Tool Installation Service (PID biz.netcentric.cq.tools.actool.impl.AcInstallationServiceImpl) to be configured correctly, i.e. its configuration path must point to the nodes containing the YAML files.
Generally it is best practice to keep the yaml files in source control and only use one of the above methods to trigger the installation of those files. However, for some support scenarios it can be useful to be able to apply small yaml fragments directly. This can be achieved by using the following groovy script (using the AEM Groovy Console):
import static org.apache.jackrabbit.commons.JcrUtils.*
import static org.apache.commons.io.IOUtils.*
import biz.netcentric.cq.tools.actool.api.AcInstallationService
def runAcTool(adhocFolder, adhocFile, yaml) {
putFile(getOrCreateByPath(adhocFolder, "nt:folder", session), adhocFile, "text/yaml", toInputStream(yaml)); session.save();
return getService(AcInstallationService.class).apply(adhocFolder)
}
runAcTool("/tmp/actool-adhoc", "actool.yaml", """
- user_config:
- test-user:
- name: "My test user"
path: /home/users/testusers
""")
As for any executions, the log of ad hoc installations are found underneath /var/statistics/achistory.