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/30 11:48:46 UTC
svn commit: r1839663 [16/22] - in /jackrabbit/site/live/oak/docs: ./
architecture/ coldstandby/ features/ nodestore/ nodestore/document/
nodestore/segment/ oak-mongo-js/ oak_api/ plugins/ query/ security/
security/accesscontrol/ security/authentication...
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=1839663&r1=1839662&r2=1839663&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/authorization/cug.html (original)
+++ jackrabbit/site/live/oak/docs/security/authorization/cug.html Thu Aug 30 11:48:45 2018
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 at 2018-08-29
+ | 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="20180829" />
+ <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>
@@ -67,12 +66,7 @@
<li><a href="../../nodestore/compositens.html" title="Composite NodeStore">Composite NodeStore</a></li>
</ul>
</li>
- <li class="dropdown-submenu">
-<a href="../../plugins/blobstore.html" title="Blob Storage">Blob Storage</a>
- <ul class="dropdown-menu">
- <li><a href="../../features/direct-binary-access.html" title="Direct Binary Access">Direct Binary Access</a></li>
- </ul>
- </li>
+ <li><a href="../../plugins/blobstore.html" title="Blob Storage">Blob Storage</a></li>
<li class="dropdown-submenu">
<a href="../../query/query.html" title="Query">Query</a>
<ul class="dropdown-menu">
@@ -142,7 +136,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2018-08-29<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>
@@ -161,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>
@@ -179,11 +171,7 @@
<li><a href="../../nodestore/compositens.html" title="Composite NodeStore"><span class="none"></span>Composite NodeStore</a> </li>
</ul>
</li>
- <li><a href="../../plugins/blobstore.html" title="Blob Storage"><span class="icon-chevron-down"></span>Blob Storage</a>
- <ul class="nav nav-list">
- <li><a href="../../features/direct-binary-access.html" title="Direct Binary Access"><span class="none"></span>Direct Binary Access</a> </li>
- </ul>
- </li>
+ <li><a href="../../plugins/blobstore.html" title="Blob Storage"><span class="none"></span>Blob Storage</a> </li>
<li><a href="../../query/query.html" title="Query"><span class="icon-chevron-down"></span>Query</a>
<ul class="nav nav-list">
<li><a href="../../query/query-engine.html" title="Query Engine"><span class="none"></span>Query Engine</a> </li>
@@ -251,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>
@@ -261,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">
@@ -289,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>
@@ -319,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">
@@ -329,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>
@@ -464,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())
@@ -494,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=1839663&r1=1839662&r2=1839663&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/authorization/restriction.html (original)
+++ jackrabbit/site/live/oak/docs/security/authorization/restriction.html Thu Aug 30 11:48:45 2018
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 at 2018-08-29
+ | 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="20180829" />
+ <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>
@@ -67,12 +66,7 @@
<li><a href="../../nodestore/compositens.html" title="Composite NodeStore">Composite NodeStore</a></li>
</ul>
</li>
- <li class="dropdown-submenu">
-<a href="../../plugins/blobstore.html" title="Blob Storage">Blob Storage</a>
- <ul class="dropdown-menu">
- <li><a href="../../features/direct-binary-access.html" title="Direct Binary Access">Direct Binary Access</a></li>
- </ul>
- </li>
+ <li><a href="../../plugins/blobstore.html" title="Blob Storage">Blob Storage</a></li>
<li class="dropdown-submenu">
<a href="../../query/query.html" title="Query">Query</a>
<ul class="dropdown-menu">
@@ -142,7 +136,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2018-08-29<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>
@@ -161,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>
@@ -179,11 +171,7 @@
<li><a href="../../nodestore/compositens.html" title="Composite NodeStore"><span class="none"></span>Composite NodeStore</a> </li>
</ul>
</li>
- <li><a href="../../plugins/blobstore.html" title="Blob Storage"><span class="icon-chevron-down"></span>Blob Storage</a>
- <ul class="nav nav-list">
- <li><a href="../../features/direct-binary-access.html" title="Direct Binary Access"><span class="none"></span>Direct Binary Access</a> </li>
- </ul>
- </li>
+ <li><a href="../../plugins/blobstore.html" title="Blob Storage"><span class="none"></span>Blob Storage</a> </li>
<li><a href="../../query/query.html" title="Query"><span class="icon-chevron-down"></span>Query</a>
<ul class="nav nav-list">
<li><a href="../../query/query-engine.html" title="Query Engine"><span class="none"></span>Query Engine</a> </li>
@@ -251,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">
@@ -358,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 */
@@ -432,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 {
@@ -493,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;
@@ -538,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();
Modified: jackrabbit/site/live/oak/docs/security/introduction.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/introduction.html?rev=1839663&r1=1839662&r2=1839663&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/introduction.html (original)
+++ jackrabbit/site/live/oak/docs/security/introduction.html Thu Aug 30 11:48:45 2018
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 at 2018-08-29
+ | 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="20180829" />
+ <meta name="Date-Revision-yyyymmdd" content="20180418" />
<meta http-equiv="Content-Language" content="en" />
<title>Jackrabbit Oak – Introduction to Oak Security</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>
@@ -67,12 +66,7 @@
<li><a href="../nodestore/compositens.html" title="Composite NodeStore">Composite NodeStore</a></li>
</ul>
</li>
- <li class="dropdown-submenu">
-<a href="../plugins/blobstore.html" title="Blob Storage">Blob Storage</a>
- <ul class="dropdown-menu">
- <li><a href="../features/direct-binary-access.html" title="Direct Binary Access">Direct Binary Access</a></li>
- </ul>
- </li>
+ <li><a href="../plugins/blobstore.html" title="Blob Storage">Blob Storage</a></li>
<li class="dropdown-submenu">
<a href="../query/query.html" title="Query">Query</a>
<ul class="dropdown-menu">
@@ -142,7 +136,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2018-08-29<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>
@@ -161,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>
@@ -179,11 +171,7 @@
<li><a href="../nodestore/compositens.html" title="Composite NodeStore"><span class="none"></span>Composite NodeStore</a> </li>
</ul>
</li>
- <li><a href="../plugins/blobstore.html" title="Blob Storage"><span class="icon-chevron-down"></span>Blob Storage</a>
- <ul class="nav nav-list">
- <li><a href="../features/direct-binary-access.html" title="Direct Binary Access"><span class="none"></span>Direct Binary Access</a> </li>
- </ul>
- </li>
+ <li><a href="../plugins/blobstore.html" title="Blob Storage"><span class="none"></span>Blob Storage</a> </li>
<li><a href="../query/query.html" title="Query"><span class="icon-chevron-down"></span>Query</a>
<ul class="nav nav-list">
<li><a href="../query/query-engine.html" title="Query Engine"><span class="none"></span>Query Engine</a> </li>
@@ -251,57 +239,69 @@
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="Introduction_to_Oak_Security"></a>Introduction to Oak Security</h2>
<div class="section">
<h3><a name="General"></a>General</h3>
-<p>The main entry point to Oak security is the <tt>SecurityProvider</tt>, which is registered to the Oak repository upon creation. The provider is in charge of collecting and exposing all security related modules present in a given Oak repository.</p>
+<p>The main entry point to Oak security is the <tt>SecurityProvider</tt>, which is registered to the Oak repository upon creation. The provider is in charge of collecting and exposing all security related modules present in a given Oak repository. </p>
<p>Each security module comes with one or multiple <tt>SecurityConfiguration</tt>(s) that are registered with the provider, identified (and possibly aggregated) by their name.</p></div>
<div class="section">
<h3><a name="Modules"></a>Modules</h3>
<p>Currently Oak comes with the following built-in security modules, each defined by a dedicated sub-interfaces of <a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/SecurityConfiguration.html">SecurityConfiguration</a>:</p>
-<ul>
+<ul>
+
<li>Authentication
+
<ul>
-
+
<li><a href="authentication.html">Authentication</a> s.str.</li>
+
<li><a href="authentication/tokenmanagement.html">Token Authentication and Token Management</a></li>
-</ul>
-</li>
+ </ul></li>
+
<li>Authorization
+
<ul>
-
+
<li><a href="authorization.html">Authorization</a> s.str. including <a href="accesscontrol.html">Access Control Management</a> and <a href="permission.html">Permission Evaluation</a></li>
+
<li><a href="privilege.html">Privilege Management</a></li>
-</ul>
-</li>
+ </ul></li>
+
<li><a href="principal.html">Principal Management</a></li>
+
<li><a href="user.html">User Management</a></li>
</ul>
-<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 package <tt>org.apache.jackrabbit.oak.spi.security</tt> defines the following interfaces and base implementations:</p>
-<ul>
+<ul>
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/SecurityProvider.html">SecurityProvider</a>: Main entry point for Oak security.
+
<ul>
-
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/OpenSecurityProvider.html">OpenSecurityProvider</a>: Rudimentary implementation for test purpose with the minimal required setup.</li>
-</ul>
-</li>
+ </ul></li>
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/SecurityConfiguration.html">SecurityConfiguration</a>: Base interface for all security related configurations.
+
<ul>
-
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/SecurityConfiguration.Default.html">SecurityConfiguration.Default</a>: Default base implementation return default implementations for initializers, context as well as empty parameters, hooks, validators etc.</li>
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/ConfigurationBase.html">ConfigurationBase</a>: Abstract base implementation of the <tt>SecurityConfiguration</tt> interface.</li>
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/CompositeConfiguration.html">CompositeConfiguration</a>: Abstract base implementation for all composite configurations that allow for aggregation of multiple modules.</li>
-</ul>
-</li>
+ </ul></li>
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/ConfigurationParameters.html">ConfigurationParameters</a>: Utility used to pass around parameters and options.</li>
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/Context.html">Context</a>: Context information that allows to identify items defined and maintained by a give security module implementation.</li>
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/RegistrationConstants.html">RegistrationConstants</a>: Utility used to define well-known registration properties</li>
</ul>
<div class="section">
@@ -316,29 +316,33 @@
<p>In a non-OSGi setup the <tt>SecurityProvider</tt> (be it the default or a custom implementation) gets passed to the repository constructor. See section <a href="#pluggability">pluggability</a> for details wrt module initialization.</p>
<p>The following example has been extracted from the basic test setup:</p>
-<div>
-<div>
-<pre class="source">NodeStore nodeStore = ...
+<div class="source">
+<div class="source"><pre class="prettyprint">NodeStore nodeStore = ...
ConfigurationParameters params = ... // TODO: provide config options
// Optional: set additional/custom implementations of the supported `SecurityConfiguration`s via the params
SecurityProvider sp = SecurityProviderBuilder.newBuilder().with(params).build();
Repository repository = new Jcr(nodeStore).with(sp).createRepository();
-</pre></div></div>
-</div></div>
+</pre></div></div></div></div>
<div class="section">
<h4><a name="SecurityConfiguration"></a>SecurityConfiguration</h4>
<p>The <tt>SecurityConfiguration</tt> interface defines functionality common to all security related modules. Apart from simple configuration parameters the basic interface defines the means to properly initialize a given security module and provide Oak internal mechanism to asserts proper validation and data consistency for all security relevant operations.</p>
<p>Please note, that <tt>RepositoryInitializer</tt> and <tt>WorkspaceInitializer</tt> as exposed by the base interface are only invoked upon repository|workspace initialization and consequently impact the <a href="#pluggability">pluggability</a> of a given security module. Examples includes modules that require modifications to the global repository content such as node types, namespaces and privileges or require the installation of initial content or index definitions for proper execution.</p>
<p>The following subinterfaces of <tt>SecurityConfiguration</tt> are currently defined by Oak:</p>
-<ul>
+<ul>
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/AuthenticationConfiguration.html">AuthenticationConfiguration</a>, <b>mandatory</b></li>
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/AuthorizationConfiguration.html">AuthorizationConfiguration</a>, <b>mandatory</b></li>
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/principal/PrincipalConfiguration.html">PrincipalConfiguration</a></li>
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/privilege/PrivilegeConfiguration.html">PrivilegeConfiguration</a></li>
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/token/TokenConfiguration.html">TokenConfiguration</a></li>
+
<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/user/UserConfiguration.html">UserConfiguration</a></li>
</ul>
<div class="section">
@@ -347,12 +351,11 @@ Repository repository = new Jcr(nodeStor
<p>This is compliant with the security requirements defined by JSR 283 which defines API to login into the repository and mandates minimal permission evaluation, be it implementation specific of imposed by the optional access control management.</p>
<p>The minimal security setup may consequently be reduced to a setup as defined by the following imaginary, custom <tt>SecurityProvider</tt> (see also <a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/OpenSecurityProvider.html">OpenSecurityProvider</a>)</p>
-<div>
-<div>
-<pre class="source"> public class MySecurityProvider implements SecurityProvider {
-
+<div class="source">
+<div class="source"><pre class="prettyprint"> public class MySecurityProvider implements SecurityProvider {
+
[...]
-
+
public <T> T getConfiguration(Class<T> configClass) {
if (AuthenticationConfiguration.class == configClass) {
return (T) new MyAuthentication();
@@ -362,11 +365,11 @@ Repository repository = new Jcr(nodeStor
throw new IllegalArgumentException();
}
}
-
+
private final class MyAuthentication extends SecurityConfiguration.Default implements AuthenticationConfiguration {
[...]
}
-
+
private final class MyAuthorization extends SecurityConfiguration.Default implements AuthorizationConfiguration {
public AccessControlManager getAccessControlManager(Root root, NamePathMapper namePathMapper) {
throw new UnsupportedOperationException();
@@ -380,129 +383,183 @@ Repository repository = new Jcr(nodeStor
}
}
</pre></div></div>
-
<p>All other security modules can be considered <i>optional</i> from an Oak repository point of view. Please note the following dependencies and special cases:</p>
-<ol style="list-style-type: decimal">
-<li><b>Authentication</b> is mandatory and expected to bind a set of <tt>Principal</tt>s to the <tt>Subject</tt>. This may happen before or during the repository login.</li>
-<li><b>Permission Evaluation</b> is mandatory and associated with the set of <tt>Principal</tt>s bound to to the <tt>Subject</tt> during the authentication step.</li>
-<li><tt>Principal</tt>s represent the link between authentication and authorization and <i>MAY</i> be exposed by Principal Management module as described above.</li>
-<li><b>Access Control Management</b> is optional and <i>usually</i> goes along with Principal and Privilege Management</li>
-<li><b>Principal Management</b> is optional and is <i>NOT</i> tied to User Management. However, supporting User Management in a given repository setup <i>usually</i> goes along with exposing the corresponding principals as part of the Principal Management.</li>
-<li><b>User Management</b> is optional and <i>MAY</i> be used for credentials validation during the authentication step. If present it is <i>usually</i> used as a source for principals exposed by Principal Management.</li>
+<ol style="list-style-type: decimal">
+
+<li><b>Authentication</b> is mandatory and expected to bind a set of <tt>Principal</tt>s to the <tt>Subject</tt>. This may happen before or during the repository login.</li>
+
+<li><b>Permission Evaluation</b> is mandatory and associated with the set of <tt>Principal</tt>s bound to to the <tt>Subject</tt> during the authentication step.</li>
+
+<li><tt>Principal</tt>s represent the link between authentication and authorization and <i>MAY</i> be exposed by Principal Management module as described above.</li>
+
+<li><b>Access Control Management</b> is optional and <i>usually</i> goes along with Principal and Privilege Management</li>
+
+<li><b>Principal Management</b> is optional and is <i>NOT</i> tied to User Management. However, supporting User Management in a given repository setup <i>usually</i> goes along with exposing the corresponding principals as part of the Principal Management.</li>
+
+<li><b>User Management</b> is optional and <i>MAY</i> be used for credentials validation during the authentication step. If present it is <i>usually</i> used as a source for principals exposed by Principal Management.</li>
</ol>
-<a name="configuration"></a>
-### Configuration
-
-<p>The configuration parameters of individual security modules are described in the corresponding sections. The following paragraphs describe the configuration of <tt>SecurityProvider</tt> and <tt>CompositeConfiguration</tt> in an OSGi-base setup.</p></div></div>
+<p><a name="configuration"></a></p></div></div></div>
+<div class="section">
+<h3><a name="Configuration"></a>Configuration</h3>
+<p>The configuration parameters of individual security modules are described in the corresponding sections. The following paragraphs describe the configuration of <tt>SecurityProvider</tt> and <tt>CompositeConfiguration</tt> in an OSGi-base setup.</p>
<div class="section">
<h4><a name="SecurityProviderRegistration"></a>SecurityProviderRegistration</h4>
-<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>Required Services</tt> </td>
-<td> String[] </td>
-<td> see below </td>
-<td> Service references mandatory for the SecurityProvider registration. </td></tr>
-</tbody>
+
+<td><tt>Required Services</tt> </td>
+
+<td>String[] </td>
+
+<td>see below </td>
+
+<td>Service references mandatory for the SecurityProvider registration. </td>
+ </tr>
+ </tbody>
</table>
<p>The value of the individual configuration entries can be one of:</p>
-<ul>
+<ul>
+
<li>the value of the <tt>service.pid</tt> registration property</li>
+
<li>the value of the <tt>oak.security.name</tt> registration property</li>
</ul>
<p>By default the <tt>SecurityProviderRegistration</tt> defines the following mandatory services. As long as these required references are not resolved the <tt>SecurityProviderRegistration</tt> will not register the <tt>SecurityProvider</tt> service and ultimately prevent premature initialization of the Oak repository instance.</p>
-<ul>
+<ul>
+
<li>“org.apache.jackrabbit.oak.security.authorization.AuthorizationConfigurationImpl”</li>
+
<li>“org.apache.jackrabbit.oak.security.principal.PrincipalConfigurationImpl”,</li>
+
<li>“org.apache.jackrabbit.oak.security.authentication.token.TokenConfigurationImpl”,</li>
+
<li>“org.apache.jackrabbit.oak.spi.security.user.action.DefaultAuthorizableActionProvider”,</li>
+
<li>“org.apache.jackrabbit.oak.security.authorization.restriction.RestrictionProviderImpl”,</li>
+
<li>“org.apache.jackrabbit.oak.security.user.UserAuthenticationFactoryImpl”</li>
</ul>
<p>The value of this configuration parameter needs to be adjusted for any additional module or functionality that is considered required for a successful security setup. See section <a href="#pluggability">pluggability</a> below.</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>Authorization Composition Type</tt> </td>
-<td> String (AND|OR) </td>
-<td> AND </td>
-<td> The Composite Authorization model uses this flag to determine what type of logic to apply to the existing providers</td></tr>
-</tbody>
+
+<td><tt>Authorization Composition Type</tt> </td>
+
+<td>String (AND|OR) </td>
+
+<td>AND </td>
+
+<td>The Composite Authorization model uses this flag to determine what type of logic to apply to the existing providers</td>
+ </tr>
+ </tbody>
</table>
<p>Given a set of permission providers, the composite model can aggregate the results by applying an <tt>AND</tt> logic (for example all providers must allow a specific privilege in order to be granted), or an <tt>OR</tt> (for example any provider can allow a privilege). By default the <tt>AND</tt> version is used.</p></div>
<div class="section">
<h4><a name="CompositeConfiguration"></a>CompositeConfiguration</h4>
-<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_RANKING</tt> </td>
-<td> int </td>
-<td> <tt>NO_RANKING</tt> (<tt>Integer.MIN_VALUE</tt>) </td>
-<td> Optional configuration parameter to define the ranking within the aggregation. </td></tr>
-</tbody>
+
+<td><tt>PARAM_RANKING</tt> </td>
+
+<td>int </td>
+
+<td><tt>NO_RANKING</tt> (<tt>Integer.MIN_VALUE</tt>) </td>
+
+<td>Optional configuration parameter to define the ranking within the aggregation. </td>
+ </tr>
+ </tbody>
</table>
<p>Note: Security modules that allow for multiple configurations may choose to expose the <tt>PARAM_RANKING</tt> option in order to allow for explicit ordering of the individual implementations. If the ranking parameter is omitted the <tt>CompositeConfiguration</tt> will try to use the <a class="externalLink" href="https://osgi.org/javadoc/r4v43/core/org/osgi/framework/Constants.html#SERVICE_RANKING">SERVICE_RANKING</a> to define the order. If neither is available (or set to <tt>NO_RANKING</tt>) the new entry will be appended to the list.</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>In a default setup Oak allows to plug custom or additional implementations of the various <tt>SecurityConfiguration</tt> described before. Similarly it would be possible to provide a custom <tt>SecurityProvider</tt>.</p>
-<p><i>Please note</i>: this is only recommended for experts having in-depth understanding of Oak internals and which understand the security risk associated with custom replacements or extensions.</p></div>
+<p><i>Please note</i>: this is only recommended for experts having in-depth understanding of Oak internals and which understand the security risk associated with custom replacements or extensions.</p>
<div class="section">
<h4><a name="SecurityProvider"></a>SecurityProvider</h4>
<p>The default <tt>SecurityProvider</tt> service could be replaced by deploying a custom service to the OSGi container. In a non-OSGi setup the JCR|Oak repository needs to be created with the custom implementation:</p>
-<div>
-<div>
-<pre class="source">SecurityProvider sp = new MySecurityProvider();
+<div class="source">
+<div class="source"><pre class="prettyprint">SecurityProvider sp = new MySecurityProvider();
Repository repository = new Jcr().with(sp).createRepository();
-</pre></div></div>
-</div>
+</pre></div></div></div>
<div class="section">
<h4><a name="SecurityConfiguration"></a>SecurityConfiguration</h4>
<p>The default Oak security setup distinguishes between the following types of modules:</p>
-<ul>
+<ul>
+
<li>Unary modules: <tt>AuthenticationConfiguration</tt>, <tt>PrivilegeConfiguration</tt>, <tt>UserConfiguration</tt></li>
+
<li>Multiple modules: <tt>AuthorizationConfiguration</tt> (since Oak 1.4), <tt>PrincipalConfiguration</tt>, <tt>TokenConfiguration</tt></li>
</ul>
<p>Plugging an implementation of an unary module will replace the default provided by Oak. As far as the multiple modules are concerned a custom implementation plugged into the repository will result in the creation of a <a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/CompositeConfiguration.html">CompositeConfiguration</a>. The aggregated modules are kept in a list while the insertion order is defined by the <tt>PARAM_RANKING</tt> or by the OSGi service ranking in case the explicit ranking parameter is missing.</p>
<div class="section">
<h5><a name="OSGi_setup"></a>OSGi setup</h5>
<p>The following steps are required to replace an existing <i>unary</i> security component or add an additional implementation (for <i>multiple</i> configurations only):</p>
-<ul>
+<ul>
+
<li>Deploy the bundle containing your custom implementation</li>
+
<li>Configure the component according to your needs</li>
+
<li>For <i>multiple</i> configurations make sure you have set the desired ranking</li>
-<li>Find the <tt>SecurityProviderRegistration</tt> <i>(“Apache Jackrabbit Oak SecurityProvider”)</i> config and enter the PID of your custom security module as additional value to the <tt>requiredServicePids</tt> property.</li>
-<li>In case of a replacement remove the PID of the module to be replaced and make sure your implementation gets a higher <a class="externalLink" href="https://osgi.org/javadoc/r4v43/core/org/osgi/framework/Constants.html#SERVICE_RANKING">SERVICE_RANKING</a> or deactivate the obsolete module altogether.</li>
+
+<li>Find the <tt>SecurityProviderRegistration</tt> <i>(“Apache Jackrabbit Oak SecurityProvider”)</i> config and enter the PID of your custom security module as additional value to the <tt>requiredServicePids</tt> property.</li>
+
+<li>In case of a replacement remove the PID of the module to be replaced and make sure your implementation gets a higher <a class="externalLink" href="https://osgi.org/javadoc/r4v43/core/org/osgi/framework/Constants.html#SERVICE_RANKING">SERVICE_RANKING</a> or deactivate the obsolete module altogether.</li>
</ul></div>
<div class="section">
<h5><a name="Non-OSGi_setup"></a>Non-OSGi setup</h5>
@@ -511,9 +568,8 @@ Repository repository = new Jcr().with(s
<h6><a name="Example"></a>Example</h6>
<p>Extend the default <tt>SecurityProvider</tt> with a custom <tt>PrincipalConfiguration</tt>. See also <i>oak-exercise</i> module for an example.</p>
-<div>
-<div>
-<pre class="source">MyPrincipalConfiguration pc = new MyPrincipalConfiguration();
+<div class="source">
+<div class="source"><pre class="prettyprint">MyPrincipalConfiguration pc = new MyPrincipalConfiguration();
ConfigurationParameters params = ConfigurationParameters.EMPTY;
pc.setParameters(params);
@@ -530,13 +586,13 @@ composite.addConfiguration(pc);
composite.addConfiguration(defConfig);
Repository repo = new Jcr(new Oak()).with(securityProvider).createRepository();
-</pre></div></div>
-</div></div>
+</pre></div></div></div></div>
<div class="section">
<h5><a name="Initialization_of_SecurityConfigurations"></a>Initialization of SecurityConfiguration(s)</h5>
<p>If a given security modules mandates repository and|or workspace initialization steps such as e.g. node type registration or persisting new index definitions, the deployment of the module requires a reload of the <tt>SecurityProvider</tt>.</p>
-<p>In the default OSGi-based setup this is achieved by adding the PID of corresponding service to the <tt>Required Service PIDs</tt> property mentioned above ultimately forcing the re-registration of the <tt>SecurityProvider</tt> service with the bundle context.</p>
-<p>Other setup scenarios would need to recreate the <tt>ContentRepository</tt> object or adjust the repository ‘initial’ content <i>before</i> binding the new configuration to the <tt>SecurityProvider</tt> in order to avoid inconsistencies.</p><!-- references --></div></div></div></div>
+<p>In the default OSGi-based setup this is achieved by adding the PID of corresponding service to the <tt>Required Service PIDs</tt> property mentioned above ultimately forcing the re-registration of the <tt>SecurityProvider</tt> service with the bundle context. </p>
+<p>Other setup scenarios would need to recreate the <tt>ContentRepository</tt> object or adjust the repository ‘initial’ content <i>before</i> binding the new configuration to the <tt>SecurityProvider</tt> in order to avoid inconsistencies. </p>
+<!-- references --></div></div></div></div>
</div>
</div>
</div>