Closed User Groups in AEM closed-user-groups-in-aem

Introduction introduction

Since AEM 6.3, there is a new Closed User Group implementation intended to address the performance, scalability, and security issues present with the existing implementation.

The goal of the new implementation is to cover existing functionality where needed while at the same time addressing problems and design limitations from older versions. The result is a new CUG design with the following characteristics:

The New Custom User Group Implementation the-new-custom-user-group-implementation

A CUG as it is known in the context of AEM consists of the following steps:

The new implementation has been designed to draw a line between the authentication and the authorization elements. As of AEM 6.3, it is possible to restrict read access without explicitly adding an authentication requirement. For example, if a given instance requires authentication altogether or a given tree already resides in a subtree that requires authentication already.

Equally, a given tree can be marked with an authentication requirement without changing the effective permission setup. The combinations and results are listed in the Combining CUG Policies and the Authentication Requirement section.

Overview overview

Authorization: Restricting Read Access authorization-restricting-read-access

The key feature of a CUG is restricting read access on a given tree in the content repository for everyone except selected principals. Instead of manipulating the default access control content on the fly the new implementation takes a different approach by defining a dedicated type of access control policy that represents a CUG.

Access Control Policy for CUG access-control-policy-for-cug

This new type of policy has the following characteristics:

The implementation of PrincipalSetPolicy used to represent CUGs in addition defines that:

These CUG policies are deployed to an AEM instance through a separate authorization module called oak-authorization-cug. This module comes with its own access control management and permission evaluation. In other words, the default AEM setup ships an Oak content repository configuration that combines multiple authorization mechanisms. For more info, see this page on the Apache Oak Documentation.

In this composite setup a new CUG does not replace the existing access control content attached to the target node, but is designed to be a supplement which can also be removed later on without affecting the original access control, that by default in AEM would be an access control list.

In contrast to the former implementation the new CUG policies are always recognized and treated as access control content. This implies that they are created and edited using the JCR access control management API. For more info, see the Managing CUG Policies section.

Permission Evaluation of CUG Policies permission-evaluation-of-cug-policies

Apart from a dedicated access control management for CUGs, the new authorization model lets you conditionally enable permission evaluation for its policies. This lets you setup CUG policies in a staging environment, and only enable evaluation of the effective permissions once replicated to the production environment.

Permission evaluation for CUG policies and the interaction with the default or any additional authorization model follows the pattern designed for multiple authorization mechanisms in Apache Jackrabbit Oak: a given set of permissions is granted if and only if all models grant access. See this page for more details.

The following characteristics apply for the permission evaluation associated with the authorization model designed to handle and evaluate CUG policies:

The effect of a single CUG policy upon permission evaluation can be summarized as follows:

Best Practices best-practices

The following best practices should be taken into account for defining restricted read access through CUGs:

Authentication: Defining the Auth Requirement authentication-defining-the-auth-requirement

The authentication-related parts of the CUG feature let you mark trees that require authentication and optionally specify a dedicated login page. In accordance to the previous version, the new implementation lets you mark trees that require authentication in the content repository and conditionally enable synchronization with the Sling org.apache.sling.api.auth.Authenticatorresponsible for ultimately enforcing the requirement and redirecting to a login resource.

These requirements are registered with the Authenticator by means of an OSGi service that provides the sling.auth.requirements registration property. These properties are then used to dynamically extend the authentication requirements. For more details, consult the Sling documentation.

Defining the Authentication Requirement with A Dedicated Mixin Type defining-the-authentication-requirement-with-a-dedicated-mixin-type

For security reasons the new implementation replaces the usage of a residual JCR property by a dedicated mixin type called granite:AuthenticationRequired, which defines a single optional property of type STRING for the login path granite:loginPath. Only content changes related to this mixin type will lead to update of the requirements registered with Apache Sling Authenticator. The modifications are tracked upon persisting any transient modifications and thus require a javax.jcr.Session.save() call to become effective.

The same applies for the granite:loginPath property. It will only be respected if it is defined by the auth-requirement related mixin type. Adding a residual property with this very name at an unstructured JCR node will not show the desired effect and the property will be ignored by the handler responsible for updating the OSGi registration.

Registering the Authentication Requirement and Login Path With the Sling Authenticator registering-the-authentication-requirement-and-login-path-with-the-sling-authenticator

Since this type of authentication requirement is expected to be limited to certain run modes and to a small subset of trees within the content repository, tracking of the requirement mixin type and the login path properties is conditional and bound to a corresponding configuration that defines the supported paths (see Configuration Options below). Consequently, only changes within the scope of these supported paths will trigger an update of the OSGi registration, elsewhere both the mixin type and the property will be ignored.

The default AEM setup now makes use of this configuration by allowing to set the mixin in the author run mode but only have it take effect upon replication to the publish instance. See this page for details how Sling enforces the authentication requirement.

Adding the granite:AuthenticationRequired mixin type within the configured supported paths will cause the OSGi registration of the responsible handler to be updated containing a new, additional entry with the sling.auth.requirements property. If a given authentication requirement specifies the optional granite:loginPath property, the value is additionally registered with the Authenticator with a ‘-’ prefix to be excluded from authentication requirement.

Evaluation and Inheritance of the Authentication Requirement evaluation-and-inheritance-of-the-authentication-requirement

Apache Sling authentication requirements are expected to be inherited through the page or node hierarchy. The very details of the inheritance and the evaluation of the authentication requirements such as order and precedence are considered an implementation detail and will not be documented in this article.

Evaluation of Login Path evaluation-of-login-path

The evaluation of the login path and redirect to the corresponding resource upon authentication is currently an implementation detail of the Adobe Granite Login Selector Authentication Handler ( com.day.cq.auth.impl.LoginSelectorHandler), which is an Apache Sling AuthenticationHandler configured with AEM by default.

Upon calling AuthenticationHandler.requestCredentials this handler makes an attempt to determine the mapping login page to which the user will be redirected. This includes the following steps:

The target of this documentation is the evaluation of the login path as exposed by the internal LoginPathProvider interface. The implementation shipped since AEM 6.3 behaves as follows:

The LoginPathProvider as implemented by the new auth-requirement support in Granite exposes login paths as defined by the granite:loginPath properties, which in turn are defined by the mixin type as described above. The mapping of the resource path holding the login path and the property value itself is kept in memory and will be evaluated to find a suitable login path for other nodes in the hierarchy.

Best Practices best-practices-1

The following best practices should be taken into account when defining authentication requirements:

Representation in the Repository representation-in-the-repository

CUG Policy Representation in the Repository cug-policy-representation-in-the-repository

The Oak documentation covers the how the new CUG policies are reflected in the repository content. For more information consult this page.

Authentication Requirement in the Repository authentication-requirement-in-the-repository

The need for a separate authentication requirement is reflected in the repository content with a dedicated mixin node type placed at the target node. The mixin type defines an optional property to specify a dedicated login page for the tree defined by the target node.

The page associated with the login path may be located inside or outside that tree. It will be excluded from the authentication requirement.

[granite:AuthenticationRequired]
      mixin
      - granite:loginPath (STRING)

Managing CUG Policies and Authentication Requirement managing-cug-policies-and-authentication-requirement

Managing CUG Policies managing-cug-policies

The new type of access control policies to restrict read access for a CUG is managed using the JCR access control management API and follows the mechanisms described with the JCR 2.0 specification.

Set A New CUG Policy set-a-new-cug-policy

Code to apply a new CUG policy at a node that didn’t have a CUG set before. Note that getApplicablePolicies only returns new policies that have not been set before. At the end the policy needs to written back and changes needs to be persisted.

String path = [...] // needs to be a supported, absolute path

Principal toAdd1 = [...]
Principal toAdd2 = [...]
Principal toRemove = [...]

AccessControlManager acMgr = session.getAccessControlManager();
PrincipalSetPolicy cugPolicy = null;

AccessControlPolicyIterator it = acMgr.getApplicablePolicies(path);
while (it.hasNext()) {
        AccessControlPolicy policy = it.nextAccessControlPolicy();
        if (policy instanceof PrincipalSetPolicy) {
           cugPolicy = (PrincipalSetPolicy) policy;
           break;
        }
}

if (cugPolicy == null) {
   log.debug("no applicable policy"); // path not supported or no applicable policy (for example,
                                                   // the policy was set before)
   return;
}

cugPolicy.addPrincipals(toAdd1, toAdd2);
cugPolicy.removePrincipals(toRemove));

acMgr.setPolicy(path, cugPolicy); // as of this step the policy can be edited/removed
session.save();

Edit An Existing CUG Policy edit-an-existing-cug-policy

The following steps are needed to edit an existing CUG policy. The modified policy needs to written back and changes needs to be persisted using javax.jcr.Session.save().

String path = [...] // needs to be a supported, absolute path

Principal toAdd1 = [...]
Principal toAdd2 = [...]
Principal toRemove = [...]

AccessControlManager acMgr = session.getAccessControlManager();
PrincipalSetPolicy cugPolicy = null;

for (AccessControlPolicy policy : acMgr.getPolicies(path)) {
     if (policy instanceof PrincipalSetPolicy) {
        cugPolicy = (PrincipalSetPolicy) policy;
        break;
     }
}

if (cugPolicy == null) {
   log.debug("no policy to edit"); // path not supported or policy not set before
   return;
}

if (cugPolicy.addPrincipals(toAdd1, toAdd2) || cugPolicy.removePrincipals(toRemove)) {
   acMgr.setPolicy(path, cugPolicy);
   session.save();
} else {
     log.debug("cug policy not modified");
}

Retrieve Effective CUG Policies retrieve-effective-cug-policies

The JCR access control management defines a best effort method to retrieve the policies that take effect at a given path. Because evaluation of CUG policies is conditional and depends on the corresponding configuration to be enabled, calling getEffectivePolicies is a convenient way to verify if a given CUG policy is taking effect in a given installation.

String path = [...] // needs to be a supported, absolute path

AccessControlManager acMgr = session.getAccessControlManager();
PrincipalSetPolicy cugPolicy = null;

// log an debug message of all CUG policies that take effect at the given path
// there could be zero, one or many (creating nested CUGs is possible)
for (AccessControlPolicy policy : acMgr.getEffectivePolicies(path) {
     if (policy instanceof PrincipalSetPolicy) {
        String policyPath = "-";
        if (policy instanceof JackrabbitAccessControlPolicy) {
           policyPath = ((JackrabbitAccessControlPolicy) policy).getPath();
        }
        log.debug("Found effective CUG for path '{}' at '{}', path, policyPath);
     }
}

Retrieve Inherited CUG Policies retrieve-inherited-cug-policies

Finding all nested CUGs that have been defined at a given path irrespective on whether they take effect or not. For more info, see the Configuration Options section.

String path = [...]

List<AccessControlPolicy> cugPolicies = new ArrayList<AccessControlPolicy>();
while (isSupportedPath(path)) {
     for (AccessControlPolicy policy : acMgr.getPolicies(path)) {
         if (policy instanceof PrincipalSetPolicy) {
            cugPolicies.add(policy);
         }
      }
      path = (PathUtils.denotesRoot(path)) ? null : PathUtils.getAncestorPath(path, 1);
}

Managing CUG Policies by Principal managing-cug-policies-by-pincipal

The extensions defined by JackrabbitAccessControlManager that allow to edit access control policies by principal are not implemented with CUG access control management, as by definition a CUG policy always affects all principals: those listed with the PrincipalSetPolicy are being granted read access while all other principals will be prevented to read content in the tree defined by the target node.

The corresponding methods always return an empty policy array but will not throw exceptions.

Managing the Authentication Requirement managing-the-authentication-requirement

The creation, modification, or removal of a new authentication requirement is achieved by changing the effective node type of the target node. The optional login path property can then be written using regular JCR API.

Adding a New Auth Requirement adding-a-new-auth-requirement

Steps to create an authentication requirement are detailed below. The requirement is only registered with the Apache Sling Authenticator if the RequirementHandler has been configured for the tree containing the target node.

Node targetNode = [...]

targetNode.addMixin("granite:AuthenticationRequired");
session.save();

Add a New Auth Requirement with Login Path add-a-new-auth-requirement-with-login-path

Steps to create an authentication requirement including a login path. Note, that the requirement and the exclusion for the login path will only be registered with the Apache Sling Authenticator if the RequirementHandler has been configured for the tree containing the target node.

Node targetNode = [...]
String loginPath = [...] // STRING property

Node targetNode = session.getNode(path);
targetNode.addMixin("granite:AuthenticationRequired");

targetNode.setProperty("granite:loginPath", loginPath);
session.save();

Modify an Existing Login Path modify-an-existing-login-path

Steps to change an existing login path are detailed below. The modification will only be registered with the Apache Sling Authenticator if the RequirementHandler has been configured for the tree containing the target node. The previous login path value will be removed from the registration. The auth requirement associated with the target node is not affected by this modification.

Node targetNode = [...]
String newLoginPath = [...] // STRING property

if (targetNode.isNodeType("granite:AuthenticationRequired")) {
   targetNode.setProperty("granite:loginPath", newLoginPath);
   session.save();
} else {
     log.debug("cannot modify login path property; mixin type missing");
}

Remove an Existing Login Path remove-an-existing-login-path

Steps to remove an existing login path. The login path entry will only be unregistered from the Apache Sling Authenticator if the RequirementHandler has been configured for the tree containing the target node. The auth requirement associated with the target node is not affected.

Node targetNode = [...]

if (targetNode.hasProperty("granite:loginPath") &&
   targetNode.isNodeType("granite:AuthenticationRequired")) {
   targetNode.setProperty("granite:loginPath", null);
   session.save();
} else {
     log.debug("cannot remove login path property; mixin type missing");
}

Or, you can use the below method for achieving the same purpose:

String path = [...] // absolute path to target node

String propertyPath = PathUtils.concat(path, "granite:loginPath");
if (session.propertyExists(propertyPath)) {
    session.getProperty(propertyPath).remove();
    // or: session.removeItem(propertyPath);
    session.save();
}

Remove an Auth Requirement remove-an-auth-requirement

Steps to remove an existing authentication requirement. The requirement will only be unregistered from the Apache Sling Authenticator if the RequirementHandler has been configured for the tree containing the target node.

Node targetNode = [...]
targetNode.removeMixin("granite:AuthenticationRequired");

session.save();

Retrieve Effective Auth Requirements retrieve-effective-auth-requirements

There is no dedicated public API to read all effective authentication requirements as registered with the Apache Sling Authenticator. However, the list is exposed in the system console at https://<serveraddress>:<serverport>/system/console/slingauth under the “Authentication Requirement Configuration” section.

The following image shows the authentication requirements of an AEM publish instance with demo content. The highlighted path of the community page illustrates how a requirement added by the implementation described in this document is reflected in the Apache Sling Authenticator.

Retrieve the Effective Login Path retrieve-the-effective-login-path

There currently is no public API to retrieve the login path that will take effect upon anonymously accessing a resource that requires authentication. See section Evaluation of Login Path for implementation details on how the login path is retrieved.

Note however, that apart from the login paths defined with this feature there are alternative ways to specify the redirect to the login, which should be taken into consideration when designing the content model and the authentication requirements of a given AEM installation.

Retrieve the Inherited Auth Requirement retrieve-the-inherited-auth-requirement

Like with the login path, there is no public API to retrieve the inherited authentication requirements defined in the content. The following sample illustrates how to list all authentication requirements that have been defined with a given hierarchy irrespective on whether they take effect or not. For more info, see Configuration Options.

String path = [...]
Node node = session.getNode(path);

Map<String, String> authRequirements = new ArrayList<String, String>();
while (isSupported(node)) {
     if (node.isNodeType("granite:AuthenticationRequired")) {
         String loginPath = (node.hasProperty("granite:loginPath") ?
                                     node.getProperty("granite:loginPath").getString() :
                                     "";
        authRequirements.put(node.getPath(), loginPath);
        node = node.getParent();
     }
}

Combining CUG Policies and the Authentication Requirement combining-cug-policies-and-the-authentication-requirement

The following table lists the valid combinations of CUG policies and the authentication requirement in an AEM instance that has both modules enabled through configuration.

OSGi Components and Configuration osgi-components-and-configuration

This section provides an overview to the OSGi components and the individual configuration options introduced with the new CUG implementation.

See also the CUG-mapping documentation for a comprehensive mapping of the configuration options between the old and the new implementation.

Authorization: Setup and Configuration authorization-setup-and-configuration

The new, authorization-related parts are contained in the Oak CUG Authorization bundle ( org.apache.jackrabbit.oak-authorization-cug), which is part of the AEM default installation. The bundle defines a separated authorization model aimed to be deployed as an additional way to manage read access.

Setting Up CUG Authorization setting-up-cug-authorization

Setting up CUG authorization is described in detail in the relevant Apache Documentation. By default, AEM has CUG authorization deployed in all run modes. The step-by-step instructions may also be used to disable CUG authorization in those installations that require a different authorization setup.

Configuring the Referrer Filter configuring-the-referrer-filter

You also need to configure the Sling Referrer Filter with all hostnames that may be used to access AEM; for example, via CDN, Load Balancer, and any others.

If the referrer filter is not configured, then errors, similar to the following, are seen when a user tries to log in to a CUG site:

31.01.2017 13:49:42.321 *INFO* [qtp1263731568-346] org.apache.sling.security.impl.ReferrerFilter Rejected referrer header for POST request to /libs/granite/core/content/login.html/j_security_check : https://hostname/libs/granite/core/content/login.html?resource=%2Fcontent%2Fgeometrixx%2Fen%2Ftest-site%2Ftest-page.html&$$login$$=%24%24login%24%24&j_reason=unknown&j_reason_code=unknown

Characteristics of OSGi Components characteristics-of-osgi-components

The following two OSGi components have been introduced to define authentication requirements and specify dedicated login paths:

org.apache.jackrabbit.oak.spi.security.authorization.cug.impl.CugConfiguration

org.apache.jackrabbit.oak.spi.security.authorization.cug.impl.CugExcludeImpl

Configuration Options configuration-options

The key configuration options are:

The available configuration options associated with the CUG-authorization module are listed and described in more detail at the Apache Oak Documentation.

Excluding Principals From CUG Evaluation excluding-principals-from-cug-evaluation

Exempting individual principals from CUG evaluation has been adopted from the former implementation. The new CUG authorization covers this with a dedicated interface named CugExclude. Apache Jackrabbit Oak 1.4 ships with a default implementation that excludes a fixed set of principals and an extended implementation that allows to configure individual principal names. The latter is configured in AEM publish instances.

The default since AEM 6.3 prevents the following principals from being affected by CUG policies:

For more info, see the table in the Default Configuration since AEM 6.3 section below.

The exclusion of the ‘administrators’ group can be altered or expanded in the system console in the configuration section of Apache Jackrabbit Oak CUG Exclude List.

Alternatively, it is possible to provide and deploy a custom implementation of the CugExclude interface to adjust the set of excluded principals if there are special needs. See the documentation on CUG pluggability for details and an example implementation.

Authentication: Setup and Configuration authentication-setup-and-configuration

The new, authentication-related parts are contained in the Adobe Granite Authentication Handler bundle ( com.adobe.granite.auth.authhandler version 5.6.48). This bundle is part of the AEM default installation.

To set up the authentication requirement replacement for the deprecated CUG support, some OSGi components must be present and active in a given AEM installation. For more details see Characteristics of OSGi Components below.

Characteristics of OSGi Components

The following two OSGi components have been introduced to define authentication requirements and specify dedicated login paths:

com.adobe.granite.auth.requirement.impl.RequirementService

com.adobe.granite.auth.requirement.impl.DefaultRequirementHandler

Configuration Options configuration-options-1

The authentication-related parts of the CUG rewrite only come with a single configuration option associated with the Adobe Granite Authentication Requirement and Login Path Handler:

“Authentication Requirement and Login Path Handler”

Default Configuration since AEM 6.3 default-configuration-since-aem

New installations of AEM will by default use the new implementations both for the authorization and authentication-related parts of the CUG feature. The old implementation “Adobe Granite Closed User Group (CUG) Support” has been deprecated and will by default be disabled in all AEM installations. The new implementations will instead be enabled as follows:

Author Instances author-instances

Publish Instances publish-instances

Disabling CUG Authorization and Authentication Requirement disabling-cug-authorization-and-authentication-requirement

The new implementation may be disabled altogether in case a given installation does not use CUGs or uses different means for authentication and authorization.

Disable CUG Authorization disable-cug-authorization

Consult the CUG pluggability documentation for details on how to remove the CUG authorization model from the composite authorization setup.

Disable the Authentication Requirement disable-the-authentication-requirement

To disable support for the authentication requirement as provided by the granite.auth.authhandler module it is sufficient to remove the configuration associated with Adobe Granite Authentication Requirement and Login Path Handler.

Interaction with other Modules interaction-with-other-modules

Apache Jackrabbit API apache-jackrabbit-api

To reflect the new type of access control policy used by the CUG authorization model, the API defined by Apache Jackrabbit has been extended. Since version 2.11.0 of the jackrabbit-api module defines a new interface called org.apache.jackrabbit.api.security.authorization.PrincipalSetPolicy, which extends from javax.jcr.security.AccessControlPolicy.

Apache Jackrabbit FileVault apache-jackrabbit-filevault

The import mechanism of Apache Jackrabbit FileVault has been adjusted to deal with access control policies of type PrincipalSetPolicy.

Apache Sling Content Distribution apache-sling-content-distribution

See the above Apache Jackrabbit FileVault section.

Adobe Granite Replication adobe-granite-replication

The replication module has been slightly adjusted to be able to replicate the CUG policies between different AEM instances:

There is one limitation of replicating CUG policies. If a given CUG policy gets removed without removing the corresponding mixin node type rep:CugMixin, the removal will not be reflected upon replication. This has been addressed by always removing the mixin upon policy removal. The limitation may nevertheless show up if the mixin type is manually added.

Adobe Granite Authentication Handler adobe-granite-authentication-handler

The authentication handler Adobe Granite HTTP Header Authentication Handler shipped with the com.adobe.granite.auth.authhandler bundle holds a reference to the CugSupport interface defined by the same module. It is used to calculate the ‘realm’ in certain circumstances, falling back to the realm configured with the handler.

This has been adjusted to make the reference to CugSupport optional to ensure maximal backwards compatibility if a given setup decides to re-enable the deprecated implementation. Installations using the implementation will no longer get the realm extracted from the CUG implementation but will always display the realm as defined with Adobe Granite HTTP Header Authentication Handler.

AEM LiveCopy aem-livecopy

Configuring CUGs in conjunction with LiveCopy is represented in the repository by the addition of one extra node and one extra property as follows:

Both of these elements are created under the cq:Page. With the current design, MSM only handles nodes and properties that are under the cq:PageContent (jcr:content) node.

Therefore, CUG groups cannot be rolled out to Live Copies from Blueprints. Plan around this when configuring Live Copy.

Changes with the New CUG Implementation changes-with-the-new-cug-implementation

The aim of this section is to provide an overview of the changes made to the CUG feature and a comparison between the old and the new implementation. It lists the changes affecting the way CUG support is configured and describes how and by whom CUGs are managed in the repository content.

Differences in CUG Setup and Configuration differences-in-cug-setup-and-configuration

The deprecated OSGi component Adobe Granite Closed User Group (CUG) Support ( com.day.cq.auth.impl.cug.CugSupportImpl) has been replaced by new components to be able to separately handle authorization and authentication-related parts of the former CUG functionality.

Differences in Managing CUGs in the Repository Content differences-in-managing-cugs-in-the-repository-content

The following sections describe the differences between the old and the new implementations from the implementation and security perspectives. While the new implementation aims to provide the same functionality, there are subtle changes that are important to know when using the new CUG.

Differences With Regard To Authorization differences-with-regards-to-authorization

The main differences from an authorization perspective are summarized in the list below:

Dedicated Access Control Content For CUGs

In the old implementation the default authorization model was used to manipulate access control list policies on publish, replacing any existing ACEs by the setup mandated by the CUG. This was triggered by writing regular, residual JCR properties which were interpreted on publish.

With the new implementation the access control setup of the default authorization model is not affected by any CUG being created, modified, or removed. Instead a new type of policy called PrincipalSetPolicy is applied as additional access control content to the target node. This additional policy will be located as a child of the target node and would be a sibling of the default policy node if present.

Editing CUG Policies In Access Control Management

This move from residual JCR properties to a dedicated access control policy has an impact on the permission needed to create or modify the authorization part of the CUG feature. Since this is considered a modification to access control content, it requires jcr:readAccessControl and jcr:modifyAccessControl privileges to be written to the repository. Therefore, only content authors entitled to modify the access control content of a page can set up or modify this content. This contrasts to the old implementation where the ability to write regular JCR properties was sufficient, resulting in a privilege escalation.

Target Node Defined By Policy

Create CUG policies at the JCR node defining the subtree to be subject to restricted read access. This is likely to be a AEM page in case the CUG is expected affect the whole tree.

Note that placing the CUG policy only at the jcr:content node located below a given page will only restrict access to the content s.str of a given page but will not take effect on any siblings or child pages. This may be a valid use case and it is possible to achieve with a repository editor that allows to apply fine grained access content. However, it contrasts the former implementation where placing a cq:cugEnabled property on the jcr:content node was internally remapped to the page node. This mapping is no longer performed.

Permission Evaluation With CUG Policies

Moving from the old CUG support to an additional authorization model, changes the way effective read permissions are evaluated. As described in the Jackrabbit documentation, a given principal allowed to view the CUGcontent will only be granted read access if the permission evaluation of all models configured in the Oak repository grant read access.

In other words, for the evaluation of the effective permissions, both the CUGPolicy and the default access control entries will be taken into account and read access on the CUG content will only be granted if it is granted by both types of policies. In a default AEM publish installation where read access to the complete /content tree is granted for everyone, the effect of the CUG policies will be the same as with the old implementation.

On-Demand Evaluation

The CUG authorization model allows to individually turn on access control management and permission evaluation:

In the new AEM default setup evaluation of CUG policies it is only enabled with the ‘publish’ run mode. See the details on the default configuration since AEM 6.3 for more details. This can be verified by comparing the effective policies for a given path to the policies stored in the content. Effective policies will only be shown in case permission evaluation for CUGs is enabled.

As explained above the CUG access control policies are now always stored in the content but evaluation of the effective permissions that result from those policies will only be enforced if CUG Evaluation Enabled is turned on in the system console at Apache Jackrabbit Oak CUG Configuration. By default, it is enabled with the ‘publish’ run mode only.

Differences With Regard To Authentication differences-with-regards-to-authentication

The differences with regard to authentication are described below.

Dedicated Mixin Type For Authentication Requirement dedicated-mixin-type-for-authentication-requirement

In the former implementation both the authorization and authentication aspects of a CUG were triggered by a single JCR property ( cq:cugEnabled). As far as authentication is concerned this resulted in an updated list of authentication requirements as stored with the Apache Sling Authenticator implementation. With the new implementation the same result is achieved by marking the target node with a dedicated mixin type ( granite:AuthenticationRequired).

Property For Excluding Login Path property-for-excluding-login-path

The mixin type defines a single, optional property called granite:loginPath, which basically corresponds to the cq:cugLoginPage property. In contrast to the previous implementation the login path property will only be respected if its declaring node type is the mentioned mixin. Adding a property with that name without setting the mixin type will have no effect and neither a new requirement nor an exclusion for the login path will be reported to the authenticator.

Privilege For Authentication Requirement privilege-for-authentication-requirement

Adding or removing a mixin type requires jcr:nodeTypeManagement privilege being granted. In the previous implementation, the jcr:modifyProperties privilege is used to edit the residual property.

As far as the granite:loginPath is concerned the same privilege is required to add, modify, or remove the property.

Target Node Defined By Mixin Type target-node-defined-by-mixin-type

Create authentication requirements at the JCR node defining the subtree to be subject to enforced login. This is likely to be an AEM Page in case the CUG is expected to affect the whole tree and the UI for the new implementation will consequently add the auth-requirement mixin type on the page node.

Placing the CUG policy only at the jcr:content node located below a given page will only restrict access to the contents, but will not take affect on the page node itself nor on any child pages.

This may be a valid scenario and is possible with a repository editor that allows to place the mixin at any node. However, the behavior contrasts the former implementation, where placing a cq:cugEnabled or cq:cugLoginPage property on the jcr:content node was internally remapped ultimately to the page node. This mapping is no longer performed.

Configured Supported Paths configured-supported-paths

Both the granite:AuthenticationRequired mixin type and the granite:loginPath property will only be respected within the scope defined by the set of Supported Paths configuration option present with the Adobe Granite Authentication Requirement and Login Path Handler. If no paths are specified, the authentication requirement feature is disabled altogether. In this case mixin type nor property take effect when being added or set to a given JCR node.

Mapping of JCR Content, OSGi Services, and Configurations mapping-of-jcr-content-osgi-services-and-configurations

The document below provides a comprehensive mapping of OSGi services, configurations, and repository content between the old and the new implementation.

CUG Mapping since AEM 6.3

Get File

Upgrade CUG upgrade-cug

Existing Installations Using the Deprecated CUG existing-installations-using-the-deprecated-cug

The old CUG support implementation has been deprecated and will be removed for in future versions. It is recommended to move to the new implementations when upgrading from versions older than AEM 6.3.

For upgraded AEM installation, it is important to ensure that only one CUG implementation is enabled. The combination of the new and the old, deprecated CUG support is not tested and is likely to cause undesired behavior:

Migrating Existing CUG Content migrating-existing-cug-content

Adobe provides a tool for migrating to the new CUG implementation. To use it, perform the following steps: