Oak Documentation

FilterProvider and Filter

In order to be operational the principal-based authorization needs to have a FilterProvider configured. The corresponding Filter defines if the model is able to evaluate permissions for a given set of principals. For any unsupported set of principals permission evaluation will be skipped altogether. Similarly, access control policies can only be obtained and modified for supported principals.

Apart from validating principals the Filter interface is also responsible for mapping each supported principal to a location in the repository where the access control setup for that principal is being stored.

See section Implementation Details for a description of the provider implementation present with the module. Section Pluggability describes how to deploy a custom implementation.

Access Control Policies

The principal-based authorization model returns two types of policies:

• PrincipalPolicyImpl: a mutable policy implementating PrincipalAccessControlList, which is returned upon JackrabbitAccessControlManager.getApplicablePolicies(Principal) and JackrabbitAccessControlManager.getPolicies(Principal).
• ImmutableACL: whenever effective policies are returned upon calling AccessControlManager.getEffectivePolicies(String) and JackrabbitAccessControlManager.getEffectivePolicies(Set<Principal>).

Management by Principal

In order to manage access control the Jackrabbit API extensions need to be used (see JackrabbitAccessControlManager).

• JackrabbitAccessControlManager.getApplicablePolicies(Principal): if the configured Filter handles the specified principal this method will return a single empty modifiable policy of type PrincipalAccessControlList if no policy has been set for the target principal before.
• JackrabbitAccessControlManager.getPolicies(Principal): once an applicable policy has been set, this method will return a single modifiable policy of type PrincipalAccessControlList.

The following characteristics apply when modifying the PrincipalAccessControlList defined by this implementation:

• all entries will grant access (i.e. no deny)
• the effective path parameter must be an absolute JCR path or null for repository level privileges.
• the effective path may point to a non-existing node.
• the entry may define one or many supported privileges (see AccessControlManager.getSupportedPrivileges(String absPath) and Supported Privileges below)
• additional restrictions may optionally be specified according to JackrabbitAccessControlList.getRestrictionNames (see Supported Restrictions below)
• entries will be added to the list in the order they are created
• while equal entries will not be added to the list, no additional effort is made to avoid or cleanup redundant entries.
• entries can be reordered within the list (JackrabbitAccessControlList.orderBefore) but this doesn't impact the net effect (no denies).

Since PrincipalAccessControlList extends JackrabbitAccessControlList, new entries can also be added using variants of the addEntry method. Please note the following principles:

• the specified Principal must be equal to the principal for which the policy was obtained
• only allow entries are supported (see above)
• the entry may define one or many supported privileges (see AccessControlManager.getSupportedPrivileges(String absPath) and Supported Privileges below)
• the new entry must come with a single value rep:nodePath restriction specifying the absolute JCR path where this policy will take effect. To indicate that the entry takes effect at the repository level an empty string value is used.
• additional restrictions may optionally be specified according to JackrabbitAccessControlList.getRestrictionNames (see Supported Restrictions below)

The path of the policies (JackrabbitAccessControlPolicy.getPath) is defined by the configured Filter implementation and will be used to persist the modified policy (AccessControlManager.setPolicy(String, AccessControlPolicy)) or remove it (AccessControlManager.removePolicy(String, AccessControlPolicy)).

Both operations require the editing session to have jcr:modifyAccessControl privilege granted at the access controlled node that will hold the policy. Since the access control entries contained in the policy will take effect at the tree defined by Entry.getEffectivePath(), the editing session in addition needs permission to modify access control content at the path defined with each individual entry. This contrasts the default implementation where a given entry only takes effect at the tree defined by the access controlled node.

Management by Path

Editing access control by path is not supported with the principal-based access control manager. Consequently, AccessControlManager.getApplicablePolicies(String) and AccessControlManager.getPolicies(String) will return an empty iterator/array.

Note however that AccessControlManager.getEffectivePolicies(String) will make a best-effort approach searching for entries that take effect at a given absolute path: the query will look for nodes of type rep:PrincipalEntry that have a property rep:effectivePath matching the target path or any of its ancestors. Restrictions limiting the effect of a given entry are not taken into account. See also JSR 283 section 16.3.5 Scope of a Policy in JSR 283.

Supported Privileges

All privileges registered with the repository are supported by this authorization model.

Supported Restrictions

The principal-based authorization model doesn't come with a dedicated RestrictionProvider. Instead it is built to handle any restriction defined by the Oak authorization setup.

Readable Paths

If the principal-based authorization is used together with the default implementation, it will respect the readable-paths configuration. For trees located at or below the readable paths AccessControlManager.getEffectivePolicies(String absPath) will include a NamedAccessControlPolicy. Note, that in accordance to the default authorization model, this effective policy is not currently not included when looking up effective policies by principal.

Reading and Caching

Once permission evalution is triggered the principal-based model will directly read the effective permissions from the persisted access control content. There exists no separate location for permissions like the permission store present with the default implementation.

All entries defined for a given set of principal are eagerly loaded from the access control content and kept in memory for each instance of ContentSession. This applies to all supported principals irrespective of the size of the individual policies or the size of the principal set.

Note, that the intended use-case for this authorization model expects small sets of system user principals each with a limited set of permissions, which result in comparably small ACLs. See OAK-8227 for benchmark series that measure read operations with increasing number of entries and principals.

Permission Inheritance

In contrast to the default permission evalution the principal-based setup makes no distinction between user and group principals nor does't make any assumptions about the order of principals computed and placed in the Subject upon login. The inheritance model only takes the item hierarchy into account. In other words the evaluation process will start at the target item and search up the item hierarchy for a matching entry. An entry is considered matching if it is defined for any of the principals in the given set, applies to the target item and grants the specified permissions.

Evaluation Shortcut

As soon as an entry matches the target item and grants the requested permission the evaluation will stop. As this model only supports allowing entries there exists no particular requirement to maintain and handle the order of entries for different principals that take effect at a given target.

However, in order to minimize excessive read on the NodeStore it is recommended to avoid fully redundant entries such as e.g.

• entry: granting privileges, redundant: same privileges with additional restrictions
• entry: granting privileges, redundant: subset of these privileges

Readable Paths

Since OAK-8671 principal-based authorization respects the readable paths configuration option present with the default authorization model. For any tree located at or below these configured paths read-access is always granted.

Administrative Access

The principal-based authorization doesn't enforce any special handling for administrative principals. When implementing a custom FilterProvider this should be part of the considerations. An implementation may e.g. choose not to support administrative principals and thus delegate the permission evalution to the default implementation.

Permission Evaluation with Multiplexed Stores

This authorization model can be used in combinition with non-default mounts with one notable limitation: None of the non-default mounts may be located below the configured filter root (see FilterProvider.getFilterRoot()) in order to make sure all policies defined by this model are located in the same mount.

OSGi Setup

The following steps are required in order to deploy the CUG authorization model in an OSGi-base Oak repository:

1. Deploy the oak-authorization-principalbased bundle
2. Configure and activate the built-in FilterProvider or deploy a custom implementation (see below).
3. Make sure you have the default or a custom MountInfoProvider service running
4. Optionally configure the PrincipalBasedAuthorizationConfiguration (“Apache Jackrabbit Oak Principal Based AuthorizationConfiguration”)
5. Find the SecurityProviderRegistration (“Apache Jackrabbit Oak SecurityProvider”) configuration and enter org.apache.jackrabbit.oak.spi.security.authorization.principalbased.impl.PrincipalBasedAuthorizationConfiguration as additional value to the requiredServicePids property.

The third step will enforce the recreation of the SecurityProvider and hence trigger the RepositoryInitializer provided by the principal-based authorization module, that will make sure the required node type definitions are installed.

Non-OSGi Setup

The following example shows a simplified setup that contains the PrincipalBasedAuthorizationConfiguration as additional authorization model (second position in the aggregation). See also unit tests for an alternative approach.

 // setup PrincipalBasedAuthorizationConfiguration
 FilterProvider filterProvider = TODO: define the filter provider;
 MountInfoProvider mip = Mounts.defaultMountInfoProvider();
                 
 PrincipalBasedAuthorizationConfiguration ac = new PrincipalBasedAuthorizationConfiguration();
 ac.bindFilterProvider(filterProvider);
 ac.bindMountInfoProvider(mip);
 // optionally set configuration parameters: ranking, enable aggregationfilter
 
 // bind it to the security provider
 ConfigurationParameters securityConfig = ConfigurationParameters.EMPTY; // TODO define security config options
 SecurityProvider securityProvider = SecurityProviderBuilder.newBuilder().with(securityConfig)
                      .withRootProvider(rootProvider)
                      .withTreeProvider(treeProvider)
                      .build();
 SecurityProviderHelper.updateConfig(securityProvider, ac, AuthorizationConfiguration.class);
                               
 // 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();