Oak Documentation

General

This section covers fundamental concepts of the access control related APIs provided by JCR and Jackrabbit as well as the extensions points defined by Oak.

If you are already familiar with the API and looking for examples you may directly read Using the Access Control Management API for a comprehensive list of method calls as well as examples that may be used to edit the access control content of the repository.

JCR API

Access Control Management is an optional feature defined by JSR 283 consisting of

• Privilege discovery: Determining the privileges that a user has in relation to a node.

• Assigning access control policies: Setting the privileges that a user has in relation to a node using access control policies specific to the implementation.

Whether a given implementation supports access control management is defined by the Repository.OPTION_ACCESS_CONTROL_SUPPORTED descriptor.

Since Oak comes with a dedicated privilege management this section focuses on reading and editing access control information. The main interfaces defined by JSR 283 are:

• AccessControlManager: Main entry point for access control related operations
• AccessControlPolicy: Marker interface for any kind of policies defined by the implementation.
  • AccessControlList: mutable policy that may have a list of entries.
  • NamedAccessControlPolicy: opaque immutable policy with a JCR name.
• AccessControlEntry: association of privilege(s) with a given principal bound to a given node by the AccessControlList.

The JCR access control management has the following characteristics:

• path-based: policies are bound to nodes; a given node may have multiple policies; the null path identifies repository level policies.
• transient: access control related modifications are always transient
• binding: policies are decoupled from the repository; in order to bind a policy to a node or apply modifications made to an existing policy AccessControlManager.setPolicy must be called.
• effect: policies bound to a given node only take effect upon Session.save(). Access to properties is defined by their parent node.
• scope: a given policy may not only affect the node it is bound to but may have an effect on accessibility of items elsewhere in the workspace.

Jackrabbit API

The Jackrabbit API defines various access control related extensions to the JCR API in order to cover common needs such as for example:

• deny access: access control entries can be defined to deny privileges at a given path (JCR only defines allowing access control entries)
• restrictions: limit the effect of a given access control entry by the mean of restrictions
• convenience:
  • reordering of access control entries in an access control list
  • retrieve the path of the node a given policy is (or can be) bound to
• principal-based:
  • principal-based access control management API (in contrast to the path-based default specified by JSR 283)
  • privilege discovery for a set of principals

The following interfaces and extensions are defined:

• JackrabbitAccessControlManager
• JackrabbitAccessControlPolicy
• JackrabbitAccessControlList
• JackrabbitAccessControlEntry
• PrincipalAccessControlList extends JackrabbitAccessControlList for principal-based ac-setup (see Managing Access by Principal for details)
• PrincipalAccessControlList.Entry extends JackrabbitAccessControlEntry for principal-based ac-setup (see Managing Access by Principal for details)
• PrincipalSetPolicy : grants a set principals the ability to perform certain actions (see Managing Access with "Closed User Groups for an example)

API Extensions

Oak defines the following interfaces extending the access control management API:

• PolicyOwner: Interface to improve pluggability of the access control management and allows testing if a giving manager handles a given policy.
• AccessControlConstants: Constants related to access control management.

In addition, it provides some access control related base classes in org.apache.jackrabbit.oak.spi.security.authorization.accesscontrol that may be used for a custom implementation:

• AbstractAccessControlList: abstract base implementation of the JackrabbitAccessControlList interface
  • ImmutableACL: an immutable subclass of AbstractAccessControlList
  • ACE: an abstract subclass that implements common methods of a mutable access control list.
• ReadPolicy: an implementation of NamedAccessControlPolicy used to represent the configured readable paths.

Utilities

The jcr-commons module present with Jackrabbit provide some access control related utilities that simplify the creation of new policies and entries such as for example:

• AccessControlUtils.getAccessControlList(Session, String)
• AccessControlUtils.getAccessControlList(AccessControlManager, String)
• AccessControlUtils.addAccessControlEntry(Session, String, Principal, String[], boolean)

See org.apache.jackrabbit.commons.jackrabbit.authorization.AccessControlUtils for the complete list of methods.

String path = node.getPath();
JackrabbitAccessControlList acl = AccessControlUtils.getAccessControlList(session, path);
acl.addEntry(principal, privileges, true);
acMgr.setPolicy(path, acl);
session.save();

Characteristics of the Default Implementation

The behavior of the default access control implementation is described in sections Access Control Management: The Default Implementation and Restriction Management.

Configuration

The configuration of the access control management implementation is handled within the AuthorizationConfiguration, which is used for all authorization related matters. This class provides the following two access control related methods:

• getAccessControlManager: get a new ac manager instance.
• getRestrictionProvider: get a new instance of the restriction provider.

Further Reading

• Differences wrt Jackrabbit 2.x
• Access Control Management: The Default Implementation
• Using the Access Control Management API
• Restriction Management