Before AEM 6.5, we really only had one UI to manage user permissions.  That’s not to say we couldn’t go to the JCR directly and set ACLs, but the user admin screen was just simpler.

For instance, take this example from the classic user admin console.

Typically, this meant that we would check the root folder to give read to everyone.  This is done because an AEM user can’t do much without access to “/bin” which is directly beneath the root node and you can’t directly add permissions to the bin.

This “read” would trickle down to all of the other nodes.  So, when you wanted to remove access you uncheck the box, you have now added a “deny” policy.

Have you ever accidentally checked a box, saved, then unchecked? You’ve just created another deny. The only solution to remove it is to go and delete the policy.  Even if you delete the user, that deny policy will persist.

Denys not only cause unnecessary clutter, but it also makes troubleshooting permissions issues so much more difficult.  This was a very unclean approach that we adapted to.  Now, we have a better option in AEM to manage permissions.

Touch UI Permissions Console

With the introduction of the Touch UI Permissions Console, you can now set your policies for your Principals.  You also have the option of creating exceptions easily through the UI.

Utilizing the example from before, this is how it looks in the permissions console.

You still have the “read” on root, but now you can create a glob on that node.  Rep:glob=”” sets the read permissions to itself only. This means any nodes directly tied to root will be readable but subfolders will be excluded and will not inherit read.  This gives you more control over what permissions you need to set without having to worry about “accidental” permissions.

I did the same thing on “/content” because authors will get permissions to specific areas through other groups. Again, no need to create a deny.

Although this isn’t a true Principal Authorization implementation, since under the hood it’s still creating the policies for the paths, it’s a big step forward for managing permissions on a more granular level.

Read more about this on the Adobe website.

In my previous post I talked about how to add service users to the YAML file exported by the AC Tool.  But what if you want to do something else that isn’t currently possible without a recompile?

There may be many reasons to create a custom file, the reason I did it was to include my groups’ members in the YAML output so that I can manage group memberships (whenever I choose to).

What is a YAML File

YAML files aren’t as common in JAVA projects. So, for many of us, we just haven’t had much need to use them.  Put simply, a YAML file is just a text-indent formatted file.  The amount of indention on an entry dictates its placement in the hierarchy.

My Disclaimer

Before you use anything you create, please test thoroughly.  A bad YAML file into the AC Tool can break a lot of things. Please make sure that doesn’t happen to you and keep this in mind when  you’re creating your files:

Any users or groups you manage in your configuration file (group_config and user_config sections) must have their ACLs in the same YAML file.  If you try to deploy users and groups without their permissions, you may (and probably will) lose the ACLs.

This is documented here:

https://github.com/Netcentric/accesscontroltool/blob/develop/docs/AdvancedFeatures.md

Custom YAML Servlet

You can choose to implement this many different ways. Since I wrote this code, I actually implemented a custom dashboard.  But a servlet is great to start with because you can link to it but you can also use it from other areas within your code, as well as just hitting the url directly (GET).

The main thing when writing your servlet is really to get the formatting right.

1.) You will likely have three config areas (group_config, user_config and ac_config).  It is possible to not include user_config, but make sure you also don’t generate any ACLs for those users in your YAML.

2.) You will need to indent based on hierarchy.  Here are some constants (the netcentric code also uses these)

public static final int DUMP_INDENTATION_KEY = 4;
public static final int DUMP_INDENTATION_FIRST_PROPERTY = 7;
public static final int DUMP_INDENTATION_PROPERTY = 9;
public static final int DUMP_INDENTATION_PROPERTY_SUB = 11;
public static final String YAML_STRUCTURAL_ELEMENT_PREFIX = "- ";

Top level items do not need an indention (group_config, user_config and ace_config)

Writing the Code

Again, I chose a Servlet because it’s an easy way to get this done, but you can use other methods.

All of the data we need for our files is readily available in AEM.

1.) Generate your group_config section.  (I chose to use queries but you can also use the UserManagement API)

Iterator<Resource> groups = resolver.findResources("SELECT * FROM [rep:Group] AS nodes WHERE ISDESCENDANTNODE([/home/groups]) ORDER BY nodes.[rep:principalName]", Query.JCR_SQL2);

Once you have your group Resources you can iterate them and add them to a list.  At this point you can either add the group object or create a custom object told the attributes you plan to use.  At the very least you will need the groupID, path,memberOf.  As I mentioned before I was doing this to get the members, if you plan to add members also collect the declaredMembers of the group.

This list will later be used to pull the necessary acl information because remember they should match.

while (groups.hasNext()) {
<do stuff and add to list>
}

2.) If you’re including System Users, follow the same process and add them to a new List.

Iterator<Resource> userResources = resolver.findResources("SELECT * FROM [rep:SystemUser] AS nodes WHERE ISDESCENDANTNODE([/home/users]) ORDER BY nodes.[rep:principalName]", Query.JCR_SQL2);

You may need to use different paths here, depending on which System Users you plan to include.

3.) Collect the data for your ACLs.

Use the lists you created above to iterate all of the acls related to the group and user principles. Do this for each user and group.

Iterator<Resource> repResources = resolver.findResources("SELECT * FROM [rep:ACE] WHERE [rep:principalName]='"+principal+"'", Query.JCR_SQL2);

We use rep:ACE so that we can get all of them at once, but you will need to distinguish between allow and deny policies. So when you store your data in a LIST, be sure to know how to tell them apart.  You can create a custom object and store the information, then add that object to the list.

if(vm.get("jcr:primaryType").toString().equalsIgnoreCase("rep:GrantACE")) {
  type="allow";
}

At the least, you will need the Principle name, type (allow or deny), path, privileges, and restrictions.

Once you have collected all of the data it’s time to write it out.

For each of the above:

1.) Write out the heading and a configuration for each list.

2.) Remember to indent properly.

3.) Test on a local that you’re not too attached to in case of issues.

In my last post, I showed you how to create your YAML output files.  By default, these files do not contain any user information, however, the tool does give you a pretty easy way to include these by using an OSGi configuration.  The only drawback to this approach is that you can’t change it without changing the config.  In the next post, I’ll show you how to create your own custom servlet to generate a custom YAML file.

In AEM, go to the Configuration Web Console (<host:port>/system/console/configMgr).  Then, open the “AC Tool Dump Service” configuration.  Check the box by “Include users in dumps”.  Also note that even though it says “users”, it only includes Service Users, not regular users.  Hopefully, they will rename it to say Service Users, as it’s a bit misleading.

Save your changes.  What this does is adds a new section to your YAML files called “user_config”, and it includes service users’ information.  It also adds service user ACLs to the ace_config section of the file.

Keeping permissions in sync across environments is an issue for most organizations.  In AEM, you can export permissions using packages but this becomes a tedious process if you need to do this on a regular basis.

I won’t say that the AC Tool solves the problem completely but it’s a good place to start.  In future posts, I will tell you how to extend the functionality to give you more control over what you need for your specific organization.

What this tool does give you is a way to retrieve your permission information from your environments in the form of YAML files.  It also provides an installation hook to deploy your yaml files to environments based on runmodes.  This means that you can have permissions for all of your environments in one code repository, it will only deploy the relevant permissions to the targeted environments with the matching runmodes.

This is already a huge step forward from the manual process.

Installation

There are two packages you will need for installation.  The first is the AC Tool package, the second is the oak index file for the same version.  Though the index file is optional, it’s recommended for those who have a large number of groups.  Personally, I don’t see a reason for not installing it either way.

One thing you want to keep in mind is that you should install the package only once per environment.  This means you do not want to make a part of your regular code deployment, which can cause issues with your deployments.

Creating YAML Files

Once you have the packages installed you can access the tool in two ways, either through the JMX console or through the tools navigation in AEM Tools Console.

Using the Netcentric Dashboard can pull the latest dump file or upload a package with your YAML files for testing.

Deploying Updates

Once you have your files retrieved and modified for import you can deploy them to your environment; remember, this is runmode based so make sure your runmodes are valid for the environment you’re targeting.  If you are only deploying to a single environment, you don’t have to use runmodes.

To deploy you can create a maven project that packages your yaml file structure. If you add the Netcentric hook, it will automatically take effect.  If you would rather double-check things, leave out the hook, and use the “Apply” feature in the Netcentric Dashboard for your changes to take effect. Remember to put in the path to your yaml files before you try to apply the updates.

This configuration will deploy only to environments with an author and a localdev run mode.

Once you have deployed your files, you can check the logs to see if it successfully updated the permissions you expected.  If you aren’t seeing anything in the logs, you may want to check the package installation to make sure it was successful.  If there are any errors in the YAML files, it will create an error and stop the installation.

Tips

1. Whenever possible, don’t redeploy OOTB system users or groups. There’s really no need to unless you’re using them for a specific reason.
2. Don’t create new users other than test users or system users.
3. Do use this tool for removing obsolete users and groups. This way you can remove them from all environments consistently.

You can find more information on the AC Tool, including example files on their github website.

https://github.com/Netcentric/accesscontroltool

Installation package files and oak index files are managed in maven, which can be found here:

https://repo1.maven.org/maven2/biz/netcentric/cq/tools/accesscontroltool/accesscontroltool-package/

https://repo1.maven.org/maven2/biz/netcentric/cq/tools/accesscontroltool/accesscontroltool-oakindex-package/

Have you found a better way of addressing the need to keep permissions in sync? If so, I would love to hear about it!