You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jackrabbit.apache.org by th...@apache.org on 2018/08/21 10:31:38 UTC
svn commit: r1838538 [29/35] - in /jackrabbit/site/live/oak/docs: ./
architecture/ coldstandby/ features/ nodestore/ nodestore/document/
nodestore/segment/ oak-mongo-js/ oak-mongo-js/fonts/ oak-mongo-js/scripts/
oak-mongo-js/scripts/prettify/ oak-mongo...
Modified: jackrabbit/site/live/oak/docs/security/authorization.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/authorization.html?rev=1838538&r1=1838537&r2=1838538&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/authorization.html (original)
+++ jackrabbit/site/live/oak/docs/security/authorization.html Tue Aug 21 10:31:37 2018
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 at 2018-08-10
+ | Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2018-02-21
| Rendered using Apache Maven Fluido Skin 1.6
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20180810" />
+ <meta name="Date-Revision-yyyymmdd" content="20180221" />
<meta http-equiv="Content-Language" content="en" />
<title>Jackrabbit Oak – Authorization</title>
<link rel="stylesheet" href="../css/apache-maven-fluido-1.6.min.css" />
@@ -52,7 +52,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Main APIs <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="http://www.day.com/specs/jcr/2.0/index.html" title="JCR API">JCR API</a></li>
- <li><a href="https://jackrabbit.apache.org/jcr/jcr-api.html" title="Jackrabbit API">Jackrabbit API</a></li>
<li><a href="../oak_api/overview.html" title="Oak API">Oak API</a></li>
</ul>
</li>
@@ -137,7 +136,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2018-08-10<span class="divider">|</span>
+ <li id="publishDate">Last Published: 2018-02-21<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 1.10-SNAPSHOT</li>
</ul>
@@ -156,14 +155,12 @@
<li><a href="../architecture/nodestate.html" title="The Node State Model"><span class="none"></span>The Node State Model</a> </li>
<li class="nav-header">Main APIs</li>
<li><a href="http://www.day.com/specs/jcr/2.0/index.html" class="externalLink" title="JCR API"><span class="none"></span>JCR API</a> </li>
- <li><a href="https://jackrabbit.apache.org/jcr/jcr-api.html" class="externalLink" title="Jackrabbit API"><span class="none"></span>Jackrabbit API</a> </li>
<li><a href="../oak_api/overview.html" title="Oak API"><span class="none"></span>Oak API</a> </li>
<li class="nav-header">Features and Plugins</li>
<li><a href="../nodestore/overview.html" title="Node Storage"><span class="icon-chevron-down"></span>Node Storage</a>
<ul class="nav nav-list">
<li><a href="../nodestore/documentmk.html" title="Document NodeStore"><span class="icon-chevron-down"></span>Document NodeStore</a>
<ul class="nav nav-list">
- <li><a href="../nodestore/document/mongo-document-store.html" title="MongoDB DocumentStore"><span class="none"></span>MongoDB DocumentStore</a> </li>
<li><a href="../nodestore/document/node-bundling.html" title="Node Bundling"><span class="none"></span>Node Bundling</a> </li>
<li><a href="../nodestore/document/secondary-store.html" title="Secondary Store"><span class="none"></span>Secondary Store</a> </li>
<li><a href="../nodestore/persistent-cache.html" title="Persistent Cache"><span class="none"></span>Persistent Cache</a> </li>
@@ -242,47 +239,54 @@
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
--->
-<div class="section">
+--><div class="section">
<h2><a name="Authorization"></a>Authorization</h2>
<div class="section">
<h3><a name="General_Notes"></a>General Notes</h3>
<p>One of main goals for Oak security, was to clearly separates between access control management (such as defined by the JCR and Jackrabbit API) and the internal permission evaluation.</p>
<p>While access control management is defined to be an optional feature added in JCR 2.0, permission evaluation was mandated since the very first version of JCR even though it remained an implementation detail.</p>
<p>The documentation follows this separations and handles access control and permission evaluation separately:</p>
-<ul>
+<ul>
+
<li><a href="accesscontrol.html">Access Control Management</a></li>
+
<li><a href="permission.html">Permissions</a></li>
</ul>
<p>Despite the fact that there is a distinction between the public facing access control management and the internal permission evaluation, these two topics remain connected to one another and a given authorization model is expected to define and handle both in a consistent manner. Consequently the main entry point for authorization related operations is a single <tt>AuthorizationConfiguration</tt> (see section <a href="#configuration">configuration</a> below).</p>
-<a name="api_extensions"></a>
-### API Extensions
-
+<p><a name="api_extensions"></a></p></div>
+<div class="section">
+<h3><a name="API_Extensions"></a>API Extensions</h3>
<p>The API extensions provided by Oak are covered in the following sections:</p>
-<ul>
+<ul>
+
<li><a href="accesscontrol.html#api_extensions">Access Control Management</a></li>
+
<li><a href="permission.html#api_extensions">Permissions</a></li>
+
<li><a href="authorization/restriction.html#api_extensions">Restriction Management</a></li>
</ul>
-<a name="configuration"></a>
-### Configuration
-
+<p><a name="configuration"></a></p></div>
+<div class="section">
+<h3><a name="Configuration"></a>Configuration</h3>
<p>The configuration of the authorization related parts is handled by the <a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/AuthorizationConfiguration.html">AuthorizationConfiguration</a>. This class provides the following methods:</p>
-<ul>
+<ul>
+
<li><tt>getAccessControlManager</tt>: get a new ac manager instance (see <a href="accesscontrol.html">Access Control Management</a>).</li>
+
<li><tt>getPermissionProvider</tt>: get a new permission provider instance (see <a href="permission.html">Permissions</a>).</li>
+
<li><tt>getRestrictionProvider</tt>: get a new instance of the restriction provider (see <a href="authorization/restriction.html">Restriction Management</a>.</li>
</ul>
<div class="section">
<h4><a name="Configuration_Parameters"></a>Configuration Parameters</h4>
<p>The supported configuration options of the default implementation are described separately for <a href="accesscontrol/default.html#configuration">access control management</a> and <a href="permission/default.html#configuration">permission evalution</a> .</p>
-<a name="pluggability"></a>
-### Pluggability
-
-<p>There are multiple options for plugging authorization related custom implementations:</p></div>
+<p><a name="pluggability"></a></p></div></div>
+<div class="section">
+<h3><a name="Pluggability"></a>Pluggability</h3>
+<p>There are multiple options for plugging authorization related custom implementations:</p>
<div class="section">
<h4><a name="Aggregation_of_Different_Authorization_Models"></a>Aggregation of Different Authorization Models</h4>
<div class="section">
@@ -292,21 +296,26 @@
<div class="section">
<h5><a name="Previous_Versions"></a>Previous Versions</h5>
<p>In previous versions of Oak aggregation of multiple authorization models was not supported and it was only possible to replace the existing <tt>AuthorizationConfiguration</tt>. This would completely replace the default way of handling authorization in the repository.</p>
-<p>In OSGi-base setup this is achieved by making the configuration implementation a service such that it takes precendece over the default.</p>
+<p>In OSGi-base setup this is achieved by making the configuration implementation a service such that it takes precendece over the default. </p>
<p>In a non-OSGi-base setup the custom configuration must be exposed by the <tt>SecurityProvider</tt> implementation.</p></div></div>
<div class="section">
<h4><a name="Extending_the_Restriction_Provider"></a>Extending the Restriction Provider</h4>
<p>In all versions of Oak it is possible to plug custom implementation(s) for the restriction management that allows to narrow the effect of permissions to items matching a given, defined behavior. Details can be found in section <a href="authorization/restriction.html#pluggability">RestrictionManagement</a>.</p>
-<a name="further_reading"></a>
-### Further Reading
+<p><a name="further_reading"></a></p></div></div>
+<div class="section">
+<h3><a name="Further_Reading"></a>Further Reading</h3>
<ul>
-
+
<li><a href="accesscontrol.html">Access Control Management</a></li>
+
<li><a href="permission.html">Permission Evalution</a></li>
+
<li><a href="authorization/restriction.html">Restriction Management</a></li>
+
<li><a href="authorization/composite.html">Combining Multiple Authorization Models</a></li>
-</ul><!-- hidden references --></div></div></div>
+</ul>
+<!-- hidden references --></div></div>
</div>
</div>
</div>
Modified: jackrabbit/site/live/oak/docs/security/authorization/composite.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/authorization/composite.html?rev=1838538&r1=1838537&r2=1838538&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/authorization/composite.html (original)
+++ jackrabbit/site/live/oak/docs/security/authorization/composite.html Tue Aug 21 10:31:37 2018
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 at 2018-08-10
+ | Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2018-04-18
| Rendered using Apache Maven Fluido Skin 1.6
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20180810" />
+ <meta name="Date-Revision-yyyymmdd" content="20180418" />
<meta http-equiv="Content-Language" content="en" />
<title>Jackrabbit Oak – Combining Multiple Authorization Models</title>
<link rel="stylesheet" href="../../css/apache-maven-fluido-1.6.min.css" />
@@ -52,7 +52,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Main APIs <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="http://www.day.com/specs/jcr/2.0/index.html" title="JCR API">JCR API</a></li>
- <li><a href="https://jackrabbit.apache.org/jcr/jcr-api.html" title="Jackrabbit API">Jackrabbit API</a></li>
<li><a href="../../oak_api/overview.html" title="Oak API">Oak API</a></li>
</ul>
</li>
@@ -137,7 +136,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2018-08-10<span class="divider">|</span>
+ <li id="publishDate">Last Published: 2018-04-18<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 1.10-SNAPSHOT</li>
</ul>
@@ -156,14 +155,12 @@
<li><a href="../../architecture/nodestate.html" title="The Node State Model"><span class="none"></span>The Node State Model</a> </li>
<li class="nav-header">Main APIs</li>
<li><a href="http://www.day.com/specs/jcr/2.0/index.html" class="externalLink" title="JCR API"><span class="none"></span>JCR API</a> </li>
- <li><a href="https://jackrabbit.apache.org/jcr/jcr-api.html" class="externalLink" title="Jackrabbit API"><span class="none"></span>Jackrabbit API</a> </li>
<li><a href="../../oak_api/overview.html" title="Oak API"><span class="none"></span>Oak API</a> </li>
<li class="nav-header">Features and Plugins</li>
<li><a href="../../nodestore/overview.html" title="Node Storage"><span class="icon-chevron-down"></span>Node Storage</a>
<ul class="nav nav-list">
<li><a href="../../nodestore/documentmk.html" title="Document NodeStore"><span class="icon-chevron-down"></span>Document NodeStore</a>
<ul class="nav nav-list">
- <li><a href="../../nodestore/document/mongo-document-store.html" title="MongoDB DocumentStore"><span class="none"></span>MongoDB DocumentStore</a> </li>
<li><a href="../../nodestore/document/node-bundling.html" title="Node Bundling"><span class="none"></span>Node Bundling</a> </li>
<li><a href="../../nodestore/document/secondary-store.html" title="Secondary Store"><span class="none"></span>Secondary Store</a> </li>
<li><a href="../../nodestore/persistent-cache.html" title="Persistent Cache"><span class="none"></span>Persistent Cache</a> </li>
@@ -242,21 +239,22 @@
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
--->
-<div class="section">
+--><div class="section">
<h2><a name="Combining_Multiple_Authorization_Models"></a>Combining Multiple Authorization Models</h2>
<div class="section">
<h3><a name="General_Notes"></a>General Notes</h3>
<p>Since Oak 1.4 it is possible to combine multiple authorization models within the default security setup.</p>
<p>The main entry point for the aggregation of multiple authorization models is the <a class="externalLink" href="http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/security/authorization/composite/CompositeAuthorizationConfiguration.java">CompositeAuthorizationConfiguration</a>, which is in charge of generating composite variants of the <tt>AccessControlManager</tt>, <tt>PermissionProvider</tt> and <tt>RestrictionProvider</tt> if multiple authorization modules have been configured (see section <a href="#details">Implementation Details</a> below.</p>
<p><i>Please note:</i> Despite the fact that Oak supports the aggregation of multiple authorization models, this extension is only recommended for experts that have in-depth knowledge and understanding of Jackrabbit/Oak authorization concepts. Doing so might otherwise result in severe security issues and heavily impact overall performance.</p>
-<a name="api_extensions"></a>
-### API Extensions
-
+<p><a name="api_extensions"></a></p></div>
+<div class="section">
+<h3><a name="API_Extensions"></a>API Extensions</h3>
<p>There are two interfaces required to make a given authorization model deployable in an aggregated setup:</p>
-<ul>
+<ul>
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/accesscontrol/PolicyOwner.html">PolicyOwner</a>: Extension to the <tt>AccessControlManager</tt>, that allows a given implementation to claim responsibility for handling certain <tt>AccessControlPolicy</tt> implementations.</li>
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/permission/AggregatedPermissionProvider.html">AggregatedPermissionProvider</a>: Subclass of <tt>PermissionProvider</tt> which is mandated for permission evaluation once multiple providers are configured.</li>
</ul>
<div class="section">
@@ -268,18 +266,21 @@
<div class="section">
<h5><a name="Example"></a>Example</h5>
<p>The permission provider shipped with the <a href="cug.html#details">oak-authorization-cug</a> module has a very limited scope: it only evaluates read-access to regular items at the configured supported paths. This means e.g. that the implementation is not able to determine if write access is granted to a given set of <tt>Principal</tt>s and indicates this fact by just returning the subset of supported read permissions upon <tt>supportedPermissions(Tree, PropertyState, long)</tt>. The aggregated permission provider will consequently not consult this implementation for the evaluation of write permissions and move on to other providers in the aggregate.</p>
-<a name="details"></a>
-### Implementation Details
-
+<p><a name="details"></a></p></div></div></div>
+<div class="section">
+<h3><a name="Implementation_Details"></a>Implementation Details</h3>
<p>As soon as multiple authorization models are configured with the security setup, the <tt>CompositeAuthorizationConfiguration</tt> will return a dedicated <tt>JackrabbitAccessControlManager</tt> and <tt>PermissionProvider</tt> that are wrapping the objects provided by the aggregated implementations.</p>
-<p>Note: as long as a single authorization model is configured (default setup) the <tt>CompositeAuthorizationConfiguration</tt> will omit any extra wrapping.</p></div></div>
+<p>Note: as long as a single authorization model is configured (default setup) the <tt>CompositeAuthorizationConfiguration</tt> will omit any extra wrapping.</p>
<div class="section">
<h4><a name="Access_Control"></a>Access Control</h4>
<p>Once multiple modules are deployed a <a class="externalLink" href="http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/security/authorization/composite/CompositeAccessControlManager.java">CompositeAccessControlManager</a> with the following characteristics will be returned:</p>
-<ul>
+<ul>
+
<li>API calls reading information will return the combined result of the wrapped implementations.</li>
+
<li>Methods defined solely by <tt>JackrabbitAccessControlManager</tt> additionally test for the delegatees to implement that extension.</li>
+
<li>API calls writing back policies will look for the responsible <tt>PolicyOwner</tt> and specifically delegate the call. If no owner can be found an <tt>AccessControlException</tt> is thrown.</li>
</ul>
<p>Hence, a given authorization model is free to implement JCR <tt>AccessControlManager</tt> or the Jackrabbit extension.</p>
@@ -288,12 +289,16 @@
<h4><a name="Permission_Evaluation"></a>Permission Evaluation</h4>
<p>Only models implementing the <tt>AggregatedPermissionProvider</tt> extensions will be respected for aggregation into the <a class="externalLink" href="http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/security/authorization/composite/CompositePermissionProvider.java">CompositePermissionProvider</a>. This allows individual models to cover only a subset of permissions and|or a subset of paths within the repository.</p>
<p>The composite wrapper subsequently applies the following logic to evaluate the effective permissions:</p>
-<ul>
-<li>each delegatee is in ask to evaluate the subset of supported permissions if it claims responsible for the given item/path,</li>
+<ul>
+
+<li>each delegatee is in ask to evaluate the subset of supported permissions if it claims responsible for the given item/path,</li>
+
<li>a delegatee that doesn’t handle any of the permissions in question it is ignored,</li>
+
<li>a delegatee that doesn’t claim responsible for the item/path is ignored,</li>
-<li>a given set of permissions is ultimately granted for a given item/path, if <i>all</i> permissions have been successfully processed and none of the delegatees involved denied access.</li>
+
+<li>a given set of permissions is ultimately granted for a given item/path, if <i>all</i> permissions have been successfully processed and none of the delegatees involved denied access.</li>
</ul>
<p>This implies that evaluation of permissions across multiple implementations is strictly additive: as soon as one provider denies access (either by an explicit deny or by a missing explicit allow) permissions are denied.</p>
<p>Similarly, if a given combination of permission providers fails to process the complete set of permissions (e.g. one permission is not covered by any of the modules) the access will be denied as none of the provider was in charge of proper evaluation.</p>
@@ -301,30 +306,34 @@
<div class="section">
<h4><a name="Restriction_Management"></a>Restriction Management</h4>
<p>Support for multiple restriction providers has already been been present with the default authorization implementation since Oak 1.0. The mechanism described in section <a href="restriction.html">Restriction Management</a> is not affected by the new functionality.</p>
-<p>The <tt>CompositeAuthorizationConfiguration</tt> is in charge of collecting the <tt>RestrictionProvider</tt>s from the aggregated modules and expose the complete set of restrictions in order to meet the API contract.</p>
+<p>The <tt>CompositeAuthorizationConfiguration</tt> is in charge of collecting the <tt>RestrictionProvider</tt>s from the aggregated modules and expose the complete set of restrictions in order to meet the API contract. </p>
<p>Nevertheless, each authorization model is responsible for exposing, validating and evaluating the subset of restrictions it can handle through the access control API extensions and the permission evaluation, respectively. A given model may decide to provide no support for restrictions. Examples include modules that deal with different types of <tt>AccessControlPolicy</tt> where restriction management doesn’t apply (see for example <a href="cug.html#details">oak-authorization-cug</a>).</p>
-<a name="configuration"></a>
-### Configuration
-
+<p><a name="configuration"></a></p></div></div>
+<div class="section">
+<h3><a name="Configuration"></a>Configuration</h3>
<p>By default the <tt>CompositeAuthorizationConfiguration</tt> aggregates results by applying an <tt>AND</tt> operation to the current set of providers. This can be changed via configuration to an <tt>OR</tt>. See section <a href="../../introduction.html#configuration">Introduction to Oak Security</a> for further details.</p>
-<a name="pluggability"></a>
-### Pluggability
-
+<p><a name="pluggability"></a></p></div>
+<div class="section">
+<h3><a name="Pluggability"></a>Pluggability</h3>
<p>The following steps are required to plug an additional authorization model into the Oak repository:</p>
-<ul>
+<ul>
+
<li>Implement your custom <tt>AuthorizationConfiguration</tt></li>
+
<li>Deploy the bundle containing the implementation</li>
+
<li>Bind your <tt>AuthorizationConfiguration</tt> to the <tt>SecurityProvider</tt>:
+
<ul>
-
-<li>in an OSGi setup this is achieved by adding the configuration to the <tt>requiredServicePids</tt> property of the <tt>SecurityProviderRegistration</tt> <i>(“Apache Jackrabbit Oak SecurityProvider”)</i> i.e. forcing the recreation of the <tt>SecurityProvider</tt>.</li>
-<li>in a non-OSGi setup this requires adding the configuration to the <tt>SecurityProvider</tt> (e.g. <i>SecurityProviderBuilder.newBuilder().with(params).build()</i>) and subsequently creating the JCR/Oak repository object.</li>
-</ul>
-</li>
+
+<li>in an OSGi setup this is achieved by adding the configuration to the <tt>requiredServicePids</tt> property of the <tt>SecurityProviderRegistration</tt> <i>(“Apache Jackrabbit Oak SecurityProvider”)</i> i.e. forcing the recreation of the <tt>SecurityProvider</tt>.</li>
+
+<li>in a non-OSGi setup this requires adding the configuration to the <tt>SecurityProvider</tt> (e.g. <i>SecurityProviderBuilder.newBuilder().with(params).build()</i>) and subsequently creating the JCR/Oak repository object.</li>
+ </ul></li>
</ul>
-<p><b>Important Note</b><br />
-Despite the fact that Oak supports the aggregation of multiple authorization models, this extension is only recommended for experts that have in-depth knowledge and understanding of Jackrabbit/Oak authorization concepts. Doing so might otherwise result in severe security issues and heavily impact overall performance.</p><!-- hidden references --></div></div></div>
+<p><b>Important Note</b><br />Despite the fact that Oak supports the aggregation of multiple authorization models, this extension is only recommended for experts that have in-depth knowledge and understanding of Jackrabbit/Oak authorization concepts. Doing so might otherwise result in severe security issues and heavily impact overall performance.</p>
+<!-- hidden references --></div></div>
</div>
</div>
</div>
Modified: jackrabbit/site/live/oak/docs/security/authorization/cug.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/authorization/cug.html?rev=1838538&r1=1838537&r2=1838538&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/authorization/cug.html (original)
+++ jackrabbit/site/live/oak/docs/security/authorization/cug.html Tue Aug 21 10:31:37 2018
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 at 2018-08-10
+ | Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2018-04-18
| Rendered using Apache Maven Fluido Skin 1.6
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20180810" />
+ <meta name="Date-Revision-yyyymmdd" content="20180418" />
<meta http-equiv="Content-Language" content="en" />
<title>Jackrabbit Oak – Managing Access with Closed User Groups (CUG)</title>
<link rel="stylesheet" href="../../css/apache-maven-fluido-1.6.min.css" />
@@ -52,7 +52,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Main APIs <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="http://www.day.com/specs/jcr/2.0/index.html" title="JCR API">JCR API</a></li>
- <li><a href="https://jackrabbit.apache.org/jcr/jcr-api.html" title="Jackrabbit API">Jackrabbit API</a></li>
<li><a href="../../oak_api/overview.html" title="Oak API">Oak API</a></li>
</ul>
</li>
@@ -137,7 +136,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2018-08-10<span class="divider">|</span>
+ <li id="publishDate">Last Published: 2018-04-18<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 1.10-SNAPSHOT</li>
</ul>
@@ -156,14 +155,12 @@
<li><a href="../../architecture/nodestate.html" title="The Node State Model"><span class="none"></span>The Node State Model</a> </li>
<li class="nav-header">Main APIs</li>
<li><a href="http://www.day.com/specs/jcr/2.0/index.html" class="externalLink" title="JCR API"><span class="none"></span>JCR API</a> </li>
- <li><a href="https://jackrabbit.apache.org/jcr/jcr-api.html" class="externalLink" title="Jackrabbit API"><span class="none"></span>Jackrabbit API</a> </li>
<li><a href="../../oak_api/overview.html" title="Oak API"><span class="none"></span>Oak API</a> </li>
<li class="nav-header">Features and Plugins</li>
<li><a href="../../nodestore/overview.html" title="Node Storage"><span class="icon-chevron-down"></span>Node Storage</a>
<ul class="nav nav-list">
<li><a href="../../nodestore/documentmk.html" title="Document NodeStore"><span class="icon-chevron-down"></span>Document NodeStore</a>
<ul class="nav nav-list">
- <li><a href="../../nodestore/document/mongo-document-store.html" title="MongoDB DocumentStore"><span class="none"></span>MongoDB DocumentStore</a> </li>
<li><a href="../../nodestore/document/node-bundling.html" title="Node Bundling"><span class="none"></span>Node Bundling</a> </li>
<li><a href="../../nodestore/document/secondary-store.html" title="Secondary Store"><span class="none"></span>Secondary Store</a> </li>
<li><a href="../../nodestore/persistent-cache.html" title="Persistent Cache"><span class="none"></span>Persistent Cache</a> </li>
@@ -242,8 +239,7 @@
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
--->
-<div class="section">
+--><div class="section">
<h2><a name="Managing_Access_with_Closed_User_Groups_CUG"></a>Managing Access with “Closed User Groups” (CUG)</h2>
<div class="section">
<h3><a name="General"></a>General</h3>
@@ -252,27 +248,32 @@
<p>This implies that the CUG-authorization model solely evaluates and enforces read access to regular nodes and properties. Therefore it may only be used as an additional, complementary authorization scheme while the primary module(s) is/are in charge of enforcing the complete set of permissions including read/write access, repository operations and any kind of special permissions like reading and writing access control content. See section <a href="composite.html">Combining Multiple Authorization Models</a> for information aggregating access control management and permission evaluation from different implementations.</p>
<p>By default the <tt>oak-authorization-cug</tt> model is disabled and it requires manual <a href="#configuration">configuration</a> steps in order to plug it into the Oak security setup.</p>
<p>Once deployed this authorization configuration can be used in the following two operation modes:</p>
-<ol style="list-style-type: decimal">
+<ol style="list-style-type: decimal">
+
<li>Evaluation disabled: Access control management is supported and policies may be applied to the repository without taking effect.</li>
+
<li>Evaluation enabled: All policies edited and applied by this module will take effect upon being persisted, i.e. access to items located in a restricted are will be subject to the permission evaluation associated with the authorization model.</li>
</ol>
-<a name="jackrabbit_api"></a>
-### Jackrabbit API
-
+<p><a name="jackrabbit_api"></a></p></div>
+<div class="section">
+<h3><a name="Jackrabbit_API"></a>Jackrabbit API</h3>
<p>The Jackrabbit API defines an extension of the JCR <a class="externalLink" href="http://www.day.com/specs/javax.jcr/javadocs/jcr-2.0/javax/jcr/security/AccessControlPolicy.html">AccessControlPolicy</a> interface intended to grant the ability to perform certain actions to a set of <a class="externalLink" href="http://docs.oracle.com/javase/7/docs/api/java/security/Principal.html">Principal</a>s:</p>
-<ul>
+<ul>
+
<li><tt>PrincipalSetPolicy</tt></li>
</ul>
<p>See <a class="externalLink" href="http://svn.apache.org/repos/asf/jackrabbit/trunk/jackrabbit-api/src/main/java/org/apache/jackrabbit/api/security/authorization/PrincipalSetPolicy.java">Jackrabbit API</a> for details and the methods exposed by the interface.</p>
-<a name="api_extensions"></a>
-### API Extensions
-
+<p><a name="api_extensions"></a></p></div>
+<div class="section">
+<h3><a name="API_Extensions"></a>API Extensions</h3>
<p>The module comes with the following extension in the <tt>org.apache.jackrabbit.oak.spi.security.authorization.cug</tt> package space:</p>
-<ul>
+<ul>
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/cug/CugPolicy.html">CugPolicy</a></li>
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/cug/CugExclude.html">CugExclude</a></li>
</ul>
<div class="section">
@@ -280,28 +281,28 @@
<h5><a name="CugPolicy"></a>CugPolicy</h5>
<p>The <tt>CugPolicy</tt> interface extends the <tt>PrincipalSetPolicy</tt> and <tt>JackrabbitAccessControlPolicy</tt> interfaces provided by Jackrabbit API. It comes with the following set of methods that allow to read and modify the set of <tt>Principal</tt>s that will be allowed to access the restricted area defined by a given policy instance.</p>
-<div>
-<div>
-<pre class="source">CugPolicy extends PrincipalSetPolicy, JackrabbitAccessControlPolicy
-
+<div class="source">
+<div class="source"><pre class="prettyprint">CugPolicy extends PrincipalSetPolicy, JackrabbitAccessControlPolicy
+
Set<Principal> getPrincipals();
boolean addPrincipals(@Nonnull Principal... principals) throws AccessControlException;
boolean removePrincipals(@Nonnull Principal... principals) throws AccessControlException;
-</pre></div></div>
-</div>
+</pre></div></div></div>
<div class="section">
<h5><a name="CugExclude"></a>CugExclude</h5>
<p>The <tt>CugExclude</tt> allows to customize the set of principals excluded from evaluation of the restricted areas. These principals will consequently never be prevented from accessing any of the configured CUGs and read permission evaluation is delegated to any other module present in the setup.</p>
<p>The feature ships with two implementations out of the box:</p>
-<ul>
+<ul>
+
<li><tt>CugExclude.Default</tt>: Default implementation that excludes admin, system and system-user principals. It will be used as fallback if no other implementation is configured.</li>
+
<li><tt>CugExcludeImpl</tt>: OSGi service extending from the default that additionally allows to excluded principals by their names at runtime.</li>
</ul>
-<p>See also section <a href="#pluggability">Pluggability</a> below.</p>
-<a name="details"></a>
-### Implementation Details
-</div></div>
+<p>See also section <a href="#pluggability">Pluggability</a> below. </p>
+<p><a name="details"></a></p></div></div></div>
+<div class="section">
+<h3><a name="Implementation_Details"></a>Implementation Details</h3>
<div class="section">
<h4><a name="Access_Control_Management"></a>Access Control Management</h4>
<p>The access control management part of the CUG authorization models follows the requirements defined by JSR 283 the extensions defined by Jackrabbit API (see section <a href="../accesscontrol.html">Access Control Management</a> with the following characterstics:</p>
@@ -310,7 +311,7 @@
<p>This implemenation of the <tt>JackrabbitAccessControlManager</tt> only supports a subset of privileges, namely <tt>jcr:read</tt>, <tt>rep:readProperties</tt>, <tt>rep:readNodes</tt>.</p></div>
<div class="section">
<h5><a name="Access_Control_Policies"></a>Access Control Policies</h5>
-<p>Only a single type of access control policies (<tt>CugPolicy</tt>) is exposed and accepted by the access control manager. Once effective each CUG policy creates a restricted area starting at the target node and inherited to the complete subtree defined therein.</p>
+<p>Only a single type of access control policies (<tt>CugPolicy</tt>) is exposed and accepted by the access control manager. Once effective each CUG policy creates a restricted area starting at the target node and inherited to the complete subtree defined therein. </p>
<p>Depending on the value of the mandatory <tt>PARAM_CUG_SUPPORTED_PATHS</tt> <a href="#configuration">configuration</a> option creation (and evaluation) of CUG policies can be limited to certain paths within the repository. Within these supported paths CUGs can be nested. Note however, that the principal set defined with a given <tt>CugPolicy</tt> is not inherited to the nested policies applied in the subtree.</p>
<p><i>Note:</i> For performance reasons it is recommended to limited the usage of <tt>CugPolicy</tt>s to a single or a couple of subtrees in the repository.</p></div>
<div class="section">
@@ -320,134 +321,205 @@
<h4><a name="Permission_Evaluation"></a>Permission Evaluation</h4>
<p>As stated above evaluation of the restricted areas requires the <tt>PARAM_CUG_ENABLED</tt> <a href="#configuration">configuration</a> option to be set to <tt>true</tt>. This switch allows to setup restricted areas in a staging enviroment and only let them take effect in the public facing production instance.</p>
<p>If permission evaluation is enabled, the <tt>PermissionProvider</tt> implementation associated with the authorization model will prevent read access to all restricted areas defined by a <tt>CugPolicy</tt>. Only <tt>Principal</tt>s explicitly allowed by the policy itself or the globally configured <tt>CugExclude</tt> will be granted read permissions to the affected items in the subtree.</p>
-<p>For example, applying and persisting a new <tt>CugPolicy</tt> at path <i>/content/restricted/apache_foundation</i>, setting the principal names to <i>apache-members</i> and <i>jackrabbit-pmc</i> will prevent read access to the tree defined by this path for all <tt>Subject</tt>s that doesn’t match any of the two criteria:</p>
-<ul>
+<p>For example, applying and persisting a new <tt>CugPolicy</tt> at path _/content/restricted/apache<i>foundation</i>, setting the principal names to <i>apache-members</i> and <i>jackrabbit-pmc</i> will prevent read access to the tree defined by this path for all <tt>Subject</tt>s that doesn’t match any of the two criteria:</p>
+<ul>
+
<li>the <tt>Subject</tt> contains<tt>Principal</tt> <i>apache-members</i> and|or <i>jackrabbit-pmc</i> (as defined in the <tt>CugPolicy</tt>)</li>
+
<li>the <tt>Subject</tt> contains at least one <tt>Principal</tt> explicitly excluded from CUG evaluation in the configured, global <tt>CugExclude</tt></li>
</ul>
-<p>This further implies that the <tt>PermissionProvider</tt> will only evaluate regular read permissions (i.e. <tt>READ_NODE</tt> and <tt>READ_PROPERTY</tt>). Evaluation of any other <a href="../permission.html#oak_permissions">permissions</a> 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 <i>Combining Multiple Authorization Models</i> for <a href="composite.html#details">details</a>).</p></div></div>
+<p>This further implies that the <tt>PermissionProvider</tt> will only evaluate regular read permissions (i.e. <tt>READ_NODE</tt> and <tt>READ_PROPERTY</tt>). Evaluation of any other <a href="../permission.html#oak_permissions">permissions</a> 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 <i>Combining Multiple Authorization Models</i> for <a href="composite.html#details">details</a>). </p></div></div>
<div class="section">
<h3><a name="Representation_in_the_Repository"></a>Representation in the Repository</h3>
<p>CUG policies defined by this module in a dedicate node name <tt>rep:cugPolicy</tt> of type <tt>rep:CugPolicy</tt>. This node is defined by a dedicate mixin type <tt>rep:CugMixin</tt> (similar to <tt>rep:AccessControllable</tt>) and has a single mandatory, protected property which stores the name of principals that are granted read access in the restricted area:</p>
-<div>
-<div>
-<pre class="source">[rep:CugMixin]
+<div class="source">
+<div class="source"><pre class="prettyprint">[rep:CugMixin]
mixin
+ rep:cugPolicy (rep:CugPolicy) protected IGNORE
-
+
[rep:CugPolicy] > rep:Policy
- rep:principalNames (STRING) multiple protected mandatory IGNORE
</pre></div></div>
-
-<p><i>Note:</i> the multivalued <tt>rep:principalNames</tt> property reflects the fact that CUGs are intended to be used for small principal sets, preferably <tt>java.security.acl.Group</tt> principals.</p>
-<a name="validation"></a>
-### Validation
-
+<p><i>Note:</i> the multivalued <tt>rep:principalNames</tt> property reflects the fact that CUGs are intended to be used for small principal sets, preferably <tt>java.security.acl.Group</tt> principals. </p>
+<p><a name="validation"></a></p></div>
+<div class="section">
+<h3><a name="Validation"></a>Validation</h3>
<p>The consistency of this content structure both on creation and modification is asserted by a dedicated <tt>CugValidatorProvider</tt>. The corresponding error are all of type <tt>AccessControl</tt> with the following codes:</p>
-<table border="0" class="table table-striped">
-<thead>
+<table border="0" class="table table-striped">
+ <thead>
+
<tr class="a">
-<th> Code </th>
-<th> Message </th></tr>
-</thead><tbody>
-
+
+<th>Code </th>
+
+<th>Message </th>
+ </tr>
+ </thead>
+ <tbody>
+
<tr class="b">
-<td> 0020 </td>
-<td> Attempt to change primary type of/to cug policy </td></tr>
+
+<td>0020 </td>
+
+<td>Attempt to change primary type of/to cug policy </td>
+ </tr>
+
<tr class="a">
-<td> 0021 </td>
-<td> Wrong primary type of ‘rep:cugPolicy’ node </td></tr>
+
+<td>0021 </td>
+
+<td>Wrong primary type of ‘rep:cugPolicy’ node </td>
+ </tr>
+
<tr class="b">
-<td> 0022 </td>
-<td> Access controlled not not of mixin ‘rep:CugMixin’ </td></tr>
+
+<td>0022 </td>
+
+<td>Access controlled not not of mixin ‘rep:CugMixin’ </td>
+ </tr>
+
<tr class="a">
-<td> 0023 </td>
-<td> Wrong name of node with primary type ‘rep:CugPolicy’ </td></tr>
-</tbody>
+
+<td>0023 </td>
+
+<td>Wrong name of node with primary type ‘rep:CugPolicy’ </td>
+ </tr>
+ </tbody>
</table>
-<a name="configuration"></a>
-### Configuration
-
+<p><a name="configuration"></a></p></div>
+<div class="section">
+<h3><a name="Configuration"></a>Configuration</h3>
<p>The CUG authorization extension is an optional feature that requires mandatory configuration: this includes defining the supported paths and enabling the permission evaluation.</p>
<div class="section">
<h4><a name="Configuration_Parameters"></a>Configuration Parameters</h4>
<p>The <tt>org.apache.jackrabbit.oak.spi.security.authorization.cug.impl.CugConfiguration</tt> supports the following configuration parameters:</p>
-<table border="0" class="table table-striped">
-<thead>
+<table border="0" class="table table-striped">
+ <thead>
+
<tr class="a">
-<th> Parameter </th>
-<th> Type </th>
-<th> Default </th>
-<th> Description </th></tr>
-</thead><tbody>
-
+
+<th>Parameter </th>
+
+<th>Type </th>
+
+<th>Default </th>
+
+<th>Description </th>
+ </tr>
+ </thead>
+ <tbody>
+
<tr class="b">
-<td> <tt>PARAM_CUG_ENABLED</tt> </td>
-<td> boolean </td>
-<td> false </td>
-<td> Flag to enable evaluation of CUG policies upon read-access. </td></tr>
+
+<td><tt>PARAM_CUG_ENABLED</tt> </td>
+
+<td>boolean </td>
+
+<td>false </td>
+
+<td>Flag to enable evaluation of CUG policies upon read-access. </td>
+ </tr>
+
<tr class="a">
-<td> <tt>PARAM_CUG_SUPPORTED_PATHS</tt> </td>
-<td> Set<String> </td>
-<td> - </td>
-<td> Paths under which CUGs can be created and will be evaluated. </td></tr>
+
+<td><tt>PARAM_CUG_SUPPORTED_PATHS</tt> </td>
+
+<td>Set<String> </td>
+
+<td>- </td>
+
+<td>Paths under which CUGs can be created and will be evaluated. </td>
+ </tr>
+
<tr class="b">
-<td> <tt>PARAM_RANKING</tt> </td>
-<td> int </td>
-<td> 200 </td>
-<td> Ranking within the composite authorization setup. </td></tr>
+
+<td><tt>PARAM_RANKING</tt> </td>
+
+<td>int </td>
+
+<td>200 </td>
+
+<td>Ranking within the composite authorization setup. </td>
+ </tr>
+
<tr class="a">
+
+<td> </td>
+
<td> </td>
+
<td> </td>
+
<td> </td>
-<td> </td></tr>
-</tbody>
+ </tr>
+ </tbody>
</table>
<p><i>Note:</i> 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.</p></div>
<div class="section">
<h4><a name="Excluding_Principals"></a>Excluding Principals</h4>
<p>The CUG authorization setup can be further customized by configuring the <tt>CugExcludeImpl</tt> service with allows to list additional principals that need to be excluded from the evaluation of restricted areas:</p>
-<table border="0" class="table table-striped">
-<thead>
+<table border="0" class="table table-striped">
+ <thead>
+
<tr class="a">
-<th> Parameter </th>
-<th> Type </th>
-<th> Default </th>
-<th> Description </th></tr>
-</thead><tbody>
-
+
+<th>Parameter </th>
+
+<th>Type </th>
+
+<th>Default </th>
+
+<th>Description </th>
+ </tr>
+ </thead>
+ <tbody>
+
<tr class="b">
-<td> <tt>principalNames</tt> </td>
-<td> Set<String> </td>
-<td> - </td>
-<td> Name of principals that are always excluded from CUG evaluation. </td></tr>
+
+<td><tt>principalNames</tt> </td>
+
+<td>Set<String> </td>
+
+<td>- </td>
+
+<td>Name of principals that are always excluded from CUG evaluation. </td>
+ </tr>
+
<tr class="a">
+
+<td> </td>
+
<td> </td>
+
<td> </td>
+
<td> </td>
-<td> </td></tr>
-</tbody>
+ </tr>
+ </tbody>
</table>
<p><i>Note:</i> This implementation extends the <a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/cug/CugExclude.Default.html">default</a> exclusion list. Alternatively, it is possible to plug a custom <tt>CugExclude</tt> implementation matching specific needs (see <a href="#pluggability">below</a>).</p>
-<a name="pluggability"></a>
-### Pluggability
-
+<p><a name="pluggability"></a></p></div></div>
+<div class="section">
+<h3><a name="Pluggability"></a>Pluggability</h3>
<p>The following section describes how to deploy the CUG authorization model into an Oak repository and how to customize the <tt>CugExclude</tt> extension point.</p>
-<p><i>Note:</i> the reverse steps can be used to completely disable the CUG authorization model in case it is not needed for a given repository installation but shipped by a vendor such as e.g. Adobe AEM 6.3.</p></div>
+<p><i>Note:</i> the reverse steps can be used to completely disable the CUG authorization model in case it is not needed for a given repository installation but shipped by a vendor such as e.g. Adobe AEM 6.3.</p>
<div class="section">
<h4><a name="Deploy_CugConfiguration"></a>Deploy CugConfiguration</h4>
<div class="section">
<h5><a name="OSGi_Setup"></a>OSGi Setup</h5>
<p>The following steps are required in order to deploy the CUG authorization model in an OSGi-base Oak repository:</p>
-<ol style="list-style-type: decimal">
+<ol style="list-style-type: decimal">
+
<li>Deploy the <tt>oak-authorization-cug</tt> bundle</li>
+
<li>Activate the <tt>CugConfiguration</tt> <i>(“Apache Jackrabbit Oak CUG Configuration”)</i> by providing the desired component configuration (<i>ConfigurationPolicy.REQUIRE</i>)</li>
+
<li>Find the <tt>SecurityProviderRegistration</tt> <i>(“Apache Jackrabbit Oak SecurityProvider”)</i> configuration and enter <i><tt>org.apache.jackrabbit.oak.spi.security.authorization.cug.impl.CugConfiguration</tt></i> as additional value to the <tt>requiredServicePids</tt> property.</li>
</ol>
<p>The third step will enforce the recreation of the <tt>SecurityProvider</tt> and hence trigger the <tt>RepositoryInitializer</tt> provided by the CUG authorization module.</p></div>
@@ -455,29 +527,28 @@
<h5><a name="Non-OSGi_Setup"></a>Non-OSGi Setup</h5>
<p>The following example shows a simplified setup that contains the <tt>CugConfiguration</tt> as additional authorization model (second position in the aggregation). See also unit tests for an alternative approach.</p>
-<div>
-<div>
-<pre class="source"> // setup CugConfiguration
+<div class="source">
+<div class="source"><pre class="prettyprint"> // 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())
@@ -485,25 +556,27 @@
.with(securityProvider);
withEditors(oak);
ContentRepository contentRepository = oak.createContentRepository();
-</pre></div></div>
-</div></div>
+</pre></div></div></div></div>
<div class="section">
<h4><a name="Customize_CugExclude"></a>Customize CugExclude</h4>
<p>The following steps are required in order to customize the <tt>CugExclude</tt> implementation in a OSGi-based repository setup. Ultimately the implementation needs to be referenced in the <tt>org.apache.jackrabbit.oak.spi.security.authorization.cug.impl.CugConfiguration</tt>.</p>
-<ol style="list-style-type: decimal">
+<ol style="list-style-type: decimal">
+
<li>implement <tt>CugExclude</tt> interface according to you needs,</li>
+
<li>make your implementation an OSGi service</li>
+
<li>deploy the bundle containing your implementation in the OSGi container and activate the service.</li>
+
<li>make sure the default CUGExclude service is properly replaced by the custom implementation.</li>
</ol>
<div class="section">
<div class="section">
<h6><a name="Example"></a>Example</h6>
-<div>
-<div>
-<pre class="source">@Component()
+<div class="source">
+<div class="source"><pre class="prettyprint">@Component()
@Service(CugExclude.class)
public class MyCugExclude implements CugExclude {
Modified: jackrabbit/site/live/oak/docs/security/authorization/restriction.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/authorization/restriction.html?rev=1838538&r1=1838537&r2=1838538&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/authorization/restriction.html (original)
+++ jackrabbit/site/live/oak/docs/security/authorization/restriction.html Tue Aug 21 10:31:37 2018
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 at 2018-08-10
+ | Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2018-04-18
| Rendered using Apache Maven Fluido Skin 1.6
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20180810" />
+ <meta name="Date-Revision-yyyymmdd" content="20180418" />
<meta http-equiv="Content-Language" content="en" />
<title>Jackrabbit Oak – Restriction Management</title>
<link rel="stylesheet" href="../../css/apache-maven-fluido-1.6.min.css" />
@@ -52,7 +52,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Main APIs <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="http://www.day.com/specs/jcr/2.0/index.html" title="JCR API">JCR API</a></li>
- <li><a href="https://jackrabbit.apache.org/jcr/jcr-api.html" title="Jackrabbit API">Jackrabbit API</a></li>
<li><a href="../../oak_api/overview.html" title="Oak API">Oak API</a></li>
</ul>
</li>
@@ -137,7 +136,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2018-08-10<span class="divider">|</span>
+ <li id="publishDate">Last Published: 2018-04-18<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 1.10-SNAPSHOT</li>
</ul>
@@ -156,14 +155,12 @@
<li><a href="../../architecture/nodestate.html" title="The Node State Model"><span class="none"></span>The Node State Model</a> </li>
<li class="nav-header">Main APIs</li>
<li><a href="http://www.day.com/specs/jcr/2.0/index.html" class="externalLink" title="JCR API"><span class="none"></span>JCR API</a> </li>
- <li><a href="https://jackrabbit.apache.org/jcr/jcr-api.html" class="externalLink" title="Jackrabbit API"><span class="none"></span>Jackrabbit API</a> </li>
<li><a href="../../oak_api/overview.html" title="Oak API"><span class="none"></span>Oak API</a> </li>
<li class="nav-header">Features and Plugins</li>
<li><a href="../../nodestore/overview.html" title="Node Storage"><span class="icon-chevron-down"></span>Node Storage</a>
<ul class="nav nav-list">
<li><a href="../../nodestore/documentmk.html" title="Document NodeStore"><span class="icon-chevron-down"></span>Document NodeStore</a>
<ul class="nav nav-list">
- <li><a href="../../nodestore/document/mongo-document-store.html" title="MongoDB DocumentStore"><span class="none"></span>MongoDB DocumentStore</a> </li>
<li><a href="../../nodestore/document/node-bundling.html" title="Node Bundling"><span class="none"></span>Node Bundling</a> </li>
<li><a href="../../nodestore/document/secondary-store.html" title="Secondary Store"><span class="none"></span>Secondary Store</a> </li>
<li><a href="../../nodestore/persistent-cache.html" title="Persistent Cache"><span class="none"></span>Persistent Cache</a> </li>
@@ -242,106 +239,136 @@
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
- -->
-<div class="section">
+ --><div class="section">
<h2><a name="Restriction_Management"></a>Restriction Management</h2>
<div class="section">
<h3><a name="Overview"></a>Overview</h3>
<p>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.</p>
<p>Quoting from JSR 283 section 16.6.2 Permissions:</p>
-<blockquote>
+<blockquote>
<p>[…] 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.</p>
</blockquote>
<p>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.</p>
<p>Existing and potential examples of restrictions limiting the effect of a given access control entry during permission evaluation include:</p>
-<ul>
+<ul>
+
<li>set of node types</li>
+
<li>set of namespaces</li>
+
<li>name/path pattern</li>
+
<li>dedicated time frame</li>
+
<li>size of a value</li>
</ul>
<p>The set of built-in restrictions present with Jackrabbit 2.x has extended as of Oak 1.0 along with some extensions of the Jackrabbit API. This covers the public facing usage of restrictions i.e. access control management.</p>
<p>In addition Oak provides it’s own restriction API that adds support for internal validation and permission evaluation.</p>
-<a name="jackrabbit_api"></a>
-### Jackrabbit API
-
+<p><a name="jackrabbit_api"></a></p></div>
+<div class="section">
+<h3><a name="Jackrabbit_API"></a>Jackrabbit API</h3>
<p>The Jackrabbit API add the following extensions to JCR access control management to read and create entries with restrictions:</p>
-<ul>
-
-<li>
-<p><tt>JackrabbitAccessControlList</tt></p>
<ul>
-
+
+<li><tt>JackrabbitAccessControlList</tt>
+
+<ul>
+
<li><tt>getRestrictionNames()</tt> : returns the JCR names of the supported restrictions.</li>
+
<li><tt>getRestrictionType(String restrictionName)</tt> : returns property type of a given restriction.</li>
+
<li><tt>addEntry(Principal, Privilege[], boolean, Map<String, Value>)</tt>: the map contain the restrictions.</li>
+
<li><tt>addEntry(Principal, Privilege[], boolean, Map<String, Value>, Map<String, Value[]>)</tt>: allows to specify both single and multivalue restrictions (since Oak 1.0, Jackrabbit API 2.8)</li>
+ </ul></li>
</ul>
-</li>
-<li>
-<p><tt>JackrabbitAccessControlEntry</tt></p>
<ul>
-
+
+<li><tt>JackrabbitAccessControlEntry</tt>
+
+<ul>
+
<li><tt>getRestrictionNames()</tt>: returns the JCR names of the restrictions present with this entry.</li>
+
<li><tt>getRestriction(String restrictionName)</tt>: returns the restriction as JCR value.</li>
+
<li><tt>getRestrictions(String restrictionName)</tt>: returns the restriction as array of JCR values (since Oak 1.0, Jackrabbit API 2.8).</li>
+ </ul></li>
</ul>
-</li>
-</ul>
-<a name="api_extensions"></a>
-### Oak Restriction API
-
+<p><a name="api_extensions"></a></p></div>
+<div class="section">
+<h3><a name="Oak_Restriction_API"></a>Oak Restriction API</h3>
<p>The following public interfaces are provided by Oak in the package <tt>org.apache.jackrabbit.oak.spi.security.authorization.restriction</tt> and provide support for pluggable restrictions both for access control management and the repository internal permission evaluation:</p>
-<ul>
+<ul>
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/restriction/RestrictionProvider.html">RestrictionProvider</a>: interface to obtain restriction information needed for access control and permission management</li>
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/restriction/Restriction.html">Restriction</a>: the restriction object as created using Jackrabbit access control API</li>
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/restriction/RestrictionDefinition.html">RestrictionDefinition</a>: the static definition of a supported restriction</li>
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/restriction/RestrictionPattern.html">RestrictionPattern</a>: the processed restriction ready for permission evaluation</li>
</ul>
-<a name="default_implementation"></a>
-### Default Implementation
-
+<p><a name="default_implementation"></a></p></div>
+<div class="section">
+<h3><a name="Default_Implementation"></a>Default Implementation</h3>
<p>Oak 1.0 provides the following base implementations:</p>
-<ul>
+<ul>
+
<li><tt>AbstractRestrictionProvider</tt>: abstract base implementation of the provider interface.</li>
+
<li><tt>RestrictionDefinitionImpl</tt>: default implementation of the <tt>RestrictionDefinition</tt> interface.</li>
+
<li><tt>RestrictionImpl</tt>: default implementation of the <tt>Restriction</tt> interface.</li>
+
<li><tt>CompositeRestrictionProvider</tt>: Allows to aggregate multiple provider implementations (see <a href="#pluggability">Pluggability</a> below).</li>
+
<li><tt>CompositePattern</tt>: Allows to aggregate multiple restriction patterns.</li>
</ul>
<div class="section">
<h4><a name="Changes_wrt_Jackrabbit_2.x"></a>Changes wrt Jackrabbit 2.x</h4>
<p>Apart from the fact that the internal Jackrabbit extension has been replaced by a public API, the restriction implementation in Oak differs from Jackrabbit 2.x as follows:</p>
-<ul>
+<ul>
+
<li>Separate restriction management API (see below) on the OAK level that allows to ease plugging custom restrictions.</li>
+
<li>Changed node type definition for storing restrictions in the default implementation.
+
<ul>
-
+
<li>as of OAK restrictions are collected underneath a separate child node “rep:restrictions”</li>
+
<li>backwards compatible behavior for restrictions stored underneath the ACE node directly</li>
-</ul>
-</li>
+ </ul></li>
+
<li>Support for multi-valued restrictions (see <a class="externalLink" href="https://issues.apache.org/jira/browse/JCR-3637">JCR-3637</a>, <a class="externalLink" href="https://issues.apache.org/jira/browse/JCR-3641">JCR-3641</a>)</li>
+
<li>Validation of the restrictions is delegated to a dedicated commit hook</li>
+
<li>Restriction <tt>rep:glob</tt> limits the number of wildcard characters to 20</li>
+
<li>New restrictions <tt>rep:ntNames</tt>, <tt>rep:prefixes</tt> and <tt>rep:itemNames</tt></li>
</ul></div>
<div class="section">
<h4><a name="Built-in_Restrictions"></a>Built-in Restrictions</h4>
<p>The default implementations of the <tt>Restriction</tt> interface are present with Oak 1.0 access control management:</p>
-<ul>
+<ul>
+
<li><tt>rep:glob</tt>: single name, path or path pattern with ‘*’ wildcard(s).</li>
+
<li><tt>rep:ntNames</tt>: multivalued restriction to limit the affected ACE to nodes of the specified primary node type(s) (no nt inheritence, since Oak 1.0)</li>
+
<li><tt>rep:prefixes</tt>: multivalued restriction to limit the effect to item names that match the specified namespace prefixes (session level remapping not respected, since Oak 1.0)</li>
+
<li><tt>rep:itemNames</tt>: multivalued restriction for property or node names (since Oak 1.3.8)</li>
</ul>
<div class="section">
@@ -349,66 +376,125 @@
<div class="section">
<h6><a name="Using_rep:glob"></a>Using rep:glob</h6>
<p>For a nodePath <tt>/foo</tt> the following results can be expected for the different values of <tt>rep:glob</tt>.</p>
-<table border="0" class="table table-striped">
-<thead>
+<table border="0" class="table table-striped">
+ <thead>
+
<tr class="a">
-<th> rep:glob </th>
-<th> Result </th></tr>
-</thead><tbody>
-
+
+<th>rep:glob </th>
+
+<th>Result </th>
+ </tr>
+ </thead>
+ <tbody>
+
<tr class="b">
-<td> "" </td>
-<td> matches node /foo only </td></tr>
+
+<td>"" </td>
+
+<td>matches node /foo only </td>
+ </tr>
+
<tr class="a">
-<td> /cat </td>
-<td> the node /foo/cat and all it’s children </td></tr>
+
+<td>/cat </td>
+
+<td>the node /foo/cat and all it’s children </td>
+ </tr>
+
<tr class="b">
-<td> /cat/ </td>
-<td> the descendants of the node /foo/cat </td></tr>
+
+<td>/cat/ </td>
+
+<td>the descendants of the node /foo/cat </td>
+ </tr>
+
<tr class="a">
-<td> cat </td>
-<td> the node /foocat and all it’s children </td></tr>
+
+<td>cat </td>
+
+<td>the node /foocat and all it’s children </td>
+ </tr>
+
<tr class="b">
-<td> cat/ </td>
-<td> all descendants of the node /foocat </td></tr>
+
+<td>cat/ </td>
+
+<td>all descendants of the node /foocat </td>
+ </tr>
+
<tr class="a">
-<td> * </td>
-<td> foo, siblings of foo and their descendants </td></tr>
+
+<td>* </td>
+
+<td>foo, siblings of foo and their descendants </td>
+ </tr>
+
<tr class="b">
-<td> /*cat </td>
-<td> all children of /foo whose path ends with ‘cat’ </td></tr>
+
+<td>/*cat </td>
+
+<td>all children of /foo whose path ends with ‘cat’ </td>
+ </tr>
+
<tr class="a">
-<td> /*/cat </td>
-<td> all non-direct descendants of /foo named ‘cat’ </td></tr>
+
+<td>/*/cat </td>
+
+<td>all non-direct descendants of /foo named ‘cat’ </td>
+ </tr>
+
<tr class="b">
-<td> /cat* </td>
-<td> all descendant path of /foo that have the direct foo-descendant segment starting with ‘cat’ </td></tr>
+
+<td>/cat* </td>
+
+<td>all descendant path of /foo that have the direct foo-descendant segment starting with ‘cat’ </td>
+ </tr>
+
<tr class="a">
-<td> *cat </td>
-<td> all siblings and descendants of foo that have a name ending with ‘cat’ </td></tr>
+
+<td>*cat </td>
+
+<td>all siblings and descendants of foo that have a name ending with ‘cat’ </td>
+ </tr>
+
<tr class="b">
-<td> */cat </td>
-<td> all descendants of /foo and foo’s siblings that have a name segment ‘cat’ </td></tr>
+
+<td>*/cat </td>
+
+<td>all descendants of /foo and foo’s siblings that have a name segment ‘cat’ </td>
+ </tr>
+
<tr class="a">
-<td> cat/* </td>
-<td> all descendants of ‘/foocat’ </td></tr>
+
+<td>cat/* </td>
+
+<td>all descendants of ‘/foocat’ </td>
+ </tr>
+
<tr class="b">
-<td> /cat/* </td>
-<td> all descendants of ‘/foo/cat’ </td></tr>
+
+<td>/cat/* </td>
+
+<td>all descendants of ‘/foo/cat’ </td>
+ </tr>
+
<tr class="a">
-<td> *cat/* </td>
-<td> all descendants of /foo that have an intermediate segment ending with ‘cat’ </td></tr>
-</tbody>
+
+<td>*cat/* </td>
+
+<td>all descendants of /foo that have an intermediate segment ending with ‘cat’ </td>
+ </tr>
+ </tbody>
</table>
-<a name="representation"></a>
-### Representation in the Repository
-
+<p><a name="representation"></a></p></div></div></div></div>
+<div class="section">
+<h3><a name="Representation_in_the_Repository"></a>Representation in the Repository</h3>
<p>All restrictions defined by default in a Oak repository are stored as properties in a dedicated <tt>rep:restriction</tt> 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:</p>
-<div>
-<div>
-<pre class="source">[rep:ACE]
+<div class="source">
+<div class="source"><pre class="prettyprint">[rep:ACE]
- rep:principalName (STRING) protected mandatory
- rep:privileges (NAME) protected mandatory multiple
- rep:nodePath (PATH) protected /* deprecated in favor of restrictions */
@@ -423,26 +509,28 @@
- * (UNDEFINED) protected
- * (UNDEFINED) protected multiple
</pre></div></div>
-<a name="pluggability"></a>
-### Pluggability
-
+<p><a name="pluggability"></a></p></div>
+<div class="section">
+<h3><a name="Pluggability"></a>Pluggability</h3>
<p>The default security setup as present with Oak 1.0 is able to provide custom <tt>RestrictionProvider</tt> implementations and will automatically combine the different implementations using the <tt>CompositeRestrictionProvider</tt>.</p>
<p>In an OSGi setup the following steps are required in order to add a action provider implementation:</p>
-<ul>
+<ul>
+
<li>implement <tt>RestrictionProvider</tt> interface exposing your custom restriction(s).</li>
+
<li>make the provider implementation an OSGi service and make it available to the Oak repository.</li>
</ul>
-<p>Please make sure to consider the following recommendations when implementing a custom <tt>RestrictionProvider</tt>: - restrictions are part of the overall permission evaluation and thus may heavily impact overall read/write performance - the hashCode generation of the base implementation (<tt>RestrictionImpl.hashCode</tt>) relies on <tt>PropertyStateValue.hashCode</tt>, which includes the internal String representation, which is not optimal for binaries (see also <a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-5784">OAK-5784</a>)</p></div></div>
+<p>Please make sure to consider the following recommendations when implementing a custom <tt>RestrictionProvider</tt>: - restrictions are part of the overall permission evaluation and thus may heavily impact overall read/write performance - the hashCode generation of the base implementation (<tt>RestrictionImpl.hashCode</tt>) relies on <tt>PropertyStateValue.hashCode</tt>, which includes the internal String representation, which is not optimal for binaries (see also <a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-5784">OAK-5784</a>)</p>
+<div class="section">
<div class="section">
<h5><a name="Examples"></a>Examples</h5>
<div class="section">
<h6><a name="Example_RestrictionProvider"></a>Example RestrictionProvider</h6>
<p>Simple example of a <tt>RestrictionProvider</tt> that defines a single time-based <tt>Restriction</tt>, which is expected to have 2 values defining a start and end date, which can then be used to allow or deny access within the given time frame.</p>
-<div>
-<div>
-<pre class="source">@Component
+<div class="source">
+<div class="source"><pre class="prettyprint">@Component
@Service(RestrictionProvider.class)
public class MyRestrictionProvider extends AbstractRestrictionProvider {
@@ -484,15 +572,13 @@ public class MyRestrictionProvider exten
// TODO: implementing 'validateRestrictions(String oakPath, Tree aceTree)' would allow to make sure the property contains 2 date values.
}
-</pre></div></div>
-</div>
+</pre></div></div></div>
<div class="section">
<h6><a name="Example_RestrictionPattern"></a>Example RestrictionPattern</h6>
<p>The time-based <tt>RestrictionPattern</tt> used by the example provider above.</p>
-<div>
-<div>
-<pre class="source">class DatePattern implements RestrictionPattern {
+<div class="source">
+<div class="source"><pre class="prettyprint">class DatePattern implements RestrictionPattern {
private final Date start;
private final Date end;
@@ -529,14 +615,12 @@ public class MyRestrictionProvider exten
return d.after(start) && d.before(end);
}
};
-</pre></div></div>
-</div>
+</pre></div></div></div>
<div class="section">
<h6><a name="Example_Non-OSGI_Setup"></a>Example Non-OSGI Setup</h6>
-<div>
-<div>
-<pre class="source">RestrictionProvider rProvider = CompositeRestrictionProvider.newInstance(new MyRestrictionProvider(), ...);
+<div class="source">
+<div class="source"><pre class="prettyprint">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();