Oak Documentation

Access Control Management

The access control management part of the CUG authorization models follows the requirements defined by JSR 283 and the extensions defined by Jackrabbit API (see section Access Control Management with the following characterstics:

Permission Evaluation

As stated above evaluation of the restricted areas requires the PARAM_CUG_ENABLED configuration option to be set to true. This switch allows to setup restricted areas in a staging enviroment and only let them take effect in the public facing production instance.

If permission evaluation is enabled, the PermissionProvider implementation associated with the authorization model will prevent read access to all restricted areas defined by a CugPolicy. Only Principals explicitly allowed by the policy itself or the globally configured CugExclude will be granted read permissions to the affected items in the subtree.

For example, applying and persisting a new CugPolicy at path /content/restricted/apache_foundation, setting the principal names to apache-members and jackrabbit-pmc will prevent read access to the tree defined by this path for all Subjects that doesn't match any of the two criteria:

• the Subject containsPrincipal apache-members and|or jackrabbit-pmc (as defined in the CugPolicy)
• the Subject contains at least one Principal explicitly excluded from CUG evaluation in the configured, global CugExclude

This further implies that the PermissionProvider will only evaluate regular read permissions (i.e. READ_NODE and READ_PROPERTY). Evaluation of any other permissions including reading the cug policy node (access control content) is consequently delegated to other authorization modules. In case there was no module dealing with these permissions, access will be denied (see in section Combining Multiple Authorization Models for details).

Permission Evaluation with Multiplexed Stores

The CUG authorization module is not designed to be used in combination with non-default mounts. If any of the configured supported paths (see below) is found to be an ancestor of any non-default mount or included therein the activation/modification of the CugConfiguration will fail with immediately and log an error.

Configuration Parameters

The org.apache.jackrabbit.oak.spi.security.authorization.cug.impl.CugConfiguration supports the following configuration parameters:

Note: depending on other the authorization models deployed in the composite setup, the number of CUGs used in a given deployment as well as other factors such as predominant read vs. read-write, the performance of overall permission evaluation may benefit from changing the default ranking of the CUG authorization model.

Excluding Principals

The CUG authorization setup can be further customized by configuring the CugExcludeImpl service with allows to list additional principals that need to be excluded from the evaluation of restricted areas:

Note: This implementation extends the default exclusion list. Alternatively, it is possible to plug a custom CugExclude implementation matching specific needs (see below).

Deploy CugConfiguration

 // setup CugConfiguration
 ConfigurationParameters params = ConfigurationParameters.of(AuthorizationConfiguration.NAME,
         ConfigurationParameters.of(ConfigurationParameters.of(
                 CugConstants.PARAM_CUG_SUPPORTED_PATHS, "/content",
                 CugConstants.PARAM_CUG_ENABLED, true)));
 CugConfiguration cug = new CugConfiguration();
 cug.setParameters(params);
 
 // bind it to the security provider
 SecurityProvider securityProvider = SecurityProviderBuilder.newBuilder().with(configuration).build();
 
 CompositeConfiguration<AuthorizationConfiguration> composite = (CompositeConfiguration) securityProvider
       .getConfiguration(AuthorizationConfiguration.class);
 AuthorizationConfiguration defConfig = composite.getDefaultConfig();
 
 cug.setSecurityProvider(securityProvider);
 cug.setRootProvider(((ConfigurationBase) defConfig).getRootProvider());
 cug.setTreeProvider(((ConfigurationBase) defConfig).getTreeProvider());
 composite.addConfiguration(cug);
 composite.addConfiguration(defConfig);
 
 // create the Oak repository (alternatively: create the JCR repository)
 Oak oak = new Oak()
         .with(new InitialContent())
         // TODO: add all required editors
         .with(securityProvider);
         withEditors(oak);
 ContentRepository contentRepository = oak.createContentRepository();

Customize CugExclude

The following steps are required in order to customize the CugExclude implementation in a OSGi-based repository setup. Ultimately the implementation needs to be referenced in the org.apache.jackrabbit.oak.spi.security.authorization.cug.impl.CugConfiguration.

1. implement CugExclude interface according to you needs,
2. make your implementation an OSGi service
3. deploy the bundle containing your implementation in the OSGi container and activate the service.
4. make sure the default CUGExclude service is properly replaced by the custom implementation.

@Component()
@Service(CugExclude.class)
public class MyCugExclude implements CugExclude {

    private static final Principal PRINCIPAL_APACHE_MEMBERS = new PrincipalImpl("apache-members");
    private static final Principal PRINCIPAL_JACKRABBIT_PMC = new PrincipalImpl("jackrabbit_pmc");

    public MyCugExclude() {}

    //-----------------------------------------------------< CugExclude >---
    @Override
    public boolean isExcluded(@Nonnull Set<Principal> principals) {
        return principals.contains(PRINCIPAL_APACHE_MEMBERS) || principals.contains(PRINCIPAL_JACKRABBIT_PMC);
    }

    //------------------------------------------------< SCR Integration >---
    @Activate
    private void activate(Map<String, Object> properties) {
    }
}