Oak Documentation

Overview

The concept of restriction has been created as extension to JCR access control management in order to refine the effect of individual access control entries.

Quoting from JSR 283 section 16.6.2 Permissions:

[…] the permissions encompass the restrictions imposed by privileges, but also include any additional policy-internal refinements with effects too fine-grained to be exposed through privilege discovery. A common case may be to provide finer-grained access restrictions to individual properties or child nodes of the node to which the policy applies.

Furthermore, the restriction concept is aimed to allow for custom extensions of the default access control implementation to meet project specific needs without having to implement the common functionality provided by JCR.

Existing and potential examples of restrictions limiting the effect of a given access control entry during permission evaluation include:

• set of node types
• set of namespaces
• name/path pattern
• dedicated time frame
• size of a value

The set of built-in restrictions available with Jackrabbit 2.x has been extended along with some extensions of the Jackrabbit API. This covers the public facing usage of restrictions i.e. access control management.

In addition, Oak provides its own internal restriction API that adds support for validation and permission evaluation.

Jackrabbit API

The Jackrabbit API adds the following extensions to JCR access control management to read and create entries with restrictions:

• JackrabbitAccessControlList

  • getRestrictionNames() : returns the JCR names of the supported restrictions.
  • getRestrictionType(String restrictionName) : returns the property type of a given restriction.
  • addEntry(Principal, Privilege[], boolean, Map<String, Value>): the map contain the restrictions.
  • addEntry(Principal, Privilege[], boolean, Map<String, Value>, Map<String, Value[]>): allows to specify both single and multi-value restrictions (since Oak 1.0, Jackrabbit API 2.8)

• JackrabbitAccessControlEntry

  • getRestrictionNames(): returns the JCR names of the restrictions present with this entry.
  • getRestriction(String restrictionName): returns the restriction as JCR value.
  • getRestrictions(String restrictionName): returns the restriction as array of JCR values (since Oak 1.0, Jackrabbit API 2.8).

Oak Restriction API

The following public interfaces are provided by Oak in the package org.apache.jackrabbit.oak.spi.security.authorization.restriction and provide support for pluggable restrictions both for access control management and the repository internal permission evaluation:

• RestrictionProvider: interface to obtain restriction information needed for access control and permission management
• Restriction: the restriction object as created using Jackrabbit access control API
• RestrictionDefinition: the static definition of a supported restriction
• RestrictionPattern: the processed restriction ready for permission evaluation
• AggregationAware: optional extension to make a RestrictionProvider aware of being used in an composite setup, since Oak 1.44.0 (see OAK-9782)

Default Implementation

Oak 1.0 provides the following base implementations:

• AbstractRestrictionProvider: abstract base implementation of the provider interface. Since 1.44.0 also implements AggregationAware (see OAK-9782)
• RestrictionDefinitionImpl: default implementation of the RestrictionDefinition interface.
• RestrictionImpl: default implementation of the Restriction interface.
• CompositeRestrictionProvider: Allows aggregating multiple provider implementations (see Pluggability below).
• CompositePattern: Allows aggregating multiple restriction patterns.

Representation in the Repository

All restrictions defined by default in an Oak repository are stored as properties in a dedicated rep:restriction child node of the target access control entry node. Similarly, they are represented with the corresponding permission entry. The node type definition used to represent restriction content is as follows:

[rep:ACE]
  - rep:principalName (STRING) protected mandatory
  - rep:privileges (NAME) protected mandatory multiple
  - rep:nodePath (PATH) protected /* deprecated in favor of restrictions */
  - rep:glob (STRING) protected   /* deprecated in favor of restrictions */
  - * (UNDEFINED) protected       /* deprecated in favor of restrictions */
  + rep:restrictions (rep:Restrictions) = rep:Restrictions protected /* since oak 1.0 */

/**
 * @since oak 1.0
 */
[rep:Restrictions]
  - * (UNDEFINED) protected
  - * (UNDEFINED) protected multiple

Pluggability

The default security setup as present with Oak 1.0 is able to provide custom RestrictionProvider implementations and will automatically combine the different implementations using the CompositeRestrictionProvider.

In an OSGi setup the following steps are required in order to add an action provider implementation:

• implement RestrictionProvider interface exposing your custom restriction(s).
• make the provider implementation an OSGi service and make it available to the Oak repository.
• make sure the RestrictionProvider is listed as required service with the SecurityProvider (see also Introduction)

Please make sure to consider the following recommendations when implementing a custom RestrictionProvider:

• restrictions are part of the overall permission evaluation and thus may heavily impact overall read/write performance
• the hashCode generation of the base implementation (RestrictionImpl.hashCode) relies on PropertyStateValue.hashCode, which includes the internal String representation, which is not optimal for binaries (see also OAK-5784)

@Component
@Service(RestrictionProvider.class)
public class MyRestrictionProvider extends AbstractRestrictionProvider {

    public MyRestrictionProvider() {
        super(supportedRestrictions());
    }

    private static Map<String, RestrictionDefinition> supportedRestrictions() {
        RestrictionDefinition dates = new RestrictionDefinitionImpl("dates", Type.DATES, false);
        return Collections.singletonMap(dates.getName(), dates);
    }

    //------------------------------------------------< RestrictionProvider >---

    @Override
    public RestrictionPattern getPattern(String oakPath, Tree tree) {
        if (oakPath != null) {
            PropertyState property = tree.getProperty("dates");
            if (property != null) {
                return DatePattern.create(property);
            }
        }
        return RestrictionPattern.EMPTY;
    }

    @Nonnull
    @Override
    public RestrictionPattern getPattern(@Nullable String oakPath, @Nonnull Set<Restriction> restrictions) {
        if (oakPath != null) {
            for (Restriction r : restrictions) {
                String name = r.getDefinition().getName();
                if ("dates".equals(name)) {
                    return DatePattern.create(r.getProperty());
                }
            }
        }
        return RestrictionPattern.EMPTY;
    }

    // TODO: implementing 'validateRestrictions(String oakPath, Tree aceTree)' would allow to make sure the property contains 2 date values.
}

class DatePattern implements RestrictionPattern {

    private final Date start;
    private final Date end;

    private DatePattern(@Nonnull Calendar start, @Nonnull Calendar end) {
        this.start = start.getTime();
        this.end = end.getTime();
    }

    static RestrictionPattern create(PropertyState timeProperty) {
        if (timeProperty.count() == 2) {
            return new DatePattern(
                    Conversions.convert(timeProperty.getValue(Type.DATE, 0), Type.DATE).toCalendar(),
                    Conversions.convert(timeProperty.getValue(Type.DATE, 1), Type.DATE).toCalendar()
            );
        } else {
            return RestrictionPattern.EMPTY;
        }
    }

    @Override
    public boolean matches(@Nonnull Tree tree, @Nullable PropertyState property) {
        return matches();
    }

    @Override
    public boolean matches(@Nonnull String path) {
        return matches();
    }

    @Override
    public boolean matches() {
        Date d = new Date();
        return d.after(start) && d.before(end);
    }
};

RestrictionProvider rProvider = CompositeRestrictionProvider.newInstance(new MyRestrictionProvider(), ...);
Map<String, RestrictionProvider> authorizMap = ImmutableMap.of(PARAM_RESTRICTION_PROVIDER, rProvider);
ConfigurationParameters config =  ConfigurationParameters.of(ImmutableMap.of(AuthorizationConfiguration.NAME, ConfigurationParameters.of(authorizMap)));
SecurityProvider securityProvider = SecurityProviderBuilder.newBuilder().with(config).build();
Repository repo = new Jcr(new Oak()).with(securityProvider).createRepository();