jackrabbit-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ang...@apache.org
Subject svn commit: r1595256 [4/5] - in /jackrabbit/site/live/oak/docs: ./ security/ security/accesscontrol/ security/authentication/ security/permission/ security/user/
Date Fri, 16 May 2014 16:36:01 GMT
Modified: jackrabbit/site/live/oak/docs/security/authentication.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/authentication.html?rev=1595256&r1=1595255&r2=1595256&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/authentication.html (original)
+++ jackrabbit/site/live/oak/docs/security/authentication.html Fri May 16 16:36:00 2014
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2014-05-14
+ | Generated by Apache Maven Doxia at 2014-05-16
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <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="20140514" />
+    <meta name="Date-Revision-yyyymmdd" content="20140516" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Jackrabbit Oak - Authentication</title>
     <link rel="stylesheet" href="../css/apache-maven-fluido-1.3.0.min.css" />
@@ -163,7 +163,7 @@
         <ul class="breadcrumb">
                 
                     
-                  <li id="publishDate">Last Published: 2014-05-14</li>
+                  <li id="publishDate">Last Published: 2014-05-16</li>
                   <li class="divider">|</li> <li id="projectVersion">Version: 0.20-SNAPSHOT</li>
                       
                 
@@ -442,11 +442,11 @@
   
 <li><tt>Repository.login()</tt>: equivalent to passing <tt>null</tt> credentials and the default workspace name.</li>
   
-<li>`Repository.login(Credentials credentials): login with credentials to the default workspace.</li>
+<li><tt>Repository.login(Credentials credentials)</tt>: login with credentials to the default workspace.</li>
   
-<li><tt>Repository.login(String workspace): login with</tt>null` credentials to the workspace with the specified name.</li>
+<li><tt>Repository.login(String workspace)</tt>: login with <tt>null</tt> credentials to the workspace with the specified name.</li>
   
-<li><tt>Repository.login(Credentials credentials, String workspaceName</tt>)</li>
+<li><tt>Repository.login(Credentials credentials, String workspaceName)</tt></li>
   
 <li><tt>JackrabbitRepository.login(Credentials credentials, String workspaceName, Map&lt;String, Object&gt; attributes)</tt>:  in addition allows to pass implementation specific session attributes.</li>
 </ul>
@@ -455,19 +455,16 @@
 <div class="section">
 <h3>Oak Authentication<a name="Oak_Authentication"></a></h3>
 <div class="section">
-<h4>General Notes<a name="General_Notes"></a></h4>
-<p><i>todo</i></p></div>
-<div class="section">
 <h4>Oak API<a name="Oak_API"></a></h4>
-<p><i>todo</i></p>
+<p>The Oak API contains the following authentication related methods and interfaces</p>
 
 <ul>
   
-<li>ContentRepository.login</li>
+<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/AuthInfo.html">AuthInfo</a>: Immutable object created upon successful login providing information about the authenticated <tt>Subject.</tt></li>
   
-<li>AuthInfo</li>
+<li><tt>ContentRepository.login(Credentials, String)</tt>: The Oak counterpart of the JCR login.</li>
   
-<li>ContentSession.getAuthInfo</li>
+<li><tt>ContentSession.getAuthInfo()</tt>: exposes the <tt>AuthInfo</tt> associated with the <tt>ContentSession</tt>.</li>
 </ul></div>
 <div class="section">
 <h4>Differences wrt Jackrabbit 2.x<a name="Differences_wrt_Jackrabbit_2.x"></a></h4>
@@ -575,7 +572,7 @@ Session anonymous = repository.login(new
   
 <li><tt>Session#impersonate</tt> takes any kind of <tt>Credentials</tt></li>
   
-<li>the specified credentials are wrapped in a new instance of <a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/ImpersonationCredentials.html">ImpersonationCredentials</a>  along with the current <a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/AuthInfo.html">AuthInfo</a> object.</li>
+<li>the specified credentials are wrapped in a new instance of <a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/ImpersonationCredentials.html">ImpersonationCredentials</a>  along with the current <tt>AuthInfo</tt> object.</li>
   
 <li>these <tt>ImpersonationCredentials</tt> are passed to <tt>Repository.login</tt></li>
 </ol>
@@ -643,11 +640,7 @@ Session anonymous = repository.login(new
 <h3>API Extension<a name="API_Extension"></a></h3>
 <div class="section">
 <h4>Oak Authentication<a name="Oak_Authentication"></a></h4>
-<p><i>todo</i></p>
-<div class="section">
-<h5>Abstract Login Module<a name="Abstract_Login_Module"></a></h5>
-<p><i>todo</i></p>
-<p>org.apache.jackrabbit.oak.spi.security.authentication:</p>
+<p>In the the package <tt>org.apache.jackrabbit.oak.spi.security.authentication</tt> Oak 1.0 defines some extensions points that allow for further customization of the authentication.</p>
 
 <ul>
   
@@ -656,7 +649,66 @@ Session anonymous = repository.login(new
 <li><tt>LoginContext</tt>: Interface version of the JAAS LoginContext aimed to ease integration with non-JAAS components</li>
   
 <li><tt>Authentication</tt>: Aimed to validate credentials during the first phase of the (JAAS) login process.</li>
-</ul></div></div>
+</ul>
+<p>In addition this package contains various utilities and base implementations. Most notably an abstract login module implementation ([AbstractLoginModule]) as described below.</p>
+<div class="section">
+<h5>Abstract Login Module<a name="Abstract_Login_Module"></a></h5>
+<p>This package also contains a abstract <tt>LoginModule</tt> implementation ([AbstractLoginModule]) providing common functionality. In particular it contains Oak specific methods that allow subclasses to retrieve the <tt>SecurityProvider</tt>, a <tt>Root</tt> and accesss to various security related interfaces (e.g. <tt>PrincipalManager</tt>).</p>
+<p>Subclasses are required to implement the following methods:</p>
+
+<ul>
+  
+<li>`getSupportedCredentials(): return a set of supported credential classes.</li>
+  
+<li><tt>login()</tt>: The login method defined by <tt>LoginModule</tt></li>
+  
+<li><tt>commit()</tt>: The commit method defined by <tt>LoginModule</tt></li>
+</ul>
+<div class="section">
+<h6>Example: Extending AbstractLoginModule<a name="Example:_Extending_AbstractLoginModule"></a></h6>
+
+<div class="source">
+<pre>public class TestLoginModule extends AbstractLoginModule {
+
+    private Credentials credentials;
+    private String userId;
+    private Set&lt;? extends Principal&gt; principals;
+
+    @Nonnull
+    @Override
+    protected Set&lt;Class&gt; getSupportedCredentials() {
+        return ImmutableSet.of(TestCredentials.class);
+    }
+
+    @Override
+    public boolean login() throws LoginException {
+        credentials = getCredentials();
+        if (validCredentials(credentials)) {
+            this.credentials = credentials;
+            this.userId = getUserId(credentials);
+            this.principals = getPrincipals(userId);
+            return true;
+        }
+        return false;
+    }
+
+    @Override
+    public boolean commit() throws LoginException {
+        if (credentials != null) {
+            if (!subject.isReadOnly()) {
+                subject.getPublicCredentials().add(credentials);
+                if (principals != null) {
+                    subject.getPrincipals().addAll(principals);
+                }
+                AuthInfo authInfo = new AuthInfoImpl(userId, Collections.EMPTY_MAP, principals);
+                setAuthInfo(authInfo, subject);
+            }
+            return true;
+        }
+        return false;
+    }
+}
+</pre></div></div></div></div>
 <div class="section">
 <h4>Token Management<a name="Token_Management"></a></h4>
 <p>See section <a href="authentication/tokenmanagement.html">token management</a> for details.</p>
@@ -671,19 +723,48 @@ Session anonymous = repository.login(new
 </ul></div>
 <div class="section">
 <h4>User and Group Synchronization<a name="User_and_Group_Synchronization"></a></h4>
-<p><i>todo</i> <a href="authentication/usersync.html">Synchronization</a></p></div>
+<p>See section <a href="authentication/usersync.html">Synchronization</a> for details.</p>
+
+<ul>
+  
+<li><tt>SyncManager</tt>: factory for the <tt>SyncHandler</tt></li>
+  
+<li><tt>SyncHandler</tt>: responsible for synchronizing users/groups from an <tt>ExternalIdentityProvider</tt> into the repository.</li>
+  
+<li><tt>SyncContext</tt>: executes the synchronization</li>
+  
+<li><tt>SyncedIdentity</tt>: represents a synchronized identity</li>
+  
+<li><tt>SyncResult</tt>: the result of a sync operation</li>
+</ul></div>
 <div class="section">
 <h4>External Identity Management<a name="External_Identity_Management"></a></h4>
-<p>Oak in addition provides interfaces to ease custom implementation of the external authentication with optional user/group synchronization to the repository.</p>
-<p>See section <a href="authentication/identitymanagement.html">identity management</a> for details.</p></div></div>
+<p>Oak in addition provides interfaces to ease custom implementation of the external authentication with optional user/group synchronization to the repository. See section <a href="authentication/identitymanagement.html">identity management</a> for details.</p>
+
+<ul>
+  
+<li><tt>ExternalIdentityProviderManager</tt>: factory for the <tt>ExternalIdentityProvider</tt></li>
+  
+<li><tt>ExternalIdentityProvider</tt>: provides user/group information from a third party system.</li>
+  
+<li><tt>ExternalIdentity</tt>: base interface for an external user/group
+  
+<ul>
+    
+<li><tt>ExternalUser</tt></li>
+    
+<li><tt>ExternalGroup</tt></li>
+  </ul></li>
+  
+<li><tt>ExternalIdentityRef</tt>: reference to an external user/group</li>
+</ul></div></div>
 <div class="section">
 <h3>Configuration<a name="Configuration"></a></h3>
+<p>The configuration of the authentication setup is defined by the <a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/AuthenticationConfiguration.html">AuthenticationConfiguration</a>. This interface provides the following method:</p>
 
 <ul>
   
-<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/AuthenticationConfiguration.html">AuthenticationConfiguration</a>: <i>todo</i> <tt>getLoginContextProvider</tt> -&gt; configuration of the login context</li>
-  
-<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/token/TokenConfiguration.html">TokenConfiguration</a>: <tt>getTokenProvider</tt>. See section <a href="tokenmanagement.html">Token Management</a> for details.</li>
+<li><tt>getLoginContextProvider()</tt>: provides the login contexts for the desired authentication mechanism.</li>
 </ul>
 <div class="section">
 <h4>JAAS Configuration Utilities<a name="JAAS_Configuration_Utilities"></a></h4>
@@ -705,6 +786,16 @@ Session anonymous = repository.login(new
   </ul></li>
 </ul></div></div>
 <div class="section">
+<h3>Pluggability<a name="Pluggability"></a></h3>
+<p>The default security setup as present with Oak 1.0 is able to provide custom implementation on various levels:</p>
+
+<ol style="list-style-type: decimal">
+  
+<li>The complete authentiction setup can be changed by plugging a different  <tt>AuthenticationConfiguration</tt> implementations. In OSGi-base setup this is  achieved by making the configuration a service. In a non-OSGi-base setup the  custom configuration must be exposed by the <tt>SecurityProvider</tt> implementation.</li>
+  
+<li>Within the default authentication setup you replace or extend the set of  login modules and their individual settings. In an OSGi-base setup is achieved  by making the modules accessible to the framework and setting their execution  order accordingly. In a Non-OSGi setup this is specified in the <a class="externalLink" href="http://docs.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html">JAAS config</a>.</li>
+</ol></div>
+<div class="section">
 <h3>Further Reading<a name="Further_Reading"></a></h3>
 
 <ul>

Modified: jackrabbit/site/live/oak/docs/security/authentication/externalloginmodule.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/authentication/externalloginmodule.html?rev=1595256&r1=1595255&r2=1595256&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/authentication/externalloginmodule.html (original)
+++ jackrabbit/site/live/oak/docs/security/authentication/externalloginmodule.html Fri May 16 16:36:00 2014
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2014-05-14
+ | Generated by Apache Maven Doxia at 2014-05-15
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <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="20140514" />
+    <meta name="Date-Revision-yyyymmdd" content="20140515" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Jackrabbit Oak - Authentication with the External Login Module</title>
     <link rel="stylesheet" href="../../css/apache-maven-fluido-1.3.0.min.css" />
@@ -163,7 +163,7 @@
         <ul class="breadcrumb">
                 
                     
-                  <li id="publishDate">Last Published: 2014-05-14</li>
+                  <li id="publishDate">Last Published: 2014-05-15</li>
                   <li class="divider">|</li> <li id="projectVersion">Version: 0.20-SNAPSHOT</li>
                       
                 
@@ -475,9 +475,10 @@
 <div class="section">
 <h3>Configuration<a name="Configuration"></a></h3>
 <div class="section">
-<h4>Examples<a name="Examples"></a></h4>
 <div class="section">
-<h5>Example JAAS Configuration<a name="Example_JAAS_Configuration"></a></h5>
+<h5>Examples<a name="Examples"></a></h5>
+<div class="section">
+<h6>Example JAAS Configuration<a name="Example_JAAS_Configuration"></a></h6>
 <p>The following JAAS configuration shows how the <tt>ExternalLoginModule</tt> could be used in a setup that not solely uses third party login:</p>
 
 <div class="source">
@@ -489,7 +490,7 @@
         idp.name=&quot;ldap&quot;;
  };
 </pre></div>
-<!-- references --></div></div></div></div>
+<!-- references --></div></div></div></div></div>
                   </div>
             </div>
           </div>

Modified: jackrabbit/site/live/oak/docs/security/authentication/identitymanagement.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/authentication/identitymanagement.html?rev=1595256&r1=1595255&r2=1595256&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/authentication/identitymanagement.html (original)
+++ jackrabbit/site/live/oak/docs/security/authentication/identitymanagement.html Fri May 16 16:36:00 2014
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2014-05-14
+ | Generated by Apache Maven Doxia at 2014-05-16
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <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="20140514" />
+    <meta name="Date-Revision-yyyymmdd" content="20140516" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Jackrabbit Oak - External Identity Management</title>
     <link rel="stylesheet" href="../../css/apache-maven-fluido-1.3.0.min.css" />
@@ -163,7 +163,7 @@
         <ul class="breadcrumb">
                 
                     
-                  <li id="publishDate">Last Published: 2014-05-14</li>
+                  <li id="publishDate">Last Published: 2014-05-16</li>
                   <li class="divider">|</li> <li id="projectVersion">Version: 0.20-SNAPSHOT</li>
                       
                 
@@ -379,18 +379,38 @@
    See the License for the specific language governing permissions and
    limitations under the License. --><div class="section">
 <h2>External Identity Management<a name="External_Identity_Management"></a></h2>
-<p><i>todo</i></p>
+<div class="section">
+<h3>General<a name="General"></a></h3>
+<p><i>todo</i></p></div>
+<div class="section">
+<h3>Identity Management API<a name="Identity_Management_API"></a></h3>
 
 <ul>
   
-<li>ExternalIdentityProvider</li>
+<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/ExternalIdentityProviderManager.html">ExternalIdentityProviderManager</a>: factory for the <tt>ExternalIdentityProvider</tt></li>
   
-<li>ExternalIdentity</li>
+<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/ExternalIdentityProvider.html">ExternalIdentityProvider</a>: provides user/group information from a third party system.</li>
   
-<li>ExternalUser</li>
+<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/ExternalIdentity.html">ExternalIdentity</a>: base interface for an external user/group
   
-<li>ExternalGroup</li>
+<ul>
+    
+<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/ExternalUser.html">ExternalUser</a></li>
+    
+<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/ExternalGroup.html">ExternalGroup</a></li>
+  </ul></li>
+  
+<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/ExternalIdentityRef.html">ExternalIdentityRef</a>: reference to an external user/group</li>
 </ul></div>
+<div class="section">
+<h3>Default Implementation<a name="Default_Implementation"></a></h3>
+<p>The default implementation present with Oak 1.0 allows for third party authentication against LDAP.</p>
+<p><i>todo</i></p>
+<p>The configuration details are described in section <a href="ldap.html">LDAP Integration</a>.</p></div>
+<div class="section">
+<h3>Pluggability<a name="Pluggability"></a></h3>
+<p><i>todo</i></p>
+<!-- references --></div></div>
                   </div>
             </div>
           </div>

Modified: jackrabbit/site/live/oak/docs/security/authentication/preauthentication.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/authentication/preauthentication.html?rev=1595256&r1=1595255&r2=1595256&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/authentication/preauthentication.html (original)
+++ jackrabbit/site/live/oak/docs/security/authentication/preauthentication.html Fri May 16 16:36:00 2014
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2014-05-14
+ | Generated by Apache Maven Doxia at 2014-05-15
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <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="20140514" />
+    <meta name="Date-Revision-yyyymmdd" content="20140515" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Jackrabbit Oak - Pre-Authenticated Login</title>
     <link rel="stylesheet" href="../../css/apache-maven-fluido-1.3.0.min.css" />
@@ -163,7 +163,7 @@
         <ul class="breadcrumb">
                 
                     
-                  <li id="publishDate">Last Published: 2014-05-14</li>
+                  <li id="publishDate">Last Published: 2014-05-15</li>
                   <li class="divider">|</li> <li id="projectVersion">Version: 0.20-SNAPSHOT</li>
                       
                 
@@ -405,9 +405,9 @@
 <li>create a custom login module that only supports these dedicated credentials and  pushes both a new instance of <tt>PreAuthenticatedLogin</tt> and other information  required and processed by subsequent login modules (e.g. credentials and  user name).</li>
   
 <li>make sure the subsequent login modules in the JAAS configuration are capable  to deal with the <tt>PreAuthenticatedLogin</tt> and the additional information and  will properly populate the subject and optionally synchronize user information  or create login tokens.</li>
-</ol></div>
+</ol>
 <div class="section">
-<h4>Example<a name="Example"></a></h4>
+<h5>Example<a name="Example"></a></h5>
 <p>Example implementation of <tt>LoginModule#login</tt> that pushes the <tt>PreAuthenticatedLogin</tt> marker to the shared state:</p>
 
 <div class="source">
@@ -433,7 +433,7 @@
         [...]
     }
 }
-</pre></div></div></div>
+</pre></div></div></div></div>
 <div class="section">
 <h3>Pre-Authentication without Repository Involvement<a name="Pre-Authentication_without_Repository_Involvement"></a></h3>
 <p>Like in Jackrabbit-core the repository internal authentication verification can be skipped by calling <tt>Repository#login()</tt> or <tt>Repository#login(null, wspName)</tt>. In this case the repository implementation expects the verification to be performed prior to the login call.</p>
@@ -449,18 +449,17 @@
 <li>Add support for extending the pre-authenticated subject by always passing writable subjects to the <tt>JaasLoginContext</tt></li>
   
 <li>Dropping JAAS altogether by providing a custom implementation of the  <tt>org.apache.jackrabbit.oak.spi.security.authentication.LoginContext</tt> [2] interface.</li>
-</ul></div>
+</ul>
 <div class="section">
-<h4>Example<a name="Example"></a></h4>
+<h5>Example<a name="Example"></a></h5>
 <p>Example how to use this type of pre-authentication:</p>
 
 <div class="source">
 <pre>String userId = &quot;test&quot;;
 /**
- Retrive valid principals e.g. by calling jackrabbit API
- - PrincipalManager#getPrincipal and/or #getGroupMembership
- or from Oak SPI
- - PrincipalProvider#getPrincipals(String userId)
+ * Retrive valid principals e.g. by using Jackrabbit or Oak API:
+ * - PrincipalManager#getPrincipal and/or #getGroupMembership
+ * - PrincipalProvider#getPrincipals(String userId)
  */
 Set&lt;? extends Principal&gt; principals = getPrincipals(userId);
 AuthInfo authInfo = new AuthInfoImpl(userId, Collections.&lt;String, Object&gt;emptyMap(), principals);
@@ -477,7 +476,7 @@ try {
     throw new RepositoryException(&quot;failed to retrieve session.&quot;, e);
 }
 </pre></div>
-<!-- references --></div></div></div>
+<!-- references --></div></div></div></div>
                   </div>
             </div>
           </div>

Modified: jackrabbit/site/live/oak/docs/security/authentication/tokenmanagement.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/authentication/tokenmanagement.html?rev=1595256&r1=1595255&r2=1595256&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/authentication/tokenmanagement.html (original)
+++ jackrabbit/site/live/oak/docs/security/authentication/tokenmanagement.html Fri May 16 16:36:00 2014
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2014-05-14
+ | Generated by Apache Maven Doxia at 2014-05-15
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <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="20140514" />
+    <meta name="Date-Revision-yyyymmdd" content="20140515" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Jackrabbit Oak - Token Authentication and Token Management</title>
     <link rel="stylesheet" href="../../css/apache-maven-fluido-1.3.0.min.css" />
@@ -163,7 +163,7 @@
         <ul class="breadcrumb">
                 
                     
-                  <li id="publishDate">Last Published: 2014-05-14</li>
+                  <li id="publishDate">Last Published: 2014-05-15</li>
                   <li class="divider">|</li> <li id="projectVersion">Version: 0.20-SNAPSHOT</li>
                       
                 
@@ -559,6 +559,15 @@
       
 <td>8 </td>
     </tr>
+    
+<tr class="b">
+      
+<td> </td>
+      
+<td> </td>
+      
+<td> </td>
+    </tr>
   </tbody>
 </table></div>
 <div class="section">
@@ -586,9 +595,10 @@
 <li>make the configuration available to the Oak repository.</li>
 </ul>
 <div class="section">
-<h4>Examples<a name="Examples"></a></h4>
 <div class="section">
-<h5>Example TokenConfiguration<a name="Example_TokenConfiguration"></a></h5>
+<h5>Examples<a name="Examples"></a></h5>
+<div class="section">
+<h6>Example TokenConfiguration<a name="Example_TokenConfiguration"></a></h6>
 
 <div class="source">
 <pre>@Component()
@@ -623,7 +633,7 @@ public class MyTokenConfiguration extend
     }
 }
 </pre></div>
-<!-- references --></div></div></div></div>
+<!-- references --></div></div></div></div></div>
                   </div>
             </div>
           </div>

Modified: jackrabbit/site/live/oak/docs/security/authentication/usersync.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/authentication/usersync.html?rev=1595256&r1=1595255&r2=1595256&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/authentication/usersync.html (original)
+++ jackrabbit/site/live/oak/docs/security/authentication/usersync.html Fri May 16 16:36:00 2014
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2014-05-14
+ | Generated by Apache Maven Doxia at 2014-05-16
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <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="20140514" />
+    <meta name="Date-Revision-yyyymmdd" content="20140516" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Jackrabbit Oak - User and Group Synchronization</title>
     <link rel="stylesheet" href="../../css/apache-maven-fluido-1.3.0.min.css" />
@@ -163,7 +163,7 @@
         <ul class="breadcrumb">
                 
                     
-                  <li id="publishDate">Last Published: 2014-05-14</li>
+                  <li id="publishDate">Last Published: 2014-05-16</li>
                   <li class="divider">|</li> <li id="projectVersion">Version: 0.20-SNAPSHOT</li>
                       
                 
@@ -379,13 +379,44 @@
    See the License for the specific language governing permissions and
    limitations under the License. --><div class="section">
 <h2>User and Group Synchronization<a name="User_and_Group_Synchronization"></a></h2>
+<div class="section">
+<h3>General<a name="General"></a></h3>
 <p>The synchronization of users and groups is triggered by the <a href="externalloginmodule.html">ExternalLoginModule</a>, after a user is successfully authenticated against the IDP or if it&#x2019;s no longer present on the IDP.</p>
-<p>Oak comes with a default implementation of the <tt>SyncHandler</tt> interface: [org.apache.jackrabbit.oak.spi.security.authentication.external.impl.DefaultSyncHandler].</p>
+<p>Oak comes with a default implementation of the <tt>SyncHandler</tt> interface: [org.apache.jackrabbit.oak.spi.security.authentication.external.impl.DefaultSyncHandler].</p></div>
+<div class="section">
+<h3>Synchronization API<a name="Synchronization_API"></a></h3>
+
+<ul>
+  
+<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/SyncManager.html">SyncManager</a>: factory for all configured <tt>SyncHandler</tt> implementations.</li>
+  
+<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/SyncHandler.html">SyncHandler</a>: responsible for synchronizing users/groups from an <tt>ExternalIdentityProvider</tt> into the repository.</li>
+  
+<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/SyncContext.html">SyncContext</a>: executes the synchronization</li>
+  
+<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/SyncedIdentity.html">SyncedIdentity</a>: represents a synchronized identity</li>
+  
+<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/SyncResult.html">SyncResult</a>: the result of a sync operation</li>
+  
+<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/SyncException.html">SyncException</a></li>
+</ul></div>
 <div class="section">
+<h3>Default Implementation<a name="Default_Implementation"></a></h3>
+<p>Oak 1.0 provides a default implementation of the user synchronization API that allow to plug additional <tt>SyncHandler</tt> implementations.</p>
+<p>The <a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/impl/DefaultSyncHandler.html">DefaultSyncHandler</a> itself comes with a set of configuration options that allow to specify the synchronization behavior (see below). All users/groups synchronized by this handler will get the following properties set:</p>
+
+<ul>
+  
+<li><tt>rep:externalId</tt></li>
+  
+<li><tt>rep:lastSynced</tt></li>
+</ul>
+<p>These properties allow to run separat task for periodical update and make sure the authorizables can later on be identitied as external users.</p></div>
 <div class="section">
+<h3>Configuration<a name="Configuration"></a></h3>
 <div class="section">
-<h5>Configuration of the DefaultSyncHandler<a name="Configuration_of_the_DefaultSyncHandler"></a></h5>
-<p>Oak provides a default synchronization handler that is configured via [DefaultSyncConfig]. The handler is configured either via OSGi or during manual <a href="../../construct.html">Repository Construction</a>.</p>
+<h4>Configuration of the DefaultSyncHandler<a name="Configuration_of_the_DefaultSyncHandler"></a></h4>
+<p>The default sync handler implementation is configured via <a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/impl/DefaultSyncConfig.html">DefaultSyncConfig</a>:</p>
 
 <table border="0" class="table table-striped">
   <thead>
@@ -502,14 +533,40 @@
     
 <tr class="a">
       
-<td>&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160; </td>
+<td> </td>
       
 <td> </td>
       
 <td> </td>
     </tr>
   </tbody>
-</table></div></div></div></div>
+</table></div></div>
+<div class="section">
+<h3>Pluggability<a name="Pluggability"></a></h3>
+<p>There are two ways to replace/change the user synchronization behavior</p>
+
+<ol style="list-style-type: decimal">
+  
+<li>Write custom <tt>SyncManager</tt></li>
+  
+<li>Write custom <tt>SyncHandler</tt></li>
+</ol>
+<p>The following steps are required in order to replace the default <tt>SyncManager</tt> implementation or plug a new implementation of the <tt>SyncHandler</tt>:</p>
+
+<ul>
+  
+<li>write your custom implementation of the interface</li>
+  
+<li>make the manager/handler available to the authentication setup or sync manager
+  
+<ul>
+    
+<li>OSGi setup: making the implementation an OSGi service</li>
+    
+<li>non-OSGi setup: configure the manager/handler during manual <a href="../../construct.html">Repository Construction</a>.</li>
+  </ul></li>
+</ul>
+<!-- references --></div></div>
                   </div>
             </div>
           </div>

Modified: jackrabbit/site/live/oak/docs/security/overview.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/overview.html?rev=1595256&r1=1595255&r2=1595256&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/overview.html (original)
+++ jackrabbit/site/live/oak/docs/security/overview.html Fri May 16 16:36:00 2014
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2014-05-14
+ | Generated by Apache Maven Doxia at 2014-05-16
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <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="20140514" />
+    <meta name="Date-Revision-yyyymmdd" content="20140516" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Jackrabbit Oak - The Oak Security Layer</title>
     <link rel="stylesheet" href="../css/apache-maven-fluido-1.3.0.min.css" />
@@ -163,7 +163,7 @@
         <ul class="breadcrumb">
                 
                     
-                  <li id="publishDate">Last Published: 2014-05-14</li>
+                  <li id="publishDate">Last Published: 2014-05-16</li>
                   <li class="divider">|</li> <li id="projectVersion">Version: 0.20-SNAPSHOT</li>
                       
                 
@@ -408,6 +408,8 @@
 <li><a href="accesscontrol/differences.html">Differences wrt Jackrabbit 2.x</a></li>
   
 <li><a href="accesscontrol/restriction.html">Restriction Management</a></li>
+  
+<li><a href="accesscontrol/editing.html">Using the API</a></li>
 </ul></div>
 <div class="section">
 <h3>Permissions<a name="Permissions"></a></h3>

Modified: jackrabbit/site/live/oak/docs/security/permission.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/permission.html?rev=1595256&r1=1595255&r2=1595256&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/permission.html (original)
+++ jackrabbit/site/live/oak/docs/security/permission.html Fri May 16 16:36:00 2014
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2014-05-14
+ | Generated by Apache Maven Doxia at 2014-05-16
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <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="20140514" />
+    <meta name="Date-Revision-yyyymmdd" content="20140516" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Jackrabbit Oak - Permissions</title>
     <link rel="stylesheet" href="../css/apache-maven-fluido-1.3.0.min.css" />
@@ -163,7 +163,7 @@
         <ul class="breadcrumb">
                 
                     
-                  <li id="publishDate">Last Published: 2014-05-14</li>
+                  <li id="publishDate">Last Published: 2014-05-16</li>
                   <li class="divider">|</li> <li id="projectVersion">Version: 0.20-SNAPSHOT</li>
                       
                 
@@ -381,15 +381,141 @@
 <h2>Permissions<a name="Permissions"></a></h2>
 <div class="section">
 <h3>JCR API<a name="JCR_API"></a></h3>
-<p><i>todo</i></p>
-<p><b><tt>Session#hasPermission</tt> and <tt>Session#checkPermission</tt></b></p>
-<p><i>todo</i></p>
-<p><b>JCR Actions</b></p>
-<p><i>todo</i></p>
+<p>While access control management is a optional feature, a JCR implementation is required to support the basic permission checking. The basic requirements for the permission evalution are defines as follows</p>
+
+<blockquote>
+<p>Permissions encompass the restrictions imposed by any access control restrictions that may be in effect upon the content of a repository, either implementation specific or JCR-defined (Access Control Management)., which consists of</p>
+</blockquote>
+<p>The methods defined to check permissions:</p>
+
+<ul>
+  
+<li><tt>Session#hasPermission(String absPath, String actions)</tt></li>
+  
+<li><tt>Session#checkPermission(String absPath, String actions)</tt></li>
+</ul>
+<p>The actions are expected to be a comma separated list of any of the following string constants:</p>
+
+<ul>
+  
+<li><tt>Session.ACTION_READ</tt></li>
+  
+<li><tt>Session.ACTION_ADD_NODE</tt></li>
+  
+<li><tt>Session.ACTION_REMOVE</tt></li>
+  
+<li><tt>Session.ACTION_SET_PROPERTY</tt></li>
+</ul>
+<p><b>Note</b>: As of Oak 1.0 the these methods also handle the names of the permissions defined by Oak (see <tt>Permissions#getString(long permissions)</tt>).</p>
+<div class="section">
+<div class="section">
+<h5>Examples<a name="Examples"></a></h5>
+<div class="section">
+<h6>Test if session has permission to add a new node<a name="Test_if_session_has_permission_to_add_a_new_node"></a></h6>
+<p>Important: <tt>absPath</tt> refers to the node to be created</p>
+
+<div class="source">
+<pre>Node content = session.getNode(&quot;/content&quot;);
+if (session.hasPermission(&quot;/content/newNode&quot;, Session.ACTION_ADD_NODE)) {
+     content.addNode(&quot;newNode&quot;);
+     session.save();
+}
+</pre></div></div>
+<div class="section">
+<h6>Test if session has permission to perform version operations<a name="Test_if_session_has_permission_to_perform_version_operations"></a></h6>
+
+<div class="source">
+<pre>Node content = session.getNode(&quot;/content&quot;);
+if (session.hasPermission(&quot;/content&quot;, Permissions.getString(Permissions.VERSION_MANAGEMENT))) {
+     content.checkin();
+     session.save();
+}
+</pre></div></div></div></div></div>
+<div class="section">
+<h3>Oak Permissions<a name="Oak_Permissions"></a></h3>
+<div class="section">
+<h4>Built-in Permissions<a name="Built-in_Permissions"></a></h4>
+<p>Oak 1.0 defines the following <a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/permission/Permissions.html">Permissions</a>:</p>
+<div class="section">
+<h5>Simple Permissions<a name="Simple_Permissions"></a></h5>
+<p>Read operations:</p>
+
+<ul>
+  
+<li><tt>READ_NODE</tt></li>
+  
+<li><tt>READ_PROPERTY</tt></li>
+  
+<li><tt>READ_ACCESS_CONTROL</tt></li>
+</ul>
+<p>Write operations:</p>
+
+<ul>
+  
+<li><tt>ADD_NODE</tt></li>
+  
+<li><tt>REMOVE_NODE</tt></li>
+  
+<li><tt>MODIFY_CHILD_NODE_COLLECTION</tt></li>
+  
+<li><tt>ADD_PROPERTY</tt></li>
+  
+<li><tt>MODIFY_PROPERTY</tt></li>
+  
+<li><tt>REMOVE_PROPERTY</tt></li>
+  
+<li><tt>NODE_TYPE_MANAGEMENT</tt></li>
+  
+<li><tt>MODIFY_ACCESS_CONTROL</tt></li>
+  
+<li><tt>LOCK_MANAGEMENT</tt></li>
+  
+<li><tt>VERSION_MANAGEMENT</tt></li>
+</ul>
+<p>Since Oak 1.0:</p>
+
+<ul>
+  
+<li><tt>USER_MANAGEMENT</tt>: : execute user management related tasks such as e.g. creating or removing user/group, changing user password and editing group membership.</li>
+  
+<li><tt>INDEX_DEFINITION_MANAGEMENT</tt>: create, modify and remove the oak:index node and it&#x2019;s subtree which is expected to contain the index definitions.</li>
+</ul>
+<p>Repository operations:</p>
+
+<ul>
+  
+<li><tt>NODE_TYPE_DEFINITION_MANAGEMENT</tt></li>
+  
+<li><tt>NAMESPACE_MANAGEMENT</tt></li>
+  
+<li><tt>PRIVILEGE_MANAGEMENT</tt></li>
+  
+<li><tt>WORKSPACE_MANAGEMENT</tt></li>
+</ul>
+<p>Not used in Oak 1.0:</p>
+
+<ul>
+  
+<li><tt>LIFECYCLE_MANAGEMENT</tt></li>
+  
+<li><tt>RETENTION_MANAGEMENT</tt></li>
+</ul></div>
 <div class="section">
+<h5>Aggregated Permissions<a name="Aggregated_Permissions"></a></h5>
+
+<ul>
+  
+<li><tt>READ</tt>: aggregates <tt>READ_NODE</tt> and <tt>READ_PROPERTY</tt></li>
+  
+<li><tt>REMOVE</tt>: aggregates <tt>REMOVE_NODE</tt> and <tt>REMOVE_PROPERTY</tt></li>
+  
+<li><tt>SET_PROPERTY</tt>: aggregates <tt>ADD_PROPERTY</tt>, <tt>MODIFY_PROPERTY</tt> and <tt>REMOVE_PROPERTY</tt></li>
+  
+<li><tt>ALL</tt>: aggregates all permissions</li>
+</ul></div></div>
 <div class="section">
-<h5>Mapping of JCR Actions to Oak Permissions<a name="Mapping_of_JCR_Actions_to_Oak_Permissions"></a></h5>
-<p>`ACTION_READ&#x2019;:</p>
+<h4>Mapping of JCR Actions to Oak Permissions<a name="Mapping_of_JCR_Actions_to_Oak_Permissions"></a></h4>
+<p><tt>ACTION_READ</tt>:</p>
 
 <ul>
   
@@ -430,49 +556,58 @@
 <li>regular properties: <tt>Permissions.MODIFY_PROPERTY</tt></li>
   
 <li>non-existing properties: <tt>Permissions.ADD_PROPERTY</tt></li>
-</ul>
-<p><b>Note</b> Since Oak the permission related API calls not only allow to pass the action strings defined by JCR specification (see constants defined in <tt>Session.java</tt>) but also handles the names of the permission defined by Oak (see <tt>Permissions#getString(long permissions)</tt>).</p></div></div></div>
+</ul></div>
 <div class="section">
-<h3>Oak API<a name="Oak_API"></a></h3>
-<p><i>todo</i></p>
+<h4>Permissions for Different Operations<a name="Permissions_for_Different_Operations"></a></h4>
 <div class="section">
-<h4>Built-in Permissions<a name="Built-in_Permissions"></a></h4>
-<p>The set of permissions supported by Oak are listed in <a href="/oak/docs/apidocs/org/apache/jackrabbit/org/apache/jackrabbit/oak/spi/security/authorization/permission/Permissions.html">Permissions</a>. The following changes have been compared compared to Jackrabbit 2.x:</p>
+<h5>Reading<a name="Reading"></a></h5>
 
 <ul>
   
-<li><tt>READ_NODE</tt>: permission to read a node</li>
+<li><b>Regular Items</b>: Due to the fine grained read permissions Oak read access can be separately granted/denied for nodes and properties. Granting the <tt>jcr:read</tt> privilege will result in a backwards compatible read access for nodes and their properties, while specifying <tt>rep:readNodes</tt> or <tt>rep:readProperties</tt> privileges allows to grant or deny access to nodes and properties (see also <a href="../privilege.html">Privilege Management</a> for changes in the privilege definitions). Together with the restrictions this new behavior now allows to individually grant/deny access to properties that match a given name/path/nodetype (and as a possible extension even property value).</li>
   
-<li><tt>READ_PROPERTY</tt>: permission to read a property</li>
+<li><b>Version Content</b>: The accessibility of version content located underneath <tt>/jcr:system/jcr:versionStore</tt> is defined by the permissions present with the versionable node. In case the version information does no longer have a versionable node in this workspace it&#x2019;s original versionable path is used to evaluate the effective permissions that would apply to that item if the version was restored. This change is covered by <a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-444">OAK-444</a> and addresses concerns summarized in <a class="externalLink" href="https://issues.apache.org/jira/browse/JCR-2963">JCR-2963</a>.</li>
   
-<li><tt>ADD_PROPERTY</tt>: permission to create a new property</li>
+<li><b>Access Control Content</b> Read access to access control content such node storing policy or ACE information requires <tt>READ_ACCESS_CONTROL</tt> permission.</li>
+</ul></div>
+<div class="section">
+<h5>Writing<a name="Writing"></a></h5>
+
+<ul>
   
-<li><tt>MODIFY_PROPERTY</tt>: permission to change an existing property</li>
+<li><b>Property Modification</b>: Since Oak the former <tt>SET_PROPERTY</tt> permission has been split such to allow for more fined grained control on writing JCR properties. In particular Oak clearly distinguishes between creating a new property that didn&#x2019;t exist before, modifying or removing an existing property. This will allow to cover those cases where a given <tt>Subject</tt> is only allowed to create content without having the ability to modify/delete it later on.</li>
   
-<li><tt>REMOVE</tt>: aggregation of <tt>REMOVE_NODE</tt> and <tt>REMOVE_PROPERTY</tt></li>
+<li><b>Node Removal</b>: As of Oak <tt>Node#remove()</tt> only requires sufficient permissions to remove the target node. See below for configuration parameters to obtain backwards compatible behavior.</li>
   
-<li><tt>USER_MANAGEMENT</tt>: permission to execute user management related tasks such as e.g. creating or removing user/group, changing user password and editing group membership.</li>
+<li><b>Rename</b>: Due to the nature of the diff mechanism in Oak it is no longer possible to distinguish between <tt>JackrabbitNode#rename</tt> and a move with subsequent reordering.</li>
   
-<li><tt>INDEX_DEFINITION_MANAGEMENT</tt>: permission to create, modify and remove the oak:index node and it&#x2019;s subtree which is expected to contain the index definitions.</li>
-</ul>
-<p>The following permissions are now an aggregation of new permissions:</p>
-
-<ul>
+<li><b>Move</b>: The current permission evaluation attempts to provide a best-effort handling to achieve a similar behavior that it was present in Jackrabbit 2.x by keeping track of transient move operations. The current implementation has the following limitations with respect to multiple move operations within a given set of transient operations:
   
-<li><tt>READ</tt>: aggregates <tt>READ_NODE</tt> and <tt>READ_PROPERTY</tt></li>
+<ul>
+    
+<li>Move operations that replace an node that has been moved away will not be detected as modification by the diff mechanism and regular permission checks for on the subtree will be performed.</li>
+    
+<li>Moving an ancestor of a node that has been moved will only detect the second move and will enforce regular permissions checks on the child that has been moved in a first step.</li>
+  </ul></li>
   
-<li><tt>SET_PROPERTY</tt>: aggregates <tt>ADD_PROPERTY</tt>, <tt>MODIFY_PROPERTY</tt> and <tt>REMOVE_PROPERTY</tt></li>
+<li><b>Managing Index Definitions</b>: Writing query index definitions requires the specific index definition management which is enforce on nodes named &#x201c;oak:index&#x201d; and the subtree defined by them. Note that the corresponding items are not protected in the JCR sense. Consequently any other modification in these subtrees like e.g. changing the primary type or adding mixin types is governed by the corresponding privileges.</li>
 </ul></div>
 <div class="section">
-<h4>New Permissions<a name="New_Permissions"></a></h4>
-<p><i>todo</i></p>
+<h5>Writing Protected Items<a name="Writing_Protected_Items"></a></h5>
+<p>Writing protected items requires specific permissions and is not covered by regular JCR write permissions. This affects:</p>
 
 <ul>
   
-<li><tt>USER_MANAGEMENT</tt>: permission to execute user management related tasks such as e.g. creating or removing user/group, changing user password and editing group membership.</li>
+<li><b>Set/Modify Primary or Mixin Type</b>: <tt>NODE_TYPE_MANAGEMENT</tt></li>
   
-<li><tt>INDEX_DEFINITION_MANAGEMENT</tt>: permission to create, modify and remove the oak:index node and it&#x2019;s subtree which is expected to contain the index definitions.</li>
-</ul></div></div>
+<li><b>Access Control Content</b>: <tt>MODIFY_ACCESS_CONTROL</tt></li>
+  
+<li><b>Locking</b>: <tt>LOCK_MANAGEMENT</tt></li>
+  
+<li><b>Versioning</b>: Executing version related operations and thus writing to the version store requires <tt>VERSION_MANAGEMENT</tt> permission instead of the regular JCR write permissions. Similarly, the content in the version store can only be modified using the dedicated version management API.</li>
+  
+<li><b>User Management</b>: By default user management operations require the specific user management related permission <tt>USER_MANAGEMENT</tt> to be granted for the editing subject. This permission (including a corresponding privilege) has been introduced with Oak 1.0. See below for configuration parameters to obtain backwards compatible behavior.</li>
+</ul></div></div></div>
 <div class="section">
 <h3>Characteristics of the Permission Evaluation<a name="Characteristics_of_the_Permission_Evaluation"></a></h3>
 <div class="section">
@@ -482,8 +617,42 @@
 <h4>Differences wrt Jackrabbit 2.x<a name="Differences_wrt_Jackrabbit_2.x"></a></h4>
 <p>see the corresponding <a href="permission/differences.html">documentation</a>.</p></div>
 <div class="section">
+<h4>Details on Permission Evaluation<a name="Details_on_Permission_Evaluation"></a></h4>
+<div class="section">
+<h5>Administrative Access<a name="Administrative_Access"></a></h5>
+<p>In the default implementation following principals always have full access to the whole content repository (except for hidden items that are not exposed on the Oak API) irrespective of the access control content:</p>
+
+<ul>
+  
+<li><tt>SystemPrincipal</tt></li>
+  
+<li>All instances of <tt>AdminPrincipal</tt></li>
+  
+<li>All principals whose name matches the configured administrative principal names (see Configuration section below). This configuration only applies to the permission evaluation and is currently not reflected in other security models nor methods that deal with the administrator (i.e. <tt>User#isAdmin</tt>).</li>
+</ul></div>
+<div class="section">
+<h5>Readable Trees<a name="Readable_Trees"></a></h5>
+<p>Oak 1.0 comes with a configurable set of subtrees that are read-accessible to all subjects irrespective of other access control content taking effect. The original aim of these readable trees is to assert full acccess to namespace, nodetype and privilege information and the corresponding configuration therefore lists the following paths:</p>
+
+<ul>
+  
+<li><tt>/jcr:system/rep:namespaces</tt>: stores all registered namespaces</li>
+  
+<li><tt>/jcr:system/jcr:nodeTypes</tt>: stores all registered node types</li>
+  
+<li><tt>/jcr:system/rep:privileges</tt>: stores all registered privileges</li>
+</ul>
+<p>This default set can be changed or extended by setting the corresponding configuration option. However, it is important to note that many JCR API calls rely on the accessibility of the namespace, nodetype and privilege information. Removing the corresponding paths from the configuration will most probably have undesired effects.</p></div>
+<div class="section">
+<h5>Regular Permission Evaluation<a name="Regular_Permission_Evaluation"></a></h5>
+<p>See section <a href="permission/evaluation.html">Permission Evaluation in Detail</a>.</p></div></div>
+<div class="section">
 <h4>Permission Representation in the Repository<a name="Permission_Representation_in_the_Repository"></a></h4>
-<p><i>todo</i></p>
+<div class="section">
+<h5>Permission Store<a name="Permission_Store"></a></h5>
+<p><i>todo</i></p></div>
+<div class="section">
+<h5>Node Type Definitions<a name="Node_Type_Definitions"></a></h5>
 
 <div class="source">
 <pre>[rep:PermissionStore]
@@ -501,58 +670,132 @@
 [rep:VersionablePaths]
   mixin
   - * (PATH) protected ABORT
-</pre></div></div>
+</pre></div></div></div></div>
 <div class="section">
-<h4>Administrative Access<a name="Administrative_Access"></a></h4>
-<p>In the default implementation following principals always have full access to the whole content repository (except for hidden items that are not exposed on the Oak API) irrespective of the access control content:</p>
+<h3>API Extensions<a name="API_Extensions"></a></h3>
+<p>Due to the separation of access control management from permission evaluation, Oak 1.0 comes with a dedicated API for permission discovery that is used both for the repository internal permission evaluation as well as for permission discovery at JCR level.</p>
+<p>The package <tt>org.apache.jackrabbit.oak.spi.security.authorization.permission</tt> defines the following interface:</p>
 
 <ul>
   
-<li><tt>SystemPrincipal</tt></li>
+<li><tt>PermissionProvider</tt>: Main entry point for permission discovery and evaluation.
   
-<li>All instances of <tt>AdminPrincipal</tt></li>
-  
-<li>All principals whose name matches the configured administrative principal names (see Configuration section below). This configuration only applies to the permission evaluation and is currently not reflected in other security models nor methods that deal with the administrator (i.e. <tt>User#isAdmin</tt>).</li>
-</ul></div>
-<div class="section">
-<h4>Detains on Permission Evaluation<a name="Detains_on_Permission_Evaluation"></a></h4>
-<p><i>todo</i></p>
-<p>see <a href="permission/evaluation.html">details</a></p></div></div>
-<div class="section">
-<h3>API Extensions<a name="API_Extensions"></a></h3>
-<p><i>todo</i></p>
-<p>org.apache.jackrabbit.oak.spi.security.authorization.permission</p>
-
 <ul>
-  
-<li><tt>PermissionProvider</tt>: Main entry point for Oak internal permission evaluation.</li>
+    
+<li><tt>TreePermission</tt>: Evaluates the permissions of a given Oak <tt>Tree</tt>, exposed by <tt>PermissionProvider</tt>.</li>
+    
+<li><tt>RepositoryPermission</tt>: Evaluates the repository level permissions, exposed by <tt>PermissionProvider</tt>.</li>
+  </ul></li>
   
 <li><tt>Permissions</tt>: The permissions defined, respected and evaluated by the repository.</li>
   
 <li><tt>PermissionConstants</tt>: Constants used throughout the permission evaluation.</li>
-</ul></div>
+</ul>
+<div class="section">
+<h4>PermissionProvider<a name="PermissionProvider"></a></h4>
+<p><i>todo</i></p></div>
+<div class="section">
+<h4>TreePermission<a name="TreePermission"></a></h4>
+<p><i>todo</i></p></div>
+<div class="section">
+<h4>RepositoryPermission<a name="RepositoryPermission"></a></h4>
+<p><i>todo</i></p></div></div>
 <div class="section">
 <h3>Configuration<a name="Configuration"></a></h3>
+<p>The configuration of the permission evaluation implementation is handled by the <a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/AuthorizationConfiguration.html">AuthorizationConfiguration</a>, which is used for all authorization related matters. This class provides the following two permission related methods:</p>
 
 <ul>
   
-<li></li>
+<li><tt>getPermissionProvider(Root, String, Set&lt;Principal&gt;)</tt>: get a new <tt>PermissionProvider</tt> instance.</li>
 </ul>
-<p>Configuration Parameters supported by the default implementation</p>
+<div class="section">
+<h4>Configuration Parameters<a name="Configuration_Parameters"></a></h4>
+<p>The default implementation supports the following configuration parameters:</p>
+
+<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>
+    
+<tr class="b">
+      
+<td><tt>PARAM_PERMISSIONS_JR2</tt> </td>
+      
+<td>String </td>
+      
+<td>- </td>
+      
+<td>Enables backwards compatible behavior for the permissions listed in the parameter value containing the permission names separated by &#x2018;,&#x2019;. Supported values are: <tt>USER_MANAGEMENT</tt>,<tt>REMOVE_NODE</tt> </td>
+    </tr>
+    
+<tr class="a">
+      
+<td><tt>PARAM_READ_PATHS</tt> </td>
+      
+<td>Set&lt;String&gt; </td>
+      
+<td>paths to namespace, nodetype and privilege root nodes </td>
+      
+<td>Set of paths that are always readable to all principals irrespective of other permissions defined at that path or inherited from other nodes. </td>
+    </tr>
+    
+<tr class="b">
+      
+<td><tt>PARAM_ADMINISTRATIVE_PRINCIPALS</tt> </td>
+      
+<td>String[] </td>
+      
+<td>- </td>
+      
+<td>The names of the additional principals that have full permission and for which the permission evaluation can be skipped altogether. </td>
+    </tr>
+    
+<tr class="a">
+      
+<td> </td>
+      
+<td> </td>
+      
+<td> </td>
+      
+<td> </td>
+    </tr>
+  </tbody>
+</table>
+<div class="section">
+<h5>PARAM_PERMISSIONS_JR2<a name="PARAM_PERMISSIONS_JR2"></a></h5>
 
 <ul>
   
-<li><tt>PARAM_PERMISSIONS_JR2</tt>: Enables backwards compatible behavior for the permissions listed in the parameter value. Currently the following values are allowed: <tt>USER_MANAGEMENT</tt> and <tt>REMOVE_NODE</tt>. The parameter value must contain the permission names separated by &#x2018;,&#x2019;.</li>
+<li><tt>REMOVE_NODE</tt>: if present, the permission evaluation will traverse down the hierarchy upon node removal. This config flag is a best effort approach but doesn&#x2019;t guarantee an identical behavior.</li>
   
-<li><tt>PARAM_READ_PATHS</tt>: default set of paths that are always readable to all principals irrespective of other permissions defined at that path or inherited from other nodes.</li>
-  
-<li><tt>PARAM_ADMINISTRATIVE_PRINCIPALS</tt>: The names of the additional principals that have full permission and for which the permission evaluation can be skipped altogether.</li>
-</ul>
-<p>Differences to Jackrabbit 2.x The <tt>omit-default-permission</tt> configuration option present with the Jackrabbit&#x2019;s AccessControlProvider implementations is no longer supported with Oak. Since there are no permissions installed by default this flag has become superfluous.</p>
+<li><tt>USER_MANAGEMENT</tt>: if set permissions for user related items will be evaluated the same way as regular JCR items irrespective of their protection status.</li>
+</ul></div>
+<div class="section">
+<h5>Differences to Jackrabbit 2.x<a name="Differences_to_Jackrabbit_2.x"></a></h5>
+<p>The <tt>omit-default-permission</tt> configuration option present with the Jackrabbit&#x2019;s AccessControlProvider implementations is no longer supported with Oak. Since there are no permissions installed by default this flag has become superfluous.</p></div></div></div>
 <div class="section">
-<h4>Write Custom Permission Evaluation<a name="Write_Custom_Permission_Evaluation"></a></h4>
-<p><i>todo</i></p>
-<!-- references --></div></div></div>
+<h3>Pluggability<a name="Pluggability"></a></h3>
+<p>There are two ways for plugging permission related custom implementations:</p>
+
+<ol style="list-style-type: decimal">
+  
+<li>replace <tt>AuthorizationConfiguration</tt>: if you want to completely replace the way  authorization is handled in the repository. In OSGi-base setup this is achieved  by making the configuration implementation a service. In a non-OSGi-base setup the  custom configuration must be exposed by the <tt>SecurityProvider</tt> implementation.</li>
+  
+<li>extend <tt>AuthorizationConfiguration</tt>: it is planned to provide a <tt>CompositeAuthorizationConfiguration</tt>  that allows to aggregate different authorization implementations (see <a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-1268">OAK-1268</a>).</li>
+</ol>
+<!-- references --></div></div>
                   </div>
             </div>
           </div>

Modified: jackrabbit/site/live/oak/docs/security/permission/differences.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/permission/differences.html?rev=1595256&r1=1595255&r2=1595256&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/permission/differences.html (original)
+++ jackrabbit/site/live/oak/docs/security/permission/differences.html Fri May 16 16:36:00 2014
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2014-05-14
+ | Generated by Apache Maven Doxia at 2014-05-16
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <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="20140514" />
+    <meta name="Date-Revision-yyyymmdd" content="20140516" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Jackrabbit Oak - Permissions : Differences wrt Jackrabbit 2.x</title>
     <link rel="stylesheet" href="../../css/apache-maven-fluido-1.3.0.min.css" />
@@ -163,7 +163,7 @@
         <ul class="breadcrumb">
                 
                     
-                  <li id="publishDate">Last Published: 2014-05-14</li>
+                  <li id="publishDate">Last Published: 2014-05-16</li>
                   <li class="divider">|</li> <li id="projectVersion">Version: 0.20-SNAPSHOT</li>
                       
                 
@@ -382,9 +382,16 @@
 <h3>Permissions : Differences wrt Jackrabbit 2.x<a name="Permissions_:_Differences_wrt_Jackrabbit_2.x"></a></h3>
 <div class="section">
 <h4>General Notes<a name="General_Notes"></a></h4>
-<p><i>todo</i></p>
+<p>The permission evaluation as present in Oak 1.0 differs from Jackrabbit 2.x in two fundamental aspects:</p>
+
+<ol style="list-style-type: decimal">
+  
+<li>Permission evaluation has been completely separated from the access control  content and is executed based on the information stored in the permission store.</li>
+  
+<li>Each JCR <tt>Session</tt> (or Oak <tt>ContentSession</tt>) gets it&#x2019;s own <tt>PermissionProvider</tt>  associated with the current repository revision the session is operating on.</li>
+</ol></div>
 <div class="section">
-<h5>Permissions<a name="Permissions"></a></h5>
+<h4>Permissions<a name="Permissions"></a></h4>
 <p>The following permissions are now an aggregation of new permissions:</p>
 
 <ul>
@@ -400,39 +407,29 @@
 <li><tt>USER_MANAGEMENT</tt>: permission to execute user management related tasks such as e.g. creating or removing user/group, changing user password and editing group membership.</li>
   
 <li><tt>INDEX_DEFINITION_MANAGEMENT</tt>: permission to create, modify and remove the oak:index node and it&#x2019;s subtree which is expected to contain the index definitions.</li>
-</ul></div></div>
+</ul></div>
 <div class="section">
-<h4>Permission Evaluation<a name="Permission_Evaluation"></a></h4>
+<h4>Evaluation<a name="Evaluation"></a></h4>
 <div class="section">
 <h5>Reading<a name="Reading"></a></h5>
 <p>The only break in terms of backwards compatibility is the accessibility of version content underneath <tt>/jcr:system/jcr:versionStore</tt>. As of Oak the access to version content depends on the read permissions present with the versionable node while Jackrabbit 2.x doesn&#x2019;t apply any special rule. These changes are covered by <a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-444">OAK-444</a> and address the concerns summarized in <a class="externalLink" href="https://issues.apache.org/jira/browse/JCR-2963">JCR-2963</a>.</p></div>
 <div class="section">
-<h5>Property Modification<a name="Property_Modification"></a></h5>
-<p>Since Oak the former <tt>SET_PROPERTY</tt> permission has been split such to allow for more fined grained control on writing JCR properties. In particular Oak clearly distinguishes between creating a new property that didn&#x2019;t exist before, modifying or removing an existing property.</p></div>
-<div class="section">
 <h5>Node Removal<a name="Node_Removal"></a></h5>
-<p>As of Oak <tt>Node#remove()</tt> only requires sufficient permissions to remove the target node. In contrast to Jackrabbit 2.x the validation will not traverse the tree and verify remove permission on all child nodes/properties. In order to obtain backwards compatible behavior with respect to tree removal the permission evaluation can be configured to traverse down the hierarchy upon removal. This config flag is a best effort approach but doesn&#x2019;t guarantee an identical behavior.</p></div>
+<p>As of Oak <tt>Node#remove()</tt> only requires sufficient permissions to remove the target node. In contrast to Jackrabbit 2.x the validation will not traverse the tree and verify remove permission on all child nodes/properties.</p>
+<p>In order to obtain backwards compatible behavior with respect to tree removal the permission evaluation can be configured to traverse down the hierarchy upon removal. This config flag is a best effort approach but doesn&#x2019;t guarantee an identical behavior.</p></div>
 <div class="section">
 <h5>Rename<a name="Rename"></a></h5>
 <p>Due to the nature of the diff mechanism in Oak it is not possible to distinguish between <tt>JackrabbitNode#rename</tt> and a move with subsequent reordering. Consequently the permission evaluation will no longer apply the special handling for the renaming as it was present in Jackrabbit 2.x (renaming just required the ability to modify the child collection of the parent node).</p></div>
 <div class="section">
 <h5>Move<a name="Move"></a></h5>
-<p>Due to the nature of the diff mechanism in Oak it is no longer possible to treat move operations the same way as it was implemented in Jackrabbit 2.x. The current permission evaluation attempts to provide a best-effort handling to achieve a similar behavior that it was present in Jackrabbit 2.x.</p>
-<p>The current implementation has the following limitations with respect to multiple move operations within a given set of transient operations:</p>
-
-<ul>
-  
-<li>Move operations that replace an node that has been moved away will not be detected as modification by the diff mechanism and regular permission checks for on the subtree will be performed.</li>
-  
-<li>Moving an ancestor of a node that has been moved will only detect the second move and will enforce regular permissions checks on the child that has been moved in a first step.</li>
-</ul>
+<p>Due to the nature of the diff mechanism in Oak it is no longer possible to treat move operations the same way as it was implemented in Jackrabbit 2.x.</p>
 <p>For API consumers and applications running on Jackrabbit Oak this means that combinations of multiple moves can not always be properly resolved. Consequently permissions will be evaluated as if the modifications did not include move (in general being more restrictive): If the move leads to changes that are detected by the diff mechanism, regular permissions will be evaluated for all items that appear to be added, removed or modified, while a regular move operations just requires <tt>REMOVE_NODE</tt> permission on the source, <tt>ADD_NODE</tt> and <tt>NODE_TYPE_MANAGEMENT</tt> permissions at the destination.</p></div>
 <div class="section">
 <h5>User Management<a name="User_Management"></a></h5>
 <p>By default user management operations require the specific user mgt related permission to be granted for the editing subject. This permission (including a corresponding privilege) has been introduced with Oak 1.0. For backwards compatibility with Jackrabbit 2.x this behavior can be turned off by setting the corresponding configuration flag.</p></div>
 <div class="section">
 <h5>Version Management<a name="Version_Management"></a></h5>
-<p>Reading and writing items in the version store does not follow the regular permission evaluation but depends on access rights present on the corresponding versionable node. In case the version information does no longer have a versionable node in this workspace that original path is used to evaluate the effective permissions that would apply to that node if the version was restored. Note, that as in Jackrabbit VERSION_MANAGEMENT permission instead of the regular JCR write permissions is required in order to execute version operations and thus modify the version store. These changes are covered by <a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-444">OAK-444</a> and address the concerns summarized in <a class="externalLink" href="https://issues.apache.org/jira/browse/JCR-2963">JCR-2963</a>.</p>
+<p>Reading items in the version store depends on access rights present on the corresponding versionable node. In case the version information does no longer have a versionable node in this workspace that original path is used to evaluate the effective permissions that would apply to that node if the version was restored. This changes is covered by <a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-444">OAK-444</a> and addresses concerns summarized in <a class="externalLink" href="https://issues.apache.org/jira/browse/JCR-2963">JCR-2963</a>.</p>
 <!-- hidden references --></div></div></div></div>
                   </div>
             </div>

Modified: jackrabbit/site/live/oak/docs/security/permission/evaluation.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/permission/evaluation.html?rev=1595256&r1=1595255&r2=1595256&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/permission/evaluation.html (original)
+++ jackrabbit/site/live/oak/docs/security/permission/evaluation.html Fri May 16 16:36:00 2014
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2014-05-14
+ | Generated by Apache Maven Doxia at 2014-05-16
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <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="20140514" />
+    <meta name="Date-Revision-yyyymmdd" content="20140516" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Jackrabbit Oak - Permission Evaluation in Detail</title>
     <link rel="stylesheet" href="../../css/apache-maven-fluido-1.3.0.min.css" />
@@ -163,7 +163,7 @@
         <ul class="breadcrumb">
                 
                     
-                  <li id="publishDate">Last Published: 2014-05-14</li>
+                  <li id="publishDate">Last Published: 2014-05-16</li>
                   <li class="divider">|</li> <li id="projectVersion">Version: 0.20-SNAPSHOT</li>
                       
                 
@@ -381,51 +381,75 @@
 <h2>Permission Evaluation in Detail<a name="Permission_Evaluation_in_Detail"></a></h2>
 <div class="section">
 <h3>General Remarks<a name="General_Remarks"></a></h3>
-<p><i>todo</i></p></div>
+<p>As of Oak 1.0 Permission evaluation is completely separated from the access control content and is executed based on the information stored in the permission store. The latter is kept in sync with the access control information using dedicated <tt>CommitHook</tt> implementation ([PermissionHook]). The evaluation itself is done by the configured <tt>PermissionProvider</tt> that read and evaluates the information stored in the permission store.</p>
+<p>Each JCR <tt>Session</tt> (or Oak <tt>ContentSession</tt>) gets it&#x2019;s own <tt>PermissionProvider</tt> associated with the current repository revision the session is operating on. Consequently, the evaluated permissions and caches are not shared between different sessions even if they represent the same subject.</p>
+<div class="section">
+<h4>Evaluation of Permission Entries<a name="Evaluation_of_Permission_Entries"></a></h4>
+<p><i>todo</i></p></div></div>
 <div class="section">
 <h3>Overview on Permission Evaluation<a name="Overview_on_Permission_Evaluation"></a></h3>
-<p><i>todo</i></p></div>
 <div class="section">
-<h3>Administrative Access<a name="Administrative_Access"></a></h3>
+<h4><a name="permissionStore"></a> The Permission Store<a name="The_Permission_Store"></a></h4>
 <p><i>todo</i></p></div>
 <div class="section">
-<h3>Individual Permissions in Detail<a name="Individual_Permissions_in_Detail"></a></h3>
-<div class="section">
-<div class="section">
-<h5>Reading<a name="Reading"></a></h5>
-<p>Due to the fine grained read permissions Oak read access can be separately granted/denied for nodes and properties. See also the section about extended <a href="../accesscontrol/restriction.html">Restriction Management</a>. Granting the <tt>jcr:read</tt> privilege will result in a backwards compatible read access for nodes and their properties, while specifying <tt>rep:readNodes</tt> or <tt>rep:readProperties</tt> privileges allows separately granting or denying access to nodes and properties (see also <a href="../privilege.html">Privilege Management</a> for changes in the privilege definitions). Together with the restrictions this new behavior now allows to individually grant/deny access to properties that match a given name/path/nodetype (and as a possible extension even property value).</p>
-<p>The only break in terms of backwards compatibility is the accessibility of version content underneath <tt>/jcr:system/jcr:versionStore</tt>. As of Oak the access to version content depends on the read permissions present with the versionable node while Jackrabbit 2.x doesn&#x2019;t apply any special rule. These changes are covered by <a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-444">OAK-444</a> and address the concerns summarized in <a class="externalLink" href="https://issues.apache.org/jira/browse/JCR-2963">JCR-2963</a>.</p></div>
+<h4><a name="PermissionProvider"></a> PermissionProvider</h4>
+<p><i>todo</i></p></div>
 <div class="section">
-<h5>Property Modification<a name="Property_Modification"></a></h5>
-<p>Since Oak the former <tt>SET_PROPERTY</tt> permission has been split such to allow for more fined grained control on writing JCR properties. In particular Oak clearly distinguishes between creating a new property that didn&#x2019;t exist before, modifying or removing an existing property. This will allow to cover those cases where a given subject is only allowed to create content but doesn&#x2019;t have the ability to modify/delete it later on.</p></div>
+<h4><a name="SecureNodeBuilder"></a> SecureNodeBuilder</h4>
+<p><i>todo</i></p></div>
 <div class="section">
-<h5>Node Removal<a name="Node_Removal"></a></h5>
-<p>As of Oak <tt>Node#remove()</tt> only requires sufficient permissions to remove the target node. In contrast to Jackrabbit 2.x the validation will not traverse the tree and verify remove permission on all child nodes/properties. In order to obtain backwards compatible behavior with respect to tree removal the permission evaluation can be configured to traverse down the hierarchy upon removal. This config flag is a best effort approach but doesn&#x2019;t guarantee an identical behavior.</p></div>
+<h4><a name="getTreePermission"></a> TreePermission<a name="TreePermission"></a></h4>
+<p><i>todo</i></p></div>
 <div class="section">
-<h5>Rename<a name="Rename"></a></h5>
-<p>Due to the nature of the diff mechanism in Oak it is not possible to distinguish between <tt>JackrabbitNode#rename</tt> and a move with subsequent reordering. Consequently the permission evaluation will no longer apply the special handling for the renaming as it was present in Jackrabbit 2.x (renaming just required the ability to modify the child collection of the parent node).</p></div>
+<h4><a name="getEntryIterator"></a> PermissionEntry Iterator<a name="PermissionEntry_Iterator"></a></h4>
+<p><i>todo</i></p></div>
 <div class="section">
-<h5>Move<a name="Move"></a></h5>
-<p>Due to the nature of the diff mechanism in Oak it is no longer possible to treat move operations the same way as it was implemented in Jackrabbit 2.x. The current permission evaluation attempts to provide a best-effort handling to achieve a similar behavior that it was present in Jackrabbit 2.x.</p>
-<p>The current implementation has the following limitations with respect to multiple move operations within a given set of transient operations:</p>
+<h4>Reading a Node : Step by Step<a name="Reading_a_Node_:_Step_by_Step"></a></h4>
+<p>The following section describes what happens on <tt>session.getNode(&quot;/foo&quot;).getProperty(&quot;jcr:title&quot;)</tt> in terms of permission evaluation:</p>
 
-<ul>
+<ol style="list-style-type: decimal">
+  
+<li>
+<p><tt>SessionImpl.getNode()</tt> internally calls <tt>SessionDelegate.getNode()</tt>  which calls <tt>Root.getTree()</tt> which calls <tt>Tree.getTree()</tt> on the <tt>/foo</tt> tree.  This creates a bunch of linked <tt>MutableTree</tt> objects.</p></li>
+  
+<li>
+<p>The session delegate then checks if the tree really exists, by calling <tt>Tree.exists()</tt>  which then calls <tt>NodeBuilder.exists()</tt>.</p></li>
+  
+<li>
+<p>If the session performing the operation is an <i>admin</i> session, then the node builder from  the persistence layer is directly used. In all other cases, the original node builder  is wrapped by a <tt>SecureNodeBuilder</tt>. The <tt>SecureNodeBuilder</tt> performs permission  checks before delegating the calls to the delegated builder.</p></li>
   
-<li>Move operations that replace an node that has been moved away will not be detected as modification by the diff mechanism and regular permission checks for on the subtree will be performed.</li>
+<li>
+<p>For non <i>admin</i> sessions the <tt>SecureNodeBuilder</tt> fetches its <i>tree permissions</i> via  <tt>getTreePermission()</tt> (See <a href="#getTreePermission">below</a> of how this works) and then  calls <tt>TreePermission.canRead()</tt>. This method (signature with no arguments) checks the  <tt>READ_NODE</tt> permission for normal trees (as in this example) or the <tt>READ_ACCESS_CONTROL</tt>  permission on <i>AC trees</i> [^1] and remembers the result in the <tt>ReadStatus</tt>.</p>
+<p>For that an iterator of the <i>permission entries</i> is <a href="#getEntryIterator">retrieved</a> which  provides all the relevant permission entries needed to be evaluated for this tree (and  and set of principals associated with the permission provider).</p></li>
   
-<li>Moving an ancestor of a node that has been moved will only detect the second move and will enforce regular permissions checks on the child that has been moved in a first step.</li>
-</ul>
-<p>For API consumers and applications running on Jackrabbit Oak this means that combinations of multiple moves can not always be properly resolved. Consequently permissions will be evaluated as if the modifications did not include move (in general being more restrictive): If the move leads to changes that are detected by the diff mechanism, regular permissions will be evaluated for all items that appear to be added, removed or modified, while a regular move operations just requires <tt>REMOVE_NODE</tt> permission on the source, <tt>ADD_NODE</tt> and <tt>NODE_TYPE_MANAGEMENT</tt> permissions at the destination.</p></div>
-<div class="section">
-<h5>User Management<a name="User_Management"></a></h5>
-<p>By default user management operations require the specific user mgt related permission to be granted for the editing subject. This permission (including a corresponding privilege) has been introduced with Oak 1.0. For backwards compatibility with Jackrabbit 2.x this behavior can be turned off by setting the corresponding configuration flag.</p></div>
-<div class="section">
-<h5>Version Management<a name="Version_Management"></a></h5>
-<p>Reading and writing items in the version store does not follow the regular permission evaluation but depends on access rights present on the corresponding versionable node. In case the version information does no longer have a versionable node in this workspace that original path is used to evaluate the effective permissions that would apply to that node if the version was restored. Note, that as in Jackrabbit VERSION_MANAGEMENT permission instead of the regular JCR write permissions is required in order to execute version operations and thus modify the version store. These changes are covered by <a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-444">OAK-444</a> and address the concerns summarized in <a class="externalLink" href="https://issues.apache.org/jira/browse/JCR-2963">JCR-2963</a>.</p></div>
-<div class="section">
-<h5>Query Index Definitions<a name="Query_Index_Definitions"></a></h5>
-<p>Writing query index definitions requires the specific index definition management which is enforce on nodes named &#x201c;oak:index&#x201d; and the subtree defined by them. Note that the corresponding items are not protected in the JCR sense. Consequently any other modification in these subtrees like e.g. changing the primary type or adding mixin types is governed by the corresponding privileges.</p>
-<!-- hidden references --></div></div></div></div>
+<li>
+<p>The <i>permission entries</i> are analyzed if they include the respective permission and if so,  the read status is set accordingly. Note that the sequence of the permission entries from  the iterator is already in the correct order for this kind of evaluation. this is ensured  by the way how they are stored in the <a href="#permissionStore">permission store</a> and how they  are feed into the iterator.</p>
+<p>The iteration also detects if the evaluated permission entries cover <i>this</i> node and all  its properties. If this is the case, subsequent calls that evaluate the property read  permissions would then not need to do the same iteration again. In order to detect this,  the iteration checks if a non-matching permission entry or privilege was skipped  and eventually sets the respective flag in the <tt>ReadStatus</tt>. This flag indicates if the  present permission entries are sufficient to tell if the session is allowed to read  <i>this</i> node and all its properties. If there are more entries present than the ones needed  for evaluating the <tt>READ_NODE</tt> permission, then it&#x2019;s ambiguous to determine if all  properties can be read.</p></li>
+  
+<li>
+<p>Once the <tt>ReadStatus</tt> is calculated (or was calculated earlier) the <tt>canRead()</tt> method  returns <tt>ReadStatus.allowsThis()</tt> which specifies if <i>this</i> node is allowed to be read.</p></li>
+</ol>
+<p>[^1]: by default access control content is stored in the <tt>rep:policy</tt> subtree of an access controlled node.</p></div>
+<div class="section">
+<h4>Reading an Property : Step by Step<a name="Reading_an_Property_:_Step_by_Step"></a></h4>
+
+<ol style="list-style-type: decimal">
+  
+<li><i>todo</i></li>
+</ol></div>
+<div class="section">
+<h4>Adding a Node : Step by Step<a name="Adding_a_Node_:_Step_by_Step"></a></h4>
+<p><i>todo</i></p></div>
+<div class="section">
+<h4>Changing a Property : Step by Step<a name="Changing_a_Property_:_Step_by_Step"></a></h4>
+<p><i>todo</i></p></div>
+<div class="section">
+<h4>Locking a Node : Step by Step<a name="Locking_a_Node_:_Step_by_Step"></a></h4>
+<p><i>todo</i></p></div>
+<div class="section">
+<h4>Registering a Node Type : Step by Step<a name="Registering_a_Node_Type_:_Step_by_Step"></a></h4>
+<p><i>todo</i></p>
+<!-- hidden references --></div></div></div>
                   </div>
             </div>
           </div>

Modified: jackrabbit/site/live/oak/docs/security/principal.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/principal.html?rev=1595256&r1=1595255&r2=1595256&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/principal.html (original)
+++ jackrabbit/site/live/oak/docs/security/principal.html Fri May 16 16:36:00 2014
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2014-05-14
+ | Generated by Apache Maven Doxia at 2014-05-15
  | Rendered using Apache Maven Fluido Skin 1.3.0
 -->
 <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="20140514" />
+    <meta name="Date-Revision-yyyymmdd" content="20140515" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Jackrabbit Oak - Principal Management</title>
     <link rel="stylesheet" href="../css/apache-maven-fluido-1.3.0.min.css" />
@@ -163,7 +163,7 @@
         <ul class="breadcrumb">
                 
                     
-                  <li id="publishDate">Last Published: 2014-05-14</li>
+                  <li id="publishDate">Last Published: 2014-05-15</li>
                   <li class="divider">|</li> <li id="projectVersion">Version: 0.20-SNAPSHOT</li>
                       
                 
@@ -424,9 +424,10 @@
 <li>make the configuration implementation an OSGi service and make it available to the Oak repository.</li>
 </ul>
 <div class="section">
-<h4>Examples<a name="Examples"></a></h4>
 <div class="section">
-<h5>Custom PrincipalConfiguration<a name="Custom_PrincipalConfiguration"></a></h5>
+<h5>Examples<a name="Examples"></a></h5>
+<div class="section">
+<h6>Custom PrincipalConfiguration<a name="Custom_PrincipalConfiguration"></a></h6>
 
 <div class="source">
 <pre> @Component()
@@ -470,7 +471,7 @@
  }
 </pre></div></div>
 <div class="section">
-<h5>Custom PrincipalProvider<a name="Custom_PrincipalProvider"></a></h5>
+<h6>Custom PrincipalProvider<a name="Custom_PrincipalProvider"></a></h6>
 
 <div class="source">
 <pre> final class MyPrincipalProvider implements PrincipalProvider {
@@ -482,7 +483,7 @@
      ...
  }
 </pre></div>
-<!-- references --></div></div></div></div>
+<!-- references --></div></div></div></div></div>
                   </div>
             </div>
           </div>



Mime
View raw message