jackrabbit-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mdue...@apache.org
Subject svn commit: r1594576 [3/8] - in /jackrabbit/site/live/oak/docs: ./ security/ security/accesscontrol/ security/authentication/ security/permission/ security/principal/ security/privilege/ security/user/
Date Wed, 14 May 2014 13:30:14 GMT
Added: jackrabbit/site/live/oak/docs/security/accesscontrol/restriction.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/accesscontrol/restriction.html?rev=1594576&view=auto
==============================================================================
--- jackrabbit/site/live/oak/docs/security/accesscontrol/restriction.html (added)
+++ jackrabbit/site/live/oak/docs/security/accesscontrol/restriction.html Wed May 14 13:30:13 2014
@@ -0,0 +1,560 @@
+<!DOCTYPE html>
+<!--
+ | Generated by Apache Maven Doxia at 2014-05-14
+ | 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 http-equiv="Content-Language" content="en" />
+    <title>Jackrabbit Oak - Restriction Management</title>
+    <link rel="stylesheet" href="../../css/apache-maven-fluido-1.3.0.min.css" />
+    <link rel="stylesheet" href="../../css/site.css" />
+    <link rel="stylesheet" href="../../css/print.css" media="print" />
+
+      
+    <script type="text/javascript" src="../../js/apache-maven-fluido-1.3.0.min.js"></script>
+
+    
+            </head>
+        <body class="topBarEnabled">
+          
+    
+    
+            
+    
+    
+    <a href="http://github.com/apache/jackrabbit-oak">
+      <img style="position: absolute; top: 0; right: 0; border: 0; z-index: 10000;"
+        src="https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png"
+        alt="Fork me on GitHub">
+    </a>
+  
+                
+                    
+                
+
+    <div id="topbar" class="navbar navbar-fixed-top ">
+      <div class="navbar-inner">
+                <div class="container-fluid">
+        <a data-target=".nav-collapse" data-toggle="collapse" class="btn btn-navbar">
+          <span class="icon-bar"></span>
+          <span class="icon-bar"></span>
+          <span class="icon-bar"></span>
+        </a>
+                
+                                <ul class="nav">
+                          <li class="dropdown">
+        <a href="#" class="dropdown-toggle" data-toggle="dropdown">Overview <b class="caret"></b></a>
+        <ul class="dropdown-menu">
+        
+                      <li>      <a href="../../index.html"  title="Jackrabbit Oak">Jackrabbit Oak</a>
+</li>
+                  
+                      <li>      <a href="../../license.html"  title="License">License</a>
+</li>
+                  
+                      <li>      <a href="../../downloads.html"  title="Downloads">Downloads</a>
+</li>
+                          </ul>
+      </li>
+                <li class="dropdown">
+        <a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts and architecture <b class="caret"></b></a>
+        <ul class="dropdown-menu">
+        
+                      <li>      <a href="../../overview.html"  title="Overview">Overview</a>
+</li>
+                  
+                      <li>      <a href="../../nodestate.html"  title="The node state model">The node state model</a>
+</li>
+                  
+                      <li>      <a href="../../microkernel.html"  title="NodeStore and MicroKernel">NodeStore and MicroKernel</a>
+</li>
+                  
+                      <li>      <a href="../../query.html"  title="Query">Query</a>
+</li>
+                  
+                      <li>      <a href="../../blobstore.html"  title="BlobStore">BlobStore</a>
+</li>
+                  
+                      <li>      <a href="../../security/overview.html"  title="Security">Security</a>
+</li>
+                  
+                      <li>      <a href="../../clustering.html"  title="Clustering">Clustering</a>
+</li>
+                          </ul>
+      </li>
+                <li class="dropdown">
+        <a href="#" class="dropdown-toggle" data-toggle="dropdown">Using Oak <b class="caret"></b></a>
+        <ul class="dropdown-menu">
+        
+                      <li>      <a href="../../use_getting_started.html"  title="Getting Started">Getting Started</a>
+</li>
+                  
+                      <li>      <a href="../../construct.html"  title="Repository construction">Repository construction</a>
+</li>
+                  
+                      <li>      <a href="../../osgi_config.html"  title="Configuring Oak">Configuring Oak</a>
+</li>
+                  
+                      <li>      <a href="../../differences.html"  title="Differences to Jackrabbit 2">Differences to Jackrabbit 2</a>
+</li>
+                  
+                      <li>      <a href="../../known_issues.html"  title="Known Issues">Known Issues</a>
+</li>
+                  
+                      <li>      <a href="../../dos_and_donts.html"  title="Dos and don'ts">Dos and don'ts</a>
+</li>
+                  
+                      <li>      <a href="../../FAQ.html"  title="FAQ">FAQ</a>
+</li>
+                          </ul>
+      </li>
+                <li class="dropdown">
+        <a href="#" class="dropdown-toggle" data-toggle="dropdown">Developing Oak <b class="caret"></b></a>
+        <ul class="dropdown-menu">
+        
+                      <li>      <a href="../../dev_getting_started.html"  title="Getting Started">Getting Started</a>
+</li>
+                  
+                      <li>      <a href="../../participating.html"  title="Participating">Participating</a>
+</li>
+                  
+                      <li>      <a href="../../apidocs/index.html"  title="API docs">API docs</a>
+</li>
+                          </ul>
+      </li>
+                <li class="dropdown">
+        <a href="#" class="dropdown-toggle" data-toggle="dropdown">Links <b class="caret"></b></a>
+        <ul class="dropdown-menu">
+        
+                      <li>      <a href="http://jackrabbit.apache.org/oak"  title="Apache Jackrabbit Oak">Apache Jackrabbit Oak</a>
+</li>
+                  
+                      <li>      <a href="http://jackrabbit.apache.org/"  title="Apache Jackrabbit">Apache Jackrabbit</a>
+</li>
+                          </ul>
+      </li>
+                  </ul>
+          
+          
+          
+                   
+                      </div>
+          
+        </div>
+      </div>
+    </div>
+    
+        <div class="container-fluid">
+          <div id="banner">
+        <div class="pull-left">
+                                <div id="bannerLeft">
+                <h2>Oak Documentation</h2>
+                </div>
+                      </div>
+        <div class="pull-right">  </div>
+        <div class="clear"><hr/></div>
+      </div>
+
+      <div id="breadcrumbs">
+        <ul class="breadcrumb">
+                
+                    
+                  <li id="publishDate">Last Published: 2014-05-14</li>
+                  <li class="divider">|</li> <li id="projectVersion">Version: 0.20-SNAPSHOT</li>
+                      
+                
+                    
+      
+                            </ul>
+      </div>
+
+            
+      <div class="row-fluid">
+        <div id="leftColumn" class="span3">
+          <div class="well sidebar-nav">
+                
+                    
+                <ul class="nav nav-list">
+                    <li class="nav-header">Overview</li>
+                                
+      <li>
+    
+                          <a href="../../index.html" title="Jackrabbit Oak">
+          <i class="none"></i>
+        Jackrabbit Oak</a>
+            </li>
+                  
+      <li>
+    
+                          <a href="../../license.html" title="License">
+          <i class="none"></i>
+        License</a>
+            </li>
+                  
+      <li>
+    
+                          <a href="../../downloads.html" title="Downloads">
+          <i class="none"></i>
+        Downloads</a>
+            </li>
+                              <li class="nav-header">Concepts and architecture</li>
+                                
+      <li>
+    
+                          <a href="../../overview.html" title="Overview">
+          <i class="none"></i>
+        Overview</a>
+            </li>
+                  
+      <li>
+    
+                          <a href="../../nodestate.html" title="The node state model">
+          <i class="none"></i>
+        The node state model</a>
+            </li>
+                  
+      <li>
+    
+                          <a href="../../microkernel.html" title="NodeStore and MicroKernel">
+          <i class="none"></i>
+        NodeStore and MicroKernel</a>
+            </li>
+                  
+      <li>
+    
+                          <a href="../../query.html" title="Query">
+          <i class="none"></i>
+        Query</a>
+            </li>
+                  
+      <li>
+    
+                          <a href="../../blobstore.html" title="BlobStore">
+          <i class="none"></i>
+        BlobStore</a>
+            </li>
+                  
+      <li>
+    
+                          <a href="../../security/overview.html" title="Security">
+          <i class="none"></i>
+        Security</a>
+            </li>
+                  
+      <li>
+    
+                          <a href="../../clustering.html" title="Clustering">
+          <i class="none"></i>
+        Clustering</a>
+            </li>
+                              <li class="nav-header">Using Oak</li>
+                                
+      <li>
+    
+                          <a href="../../use_getting_started.html" title="Getting Started">
+          <i class="none"></i>
+        Getting Started</a>
+            </li>
+                  
+      <li>
+    
+                          <a href="../../construct.html" title="Repository construction">
+          <i class="none"></i>
+        Repository construction</a>
+            </li>
+                  
+      <li>
+    
+                          <a href="../../osgi_config.html" title="Configuring Oak">
+          <i class="none"></i>
+        Configuring Oak</a>
+            </li>
+                  
+      <li>
+    
+                          <a href="../../differences.html" title="Differences to Jackrabbit 2">
+          <i class="none"></i>
+        Differences to Jackrabbit 2</a>
+            </li>
+                  
+      <li>
+    
+                          <a href="../../known_issues.html" title="Known Issues">
+          <i class="none"></i>
+        Known Issues</a>
+            </li>
+                  
+      <li>
+    
+                          <a href="../../dos_and_donts.html" title="Dos and don'ts">
+          <i class="none"></i>
+        Dos and don'ts</a>
+            </li>
+                  
+      <li>
+    
+                          <a href="../../FAQ.html" title="FAQ">
+          <i class="none"></i>
+        FAQ</a>
+            </li>
+                              <li class="nav-header">Developing Oak</li>
+                                
+      <li>
+    
+                          <a href="../../dev_getting_started.html" title="Getting Started">
+          <i class="none"></i>
+        Getting Started</a>
+            </li>
+                  
+      <li>
+    
+                          <a href="../../participating.html" title="Participating">
+          <i class="none"></i>
+        Participating</a>
+            </li>
+                  
+      <li>
+    
+                          <a href="../../apidocs/index.html" title="API docs">
+          <i class="none"></i>
+        API docs</a>
+            </li>
+                              <li class="nav-header">Links</li>
+                                
+      <li>
+    
+                          <a href="http://jackrabbit.apache.org/oak" class="externalLink" title="Apache Jackrabbit Oak">
+          <i class="none"></i>
+        Apache Jackrabbit Oak</a>
+            </li>
+                  
+      <li>
+    
+                          <a href="http://jackrabbit.apache.org/" class="externalLink" title="Apache Jackrabbit">
+          <i class="none"></i>
+        Apache Jackrabbit</a>
+            </li>
+            </ul>
+                
+                    
+                
+          <hr class="divider" />
+
+           <div id="poweredBy">
+                   
+    <script type="text/javascript" src="https://apis.google.com/js/plusone.js"></script>
+
+    
+    <div class="g-plusone" data-href="http://jackrabbit.apache.org/oak-doc/" data-size="tall" ></div>
+
+                   <div class="clear"></div>
+                            <div class="clear"></div>
+                            <div class="clear"></div>
+                             <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+        <img class="builtBy" alt="Built by Maven" src="../../images/logos/maven-feather.png" />
+      </a>
+                  </div>
+          </div>
+        </div>
+        
+                
+        <div id="bodyColumn"  class="span9" >
+                                  
+            <!-- Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   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">
+<h2>Restriction Management<a name="Restriction_Management"></a></h2>
+<div class="section">
+<h3>Overview<a name="Overview"></a></h3>
+<p><i>todo</i></p></div>
+<div class="section">
+<h3>Restriction API<a name="Restriction_API"></a></h3>
+<p>The following public interfaces are provided by Oak in the package <tt>org.apache.jackrabbit.oak.spi.security.authorization.restriction</tt>:</p>
+
+<ul>
+  
+<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/restriction/RestrictionProvider.html">RestrictionProvider</a></li>
+  
+<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/restriction/Restriction.html">Restriction</a></li>
+  
+<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/restriction/RestrictionDefinition.html">RestrictionDefinition</a></li>
+  
+<li><a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/restriction/RestrictionPattern.html">RestrictionPattern</a></li>
+</ul></div>
+<div class="section">
+<h3>Default Implementation<a name="Default_Implementation"></a></h3>
+<p>Oak 1.0 provides the following base implementations:</p>
+
+<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.</li>
+  
+<li><tt>CompositePattern</tt>: Allows to aggregate multiple restriction patterns.</li>
+</ul>
+<div class="section">
+<h4>Changes wrt Jackrabbit 2.x<a name="Changes_wrt_Jackrabbit_2.x"></a></h4>
+<p><i>todo</i></p></div>
+<div class="section">
+<h4>Built-in Restriction Implementations<a name="Built-in_Restriction_Implementations"></a></h4>
+<p>The default implementations of the <tt>Restriction</tt> interface are present with Oak 1.0 access control management:</p>
+
+<ul>
+  
+<li><tt>rep:glob</tt>:</li>
+  
+<li><tt>rep:ntNames</tt>:</li>
+  
+<li><tt>rep:prefixes</tt>:</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 <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>
+  
+<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>
+<div class="section">
+<h4>Examples<a name="Examples"></a></h4>
+<div class="section">
+<h5>Example RestrictionProvider<a name="Example_RestrictionProvider"></a></h5>
+<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 class="source">
+<pre>@Component
+@Service(RestrictionProvider.class)
+public class MyRestrictionProvider extends AbstractRestrictionProvider {
+
+    public MyRestrictionProvider() {
+        super(supportedRestrictions());
+    }
+
+    private static Map&lt;String, RestrictionDefinition&gt; supportedRestrictions() {
+        RestrictionDefinition dates = new RestrictionDefinitionImpl(&quot;dates&quot;, Type.DATES, false);
+        return Collections.singletonMap(dates.getName(), dates);
+    }
+
+    //------------------------------------------------&lt; RestrictionProvider &gt;---
+
+    @Override
+    public RestrictionPattern getPattern(String oakPath, Tree tree) {
+        if (oakPath != null) {
+            PropertyState property = tree.getProperty(&quot;dates&quot;);
+            if (property != null) {
+                return DatePattern.create(property);
+            }
+        }
+        return RestrictionPattern.EMPTY;
+    }
+
+    @Nonnull
+    @Override
+    public RestrictionPattern getPattern(@Nullable String oakPath, @Nonnull Set&lt;Restriction&gt; restrictions) {
+        if (oakPath != null) {
+            for (Restriction r : restrictions) {
+                String name = r.getDefinition().getName();
+                if (&quot;dates&quot;.equals(name)) {
+                    return DatePattern.create(r.getProperty());
+                }
+            }
+        }
+        return RestrictionPattern.EMPTY;
+    }
+
+    // TODO: implementing 'validateRestrictions(String oakPath, Tree aceTree)' would allow to make sure the property contains 2 date values.
+}
+</pre></div></div>
+<div class="section">
+<h5>Example RestrictionPattern<a name="Example_RestrictionPattern"></a></h5>
+<p>The time-based <tt>RestrictionPattern</tt> used by the example provider above.</p>
+
+<div class="source">
+<pre>class DatePattern implements RestrictionPattern {
+
+    private final Date start;
+    private final Date end;
+
+    private DatePattern(@Nonnull Calendar start, @Nonnull Calendar end) {
+        this.start = start.getTime();
+        this.end = end.getTime();
+    }
+
+    static RestrictionPattern create(PropertyState timeProperty) {
+        if (timeProperty.count() == 2) {
+            return new DatePattern(
+                    Conversions.convert(timeProperty.getValue(Type.DATE, 0), Type.DATE).toCalendar(),
+                    Conversions.convert(timeProperty.getValue(Type.DATE, 1), Type.DATE).toCalendar()
+            );
+        } else {
+            return RestrictionPattern.EMPTY;
+        }
+    }
+
+    @Override
+    public boolean matches(@Nonnull Tree tree, @Nullable PropertyState property) {
+        return matches();
+    }
+
+    @Override
+    public boolean matches(@Nonnull String path) {
+        return matches();
+    }
+
+    @Override
+    public boolean matches() {
+        Date d = new Date();
+        return d.after(start) &amp;&amp; d.before(end);
+    }
+};
+</pre></div>
+<!-- hidden references --></div></div></div></div>
+                  </div>
+            </div>
+          </div>
+
+    <hr/>
+
+    <footer>
+            <div class="container-fluid">
+              <div class="row span12">Copyright &copy;                    2012-2014
+                        <a href="http://www.apache.org/">The Apache Software Foundation</a>.
+            All Rights Reserved.      
+                    
+      </div>
+
+        
+        
+          
+    
+    
+    <div id="ohloh" class="pull-right">
+      <script type="text/javascript" src="http://www.ohloh.net/p/jackrabbit-oak/widgets/project_users_logo.js"></script>
+    </div>
+        </div>
+    </footer>
+  </body>
+</html>
\ No newline at end of file

Modified: jackrabbit/site/live/oak/docs/security/authentication.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/authentication.html?rev=1594576&r1=1594575&r2=1594576&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/authentication.html (original)
+++ jackrabbit/site/live/oak/docs/security/authentication.html Wed May 14 13:30:13 2014
@@ -1,15 +1,15 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2014-05-06
+ | Generated by Apache Maven Doxia at 2014-05-14
  | 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="20140506" />
+    <meta name="Date-Revision-yyyymmdd" content="20140514" />
     <meta http-equiv="Content-Language" content="en" />
-    <title>Jackrabbit Oak - The Oak Security Layer</title>
+    <title>Jackrabbit Oak - Authentication</title>
     <link rel="stylesheet" href="../css/apache-maven-fluido-1.3.0.min.css" />
     <link rel="stylesheet" href="../css/site.css" />
     <link rel="stylesheet" href="../css/print.css" media="print" />
@@ -58,9 +58,6 @@
                   
                       <li>      <a href="../downloads.html"  title="Downloads">Downloads</a>
 </li>
-                  
-                      <li>      <a href="../from_here.html"  title="From here">From here</a>
-</li>
                           </ul>
       </li>
                 <li class="dropdown">
@@ -73,7 +70,7 @@
                       <li>      <a href="../nodestate.html"  title="The node state model">The node state model</a>
 </li>
                   
-                      <li>      <a href="../microkernel.html"  title="NodesStore and MicroKernel">NodesStore and MicroKernel</a>
+                      <li>      <a href="../microkernel.html"  title="NodeStore and MicroKernel">NodeStore and MicroKernel</a>
 </li>
                   
                       <li>      <a href="../query.html"  title="Query">Query</a>
@@ -96,19 +93,22 @@
                       <li>      <a href="../use_getting_started.html"  title="Getting Started">Getting Started</a>
 </li>
                   
-                      <li>      <a href="../differences.html"  title="Differences to Jackrabbit 2">Differences to Jackrabbit 2</a>
+                      <li>      <a href="../construct.html"  title="Repository construction">Repository construction</a>
 </li>
                   
                       <li>      <a href="../osgi_config.html"  title="Configuring Oak">Configuring Oak</a>
 </li>
                   
+                      <li>      <a href="../differences.html"  title="Differences to Jackrabbit 2">Differences to Jackrabbit 2</a>
+</li>
+                  
                       <li>      <a href="../known_issues.html"  title="Known Issues">Known Issues</a>
 </li>
                   
                       <li>      <a href="../dos_and_donts.html"  title="Dos and don'ts">Dos and don'ts</a>
 </li>
                   
-                      <li>      <a href="../when_things_go_wrong.html"  title="When things go wrong">When things go wrong</a>
+                      <li>      <a href="../FAQ.html"  title="FAQ">FAQ</a>
 </li>
                           </ul>
       </li>
@@ -163,7 +163,7 @@
         <ul class="breadcrumb">
                 
                     
-                  <li id="publishDate">Last Published: 2014-05-06</li>
+                  <li id="publishDate">Last Published: 2014-05-14</li>
                   <li class="divider">|</li> <li id="projectVersion">Version: 0.20-SNAPSHOT</li>
                       
                 
@@ -201,13 +201,6 @@
           <i class="none"></i>
         Downloads</a>
             </li>
-                  
-      <li>
-    
-                          <a href="../from_here.html" title="From here">
-          <i class="none"></i>
-        From here</a>
-            </li>
                               <li class="nav-header">Concepts and architecture</li>
                                 
       <li>
@@ -226,9 +219,9 @@
                   
       <li>
     
-                          <a href="../microkernel.html" title="NodesStore and MicroKernel">
+                          <a href="../microkernel.html" title="NodeStore and MicroKernel">
           <i class="none"></i>
-        NodesStore and MicroKernel</a>
+        NodeStore and MicroKernel</a>
             </li>
                   
       <li>
@@ -269,9 +262,9 @@
                   
       <li>
     
-                          <a href="../differences.html" title="Differences to Jackrabbit 2">
+                          <a href="../construct.html" title="Repository construction">
           <i class="none"></i>
-        Differences to Jackrabbit 2</a>
+        Repository construction</a>
             </li>
                   
       <li>
@@ -283,6 +276,13 @@
                   
       <li>
     
+                          <a href="../differences.html" title="Differences to Jackrabbit 2">
+          <i class="none"></i>
+        Differences to Jackrabbit 2</a>
+            </li>
+                  
+      <li>
+    
                           <a href="../known_issues.html" title="Known Issues">
           <i class="none"></i>
         Known Issues</a>
@@ -297,9 +297,9 @@
                   
       <li>
     
-                          <a href="../when_things_go_wrong.html" title="When things go wrong">
+                          <a href="../FAQ.html" title="FAQ">
           <i class="none"></i>
-        When things go wrong</a>
+        FAQ</a>
             </li>
                               <li class="nav-header">Developing Oak</li>
                                 
@@ -377,34 +377,31 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    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. --><h1>The Oak Security Layer</h1>
+   limitations under the License. --><div class="section">
+<h2>Authentication<a name="Authentication"></a></h2>
 <div class="section">
-<h2>Authentication and Login Modules<a name="Authentication_and_Login_Modules"></a></h2>
+<h3>JAAS Authentication and Login Modules<a name="JAAS_Authentication_and_Login_Modules"></a></h3>
 <div class="section">
-<h3>General Concepts<a name="General_Concepts"></a></h3>
+<h4>General Concepts<a name="General_Concepts"></a></h4>
 <p>In order to understand how login modules work and how Oak can help providing extension points we need to look at how JAAS authentication works in general and discuss where the actual credential-verification is performed.</p>
 <div class="section">
-<h4>Brief recap of the JAAS authentication<a name="Brief_recap_of_the_JAAS_authentication"></a></h4>
-<p>The following section is copied and adapted from the javadoc of <a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/javax/security/auth/spi/LoginModule.html">javax.security.auth.spi.LoginModule</a>:</p>
-<p>The authentication process within the <tt>LoginModule</tt> proceeds in two distinct phases. </p>
+<h5>Brief recap of the JAAS authentication<a name="Brief_recap_of_the_JAAS_authentication"></a></h5>
+<p>The following section is copied and adapted from the javadoc of <a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/javax/security/auth/spi/LoginModule.html">javax.security.auth.spi.LoginModule</a>. The authentication process within the <tt>LoginModule</tt> proceeds in two distinct phases, login and commit phase:</p>
+<p><i>Phase 1: Login</i></p>
 
 <ol style="list-style-type: decimal">
   
-<li>
-<p>Login Phase</p></li>
-  
-<li>
-<p>In the first phase, the <tt>LoginModule</tt>&#x2019;s <tt>login</tt> method gets invoked by the <tt>LoginContext</tt>&#x2019;s <tt>login</tt> method.</p></li>
+<li>In the first phase, the <tt>LoginModule</tt>&#x2019;s <tt>login</tt> method gets invoked by the <tt>LoginContext</tt>&#x2019;s <tt>login</tt> method.</li>
   
 <li>The <tt>login</tt> method for the <tt>LoginModule</tt> then performs the actual authentication (prompt for and verify a  password for example) and saves its authentication status as private state information.</li>
   
 <li>Once finished, the <tt>LoginModule</tt>&#x2019;s login method either returns <tt>true</tt> (if it succeeded) or <tt>false</tt> (if it should  be ignored), or throws a <tt>LoginException</tt> to specify a failure. In the failure case, the <tt>LoginModule</tt> must not  retry the authentication or introduce delays. The responsibility of such tasks belongs to the application.  If the application attempts to retry the authentication, the <tt>LoginModule</tt>&#x2019;s <tt>login</tt> method will be called again.</li>
+</ol>
+<p><i>Phase 2: Commit</i></p>
+
+<ol style="list-style-type: decimal">
   
-<li>
-<p>Commit Phase</p></li>
-  
-<li>
-<p>In the second phase, if the <tt>LoginContext</tt>&#x2019;s overall authentication succeeded (the relevant REQUIRED, REQUISITE,  SUFFICIENT and OPTIONAL LoginModules succeeded), then the <tt>commit</tt> method for the <tt>LoginModule</tt> gets invoked. </p></li>
+<li>In the second phase, if the <tt>LoginContext</tt>&#x2019;s overall authentication succeeded (the relevant REQUIRED, REQUISITE,  SUFFICIENT and OPTIONAL LoginModules succeeded), then the <tt>commit</tt> method for the <tt>LoginModule</tt> gets invoked.</li>
   
 <li>The <tt>commit</tt> method for a <tt>LoginModule</tt> checks its privately saved state to see if its own authentication  succeeded.</li>
   
@@ -413,124 +410,132 @@
 <li>If the <tt>LoginContext</tt>&#x2019;s overall authentication failed (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL  LoginModules did not succeed), then the <tt>abort</tt> method for each <tt>LoginModule</tt> gets invoked. In this case, the  <tt>LoginModule</tt> removes/destroys any authentication state originally saved.</li>
 </ol></div>
 <div class="section">
-<h4>Login module execution order<a name="Login_module_execution_order"></a></h4>
+<h5>Login module execution order<a name="Login_module_execution_order"></a></h5>
 <p>Very simply put, all the login modules that participate in JAAS authentication are configured in a list and can have flags indicating how to treat their behaviors on the <tt>login()</tt> calls.</p>
 <p>JAAS defines the following module flags:<br />(The following section is copied and adapted from the javadoc of <a class="externalLink" href="http://docs.oracle.com/javase/6/docs/api/javax/security/auth/login/Configuration.html">javax.security.auth.login.Configuration</a>)</p>
 
-<dl>
-<dt><b>Required</b></dt>
-<dd>The LoginModule is required to succeed.<br /> If it succeeds or fails, authentication still continues to proceed down the LoginModule list.</dd>
-<dt><b>Requisite</b></dt>
-<dd>The LoginModule is required to succeed.<br /> If it succeeds, authentication continues down the LoginModule list.  If it fails, control immediately returns to the application (authentication does not proceed down the LoginModule  list).</dd>
-<dt><b>Sufficient</b></dt>
-<dd>The LoginModule is not required to succeed.<br /> If it does succeed, control immediately returns to the application (authentication does not proceed down the  LoginModule list).  If it fails, authentication continues down the LoginModule list.</dd>
-<dt><b>Optional</b></dt>
-<dd>The LoginModule is not required to succeed.<br /> If it succeeds or fails, authentication still continues to proceed down the LoginModule list.</dd>
-</dl>
+<ul>
+  
+<li><b>Required</b>: The LoginModule is required to succeed. If it succeeds or fails,  authentication still continues to proceed down the LoginModule list.</li>
+  
+<li><b>Requisite</b>: The LoginModule is required to succeed. If it succeeds, authentication  continues down the LoginModule list. If it fails, control immediately returns  to the application (authentication does not proceed down the LoginModule list).</li>
+  
+<li><b>Sufficient</b>: The LoginModule is not required to succeed. If it does succeed,  control immediately returns to the application (authentication does not proceed  down the LoginModule list). If it fails, authentication continues down the LoginModule list.</li>
+  
+<li><b>Optional</b>: The LoginModule is not required to succeed. If it succeeds or  fails, authentication still continues to proceed down the LoginModule list.</li>
+</ul>
 <p>The overall authentication succeeds <b>only</b> if <b>all</b> Required and Requisite LoginModules succeed. If a Sufficient LoginModule is configured and succeeds, then only the Required and Requisite LoginModules prior to that Sufficient LoginModule need to have succeeded for the overall authentication to succeed. If no Required or Requisite LoginModules are configured for an application, then at least one Sufficient or Optional LoginModule must succeed.</p></div></div></div>
 <div class="section">
-<h2>JCR and Oak Authentication<a name="JCR_and_Oak_Authentication"></a></h2>
+<h3>JCR Authentication<a name="JCR_Authentication"></a></h3>
 <p>Within the scope of JCR <tt>Repository.login</tt> is used to authenticate a given user. This method either takes a <tt>Credentials</tt> argument if the validation is performed by the repository itself or <tt>null</tt> in case the user has be pre-authenticated by an external system.</p>
+<p>Furthermore JCR defines two types of <tt>Credentials</tt> implementations:</p>
+
+<ul>
+  
+<li><a class="externalLink" href="http://www.day.com/specs/javax.jcr/javadocs/jcr-2.0/javax/jcr/GuestCredentials.html">javax.jcr.GuestCredentials</a>: used to obtain a &#x201c;guest&#x201d;, &#x201c;public&#x201d; or &#x201c;anonymous&#x201d; session.</li>
+  
+<li><a class="externalLink" href="http://www.day.com/specs/javax.jcr/javadocs/jcr-2.0/javax/jcr/SimpleCredentials.html">javax.jcr.SimpleCredentials</a>: used to login a user with a userId and password.</li>
+</ul>
+<p>The following variants exist for the repository login itself:</p>
+
+<ul>
+  
+<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(String workspace): login with</tt>null` credentials to the workspace with the specified name.</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>
+<p>See <a class="externalLink" href="http://www.day.com/specs/javax.jcr/javadocs/jcr-2.0/javax/jcr/Repository.html">javax.jcr.Repository</a> and <a class="externalLink" href="http://svn.apache.org/repos/asf/jackrabbit/trunk/jackrabbit-api/src/main/java/org/apache/jackrabbit/api/JackrabbitRepository.java">org.apache.jackrabbit.api.JackrabbitRepository</a> for further details.</p>
+<p>In addition JCR defines <tt>Session.impersonate(Credentials)</tt> to impersonate another user or - as of JSR 333 - clone an existing session.</p></div>
 <div class="section">
-<h3>Differences wrt Jackrabbit 2.x<a name="Differences_wrt_Jackrabbit_2.x"></a></h3>
-<p>see the corresponding <a href="../differences_authentication.html">documentation</a>.</p></div>
+<h3>Oak Authentication<a name="Oak_Authentication"></a></h3>
 <div class="section">
-<h3>Logins with Credentials<a name="Logins_with_Credentials"></a></h3>
+<h4>General Notes<a name="General_Notes"></a></h4>
 <p><i>todo</i></p></div>
 <div class="section">
-<h3>Pre Authenticated Logins<a name="Pre_Authenticated_Logins"></a></h3>
-<p>Oak provides two different mechanisms to create pre-authentication that doesn&#x2019;t involve the repositories internal authentication mechanism for credentials validation.</p>
-<div class="section">
-<h4>Pre-Authentication combined with Login Module Chain<a name="Pre-Authentication_combined_with_Login_Module_Chain"></a></h4>
-<p>This first variant allows to support 3rd party login modules that wish to provide the login context with pre authenticated login names, but still want to rely on the rest of the oak&#x2019;s login module chain. For example an external SSO login module can extract the userid from a servlet request and use it to authenticate against the repository. But instead of re-implementing the user lookup and subject population (and possible external user synchronization) it just sets a respective <a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/PreAuthenticatedLogin.html">org.apache.jackrabbit.oak.spi.security.authentication.PreAuthenticatedLogin</a> on the shared state.</p>
-<p>This setup is particularly recommended in a OSGi setup that includes Apache Sling on top of the Oak repository but still requires user information to be synchronized into the repository.</p>
-<p>The key to understand this mechanism is <tt>org.apache.jackrabbit.oak.spi.security.authentication.PreAuthenticatedLogin</tt> a simple marker, which is pushed to the shared state of the login context and which indicates to any subsequent LoginModule that the credentials present in the state already have been verified and thus can be trusted.</p>
-<p>The basic steps of this pre-authentication are outlined as follows:</p>
+<h4>Oak API<a name="Oak_API"></a></h4>
+<p><i>todo</i></p>
 
-<ol style="list-style-type: decimal">
-  
-<li>verify the identity in the layer on top of the JCR repository (e.g. in a custom Sling Authentication Handler)</li>
+<ul>
   
-<li>pass a custom, non-public Credentials implementation to the repository login</li>
+<li>ContentRepository.login</li>
   
-<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>AuthInfo</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>
-<p>Example implementation of <tt>LoginModule#login</tt> of this kind of custom login module:</p>
+<li>ContentSession.getAuthInfo</li>
+</ul></div>
+<div class="section">
+<h4>Differences wrt Jackrabbit 2.x<a name="Differences_wrt_Jackrabbit_2.x"></a></h4>
+<p>See section <a href="authentication/differences.html">differences</a> for complete list of differences wrt authentication between Jackrabbit 2.x and Oak.</p></div>
+<div class="section">
+<h4>Guest Login<a name="Guest_Login"></a></h4>
+<p>The proper way to obtain an guest session as of Oak is as specified by JSR 283:</p>
 
 <div class="source">
-<pre>public class PreAuthLoginModule extends AbstractLoginModule {
+<pre>String wspName = null;
+Session anonymous = repository.login(new GuestCredentials(), wspName);
+</pre></div>
+<p>As of Oak 1.0 <tt>Repository#login()</tt> and <tt>Repository#login(null, wspName)</tt> is no longer treated as guest login. This behavior of Jackrabbit-core is violating the specification, which defines that null-login should be used for those cases where the authentication process is handled outside of the repository (see <a href="authentication/preauthentication.html">Pre-Authentication</a>).</p>
+<p>Similarly, any special treatment that Jackrabbit core applied for the guest (anonymous) user has been omitted altogether from the default <a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/security/authentication/user/LoginModuleImpl.html">LoginModuleImpl</a>. In the default setup the built-in anonymous user will be created without any password. Therefore explicitly uid/pw login using the anonymous userId will no longer work. This behavior is now consistent with the default login of any other user which doesn&#x2019;t have a password set.</p>
+<div class="section">
+<h5>Guest Login Module<a name="Guest_Login_Module"></a></h5>
+<p>The aim of the <a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/GuestLoginModule.html">GuestLoginModule</a> implementation is to provide backwards compatibility with Jackrabbit 2.x with respect to the guest (anonymous) login: the <tt>GuestLoginModule</tt> can be added as <i>optional</i> entry to the chain of login modules in the JAAS (or corresponding OSGi) configuration.</p>
+<p>Example JAAS Configuration:</p>
 
-[...]
-
-    @Overwrite
-    public boolean login() throws LoginException {
-        Credentials credentials = getCredentials();
-        if (credentials instanceof MyPreAuthCredentials) {
-            userId = ((MyPreAuthCredentials) credentials).getUserId();
-            if (userId == null) {
-                log.debug(&quot;Could not extract userId/credentials&quot;);
-            } else {
-                sharedState.put(SHARED_KEY_PRE_AUTH_LOGIN, new PreAuthenticatedLogin(userId));
-                sharedState.put(SHARED_KEY_CREDENTIALS, new SimpleCredentials(userId, new char[0]));
-                sharedState.put(SHARED_KEY_LOGIN_NAME, userId);
-                log.debug(&quot;login succeeded with trusted user: {}&quot;, userId);
-            }
-        }
-
-        [...]
-    }
-}
-</pre></div></div>
-<div class="section">
-<h4>Pre-Authentication without Repository Involvement<a name="Pre-Authentication_without_Repository_Involvement"></a></h4>
-<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>
-<p>This behavior is provided by the default implementation of the <tt>LoginContextProvider</tt> [1] which expects a <tt>Subject</tt> to be available with the current <tt>java.security.AccessControlContext</tt>. However, in contrast to Jackrabbit-core the current implementation does not try to extend the pre-authenticated subject but skips the internal verification step altogether.</p>
-<p>Since the <tt>LoginContextProvider</tt> is a configurable with the authentication setup OAK users also have the following options by providing a custom <tt>LoginContextProvider</tt>:</p>
+<div class="source">
+<pre>jackrabbit.oak {
+   org.apache.jackrabbit.oak.spi.security.authentication.GuestLoginModule  optional;
+   org.apache.jackrabbit.oak.security.authentication.user.LoginModuleImpl required;
+};
+</pre></div>
+<p>The behavior of the <tt>GuestLoginModule</tt> is as follows:</p>
+<p><i>Phase 1: Login</i></p>
 
 <ul>
   
-<li>Disable pre-authentication by not trying to retrieve a pre-authenticated <tt>Subject</tt>.</li>
+<li>tries to retrieve JCR credentials from the [CallbackHandler] using the [CredentialsCallback]</li>
   
-<li>Add support for extending the pre-authenticated subject by always passing writable subjects to the <tt>JaasLoginContext</tt></li>
+<li>in case no credentials could be obtained it pushes a new instance of [GuestCredentials] to the shared stated  and <b>returns</b> <tt>true</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>
+<li>otherwise it <b>returns</b> <tt>false</tt></li>
 </ul>
-<p>Example how to use this type of pre-authentication:</p>
+<p><i>Phase 2: Commit</i></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)
- */
-Set&lt;? extends Principal&gt; principals = getPrincipals(userId);
-AuthInfo authInfo = new AuthInfoImpl(userId, Collections.&lt;String, Object&gt;emptyMap(), principals);
-Subject subject = new Subject(true, principals, Collections.singleton(authInfo), Collections.&lt;Object&gt;emptySet());
-Session session;
-try {
-    session = Subject.doAsPrivileged(subject, new PrivilegedExceptionAction&lt;Session&gt;() {
-        @Override
-        public Session run() throws Exception {
-            return login(null, null);
-        }
-    }, null);
-} catch (PrivilegedActionException e) {
-    throw new RepositoryException(&quot;failed to retrieve session.&quot;, e);
-}
-</pre></div></div></div></div>
-<div class="section">
-<h2>Oak Login Module Implementations<a name="Oak_Login_Module_Implementations"></a></h2>
+<ul>
+  
+<li>if the phase 1 succeeded it will add the <tt>GuestCredentials</tt> created above and  <tt>EveryonePrincipal</tt> the <tt>Subject</tt> in phase 2 of the login process and <b>returns</b> <tt>true</tt></li>
+  
+<li>otherwise it <b>returns</b> <tt>false</tt></li>
+</ul></div></div>
 <div class="section">
-<h3>Abstract Login Module<a name="Abstract_Login_Module"></a></h3>
-<p><i>todo</i></p></div>
+<h4>UserId/Password Login<a name="UserIdPassword_Login"></a></h4>
+<p>Oak 1.0 comes with 2 different login module implementations that can handle <tt>SimpleCredentials</tt>:</p>
+
+<ul>
+  
+<li>Default (<tt>LoginModuleImpl</tt>) as described below</li>
+  
+<li><tt>ExternalLoginModule</tt> as described in section <a href="authentication/externalloginmodule.html">External Authentication</a></li>
+</ul>
 <div class="section">
-<h3>Default Login Module<a name="Default_Login_Module"></a></h3>
-<p>The behavior of the default login module is relatively simple, so it is explained first:</p>
-<p>upon login():</p>
+<h5>Default Login Module<a name="Default_Login_Module"></a></h5>
+<p>The <a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/security/authentication/user/LoginModuleImpl.html">LoginModuleImpl</a> defines a regular userId/password login and requires a repository setup that supports <a href="user.html">User Management</a> and is designed to supports the following <tt>Credentials</tt>:</p>
+
+<ul>
+  
+<li><tt>SimpleCredentials</tt></li>
+  
+<li><tt>GuestCredentials</tt> (see above)</li>
+  
+<li><tt>ImpersonationCredentials</tt> (see below)</li>
+</ul>
+<p>This login module implementations behaves as follows:</p>
+<p><i>Phase 1: Login</i></p>
 
 <ul>
   
@@ -553,462 +558,175 @@ try {
 <li>also, it adds the credentials to the private state</li>
   </ul></li>
 </ul>
-<p>upon commit():</p>
+<p><i>Phase 2: Commit</i></p>
 
 <ul>
   
 <li>if the private state contains the credentials and principals, it adds them (both) to the subject and <b>returns <tt>true</tt></b></li>
   
 <li>if the private state does not contain credentials and principals, it clears the state and <b>returns <tt>false</tt></b></li>
-</ul></div>
-<div class="section">
-<h3>Token Login Module<a name="Token_Login_Module"></a></h3>
-<p><i>todo</i></p></div>
-<div class="section">
-<h3>Guest Login Module<a name="Guest_Login_Module"></a></h3>
-<p><i>todo</i></p></div>
-<div class="section">
-<h3>External Login Module<a name="External_Login_Module"></a></h3>
+</ul></div></div>
 <div class="section">
-<h4>Overview<a name="Overview"></a></h4>
-<p>The purpose of the external login module is to provide a base implementation that allows easy integration of 3rd party authentication and identity systems, such as LDAP. The general mode of the external login module is to use the external system as authentication source and as a provider for users and groups.</p>
-<p>what it does:</p>
+<h4>Impersonation<a name="Impersonation"></a></h4>
+<p>Another flavor of the Oak authentication implementation is covered by <tt>javax.jcr.Session#impersonate(Credentials)</tt>, which allows to obtain an new <tt>Session</tt> for user identitified by the specified credentials. As of JSR 333 this method can also be used in order to clone the existing session (i.e. self-impersonation of the user that holds the session.</p>
+<p>With Oak 1.0 impersonation is implemented as follows:</p>
 
-<ul>
+<ol style="list-style-type: decimal">
   
-<li>facilitate the use of a 3rd party system for authentication</li>
+<li><tt>Session#impersonate</tt> takes any kind of <tt>Credentials</tt></li>
   
-<li>simplify populating the oak user manager with identities from a 3rd party system</li>
-</ul>
-<p>what it does not:</p>
+<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>these <tt>ImpersonationCredentials</tt> are passed to <tt>Repository.login</tt></li>
+</ol>
+<p>Whether or not impersonation succeeds consequently both depends on the authentication setup and on some implementation specific validation that make sure the editing session is allowed to impersonate the user identified by the credentials passed to the impersonate call.</p>
+<p>With Oak 1.0 only the default login module (<a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/security/authentication/user/LoginModuleImpl.html">LoginModuleImpl</a>) is able to deal with <tt>ImpersonationCredentials</tt> and applies the following logic:</p>
 
 <ul>
   
-<li>provide a transparent oak user manager</li>
-  
-<li>provide a transparent oak principal provider.</li>
+<li><b>Self-Impersonation</b>: Any attempt to impersonate the same session will succeed  as long as the user is still valid (i.e. exists and has not been disabled).</li>
   
-<li>offer services for background synchronization of users and groups</li>
-</ul></div>
+<li><b>Regular Impersonation</b>: Impersonation another user will only succeed if  the impersonated user is valid (i.e. exists and is not disabled) <i>and</i> the  the user associated with the editing session is allowed to impersonate this  user. The latter depends on the <a href="user.html">User Management</a> implementation  specifically on the return value of <tt>User.getImpersonation().allows(Subject subject)</tt>.</li>
+</ul>
 <div class="section">
-<h4>Structure<a name="Structure"></a></h4>
-<p>The external identity and login handling is split into 3 parts:</p>
+<h5>ImpersonationCredentials<a name="ImpersonationCredentials"></a></h5>
+<p>Since the implementation of <tt>Session.impersonate</tt> no longer uses <tt>SimpleCredentials</tt> to transport the original <tt>Subject</tt> but rather performs the login with dedicated <a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/ImpersonationCredentials.html">ImpersonationCredentials</a>, impersonation is no longer restricted to <tt>SimpleCredentials</tt> being passed to <tt>Session#impersonate</tt> call. Instead the specified credentials are passed to a new instance of <tt>ImpersonationCredentials</tt> delegating the evaluation and validation of the specified <tt>Credentials</tt> to the configured login module(s).</p>
+<p>This modification will not affect applications that used JCR API to impersonate a given session. Note however that applications relying on the Jackrabbit implementation and manually creating <tt>SimpleCredentials</tt> with a <tt>SecurityConstants.IMPERSONATOR_ATTRIBUTE</tt>, would need to be refactor after migration to Oak.</p></div>
+<div class="section">
+<h5>Impersonation with Custom Authentication Setup<a name="Impersonation_with_Custom_Authentication_Setup"></a></h5>
+<p>Applications that wish to use a custom authentication setup need to ensure the following steps in order to get JCR impersonation working:</p>
 
-<ol style="list-style-type: decimal">
+<ul>
   
-<li>An external identity provider (IDP). This is a service implementing the <tt>ExternalIdentityProvider</tt> interface and is responsible to retrieve and authenticate identities towards an external system (e.g. LDAP).</li>
+<li>Respect <tt>ImpersonationCredentials</tt> in the authentication setup.</li>
   
-<li>An synchronization handler. This is a service implementing the <tt>SyncHandler</tt> interface and is responsible to actually managing the external identities within the Oak user management. A very trivial implementation might just create users and groups for external ones on demand.</li>
+<li>Identify the impersonated from <tt>ImpersonationCredentials.getBaseCredentials</tt>  and verify if it can be authenticated.</li>
   
-<li>The external login module (ExtLM). This is the connection between JAAS login mechanism, the external identity provider and the synchronization handler.</li>
-</ol>
-<p>This modularization allows to reuse the same external login module for different combinations of IDPs and synchronization handlers. Although in practice, systems usually have 1 of each. </p>
-<p>An example where multiple such entities come into play would be the case to use several LDAP servers for authentication. Here we would configure 2 LDAP IDPs, 1 Sync handler and 2 ExtLMs.</p>
+<li>Validate that the editing session is allowed to impersonate: The user associated  with the editing session can be identified by the <a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/AuthInfo.html">AuthInfo</a> obtained from  from <tt>ImpersonationCredentials.getImpersonatorInfo()</tt>.</li>
+</ul></div></div>
 <div class="section">
-<h5>Authentication and subject population<a name="Authentication_and_subject_population"></a></h5>
-<p>The goal of the external login module is to provide a very simple way of using <i>&#x201c;the users stored in an external system for authentication and authorization in the Oak content repository&#x201d;</i>. So the easiest way of doing this is to import the users on-demand when they log in. </p></div></div>
+<h4>Token Login<a name="Token_Login"></a></h4>
+<p>See section <a href="authentication/tokenmanagement.html">Token Authentication</a> for details regarding token based authentication.</p>
 <div class="section">
-<h4>Behavior of the External Login Module<a name="Behavior_of_the_External_Login_Module"></a></h4>
+<h5>Token Login Module<a name="Token_Login_Module"></a></h5>
+<p>The <tt>TokenLoginModule</tt> is in charge of creating new login tokens and validate repository logins with <tt>TokenCredentials</tt>. The exact behavior of this login module is described in section <a href="authentication/tokenmanagement.html">Token Authentication</a>.</p></div></div>
 <div class="section">
-<h5>General<a name="General"></a></h5>
-<p>The external login module has 2 main tasks. one is to authenticate credentials against a 3rd party system, the other is to coordinate syncing of the respective users and groups with the JCR repository (via the UserManager).</p>
-<p>If a user needs re-authentication (for example, if the cache validity expired or if the user is not yet present in the local system at all), the login module must check the credentials with the external system during the <tt>login()</tt> method. </p>
-<p><b>ExternalLoginModule</b></p>
-<p>Note:</p>
+<h4>Pre-Authenticated Login<a name="Pre-Authenticated_Login"></a></h4>
+<p>Oak provides two different mechanisms to create pre-authentication that doesn&#x2019;t involve the repositories internal authentication mechanism for credentials validation.</p>
 
 <ul>
   
-<li>users (and groups) that are synced from the 3rd party system contain a <tt>rep:externalId</tt> property. This allows to identify the external users and distinguish them from others.</li>
+<li>Pre-Authentication combined with Login Module Chain</li>
   
-<li>to reduce expensive syncing, the synced users and groups have sync timestamp <tt>rep:lastSynced</tt> and are considered valid for a configurable time. if they expire, they need to be validated against the 3rd party system again.</li>
+<li>Pre-Authentication without Repository Involvement (aka <tt>null</tt> login)</li>
 </ul>
-<p>upon login():</p>
+<p>See section <a href="authentication/preauthentication.html">Pre-Authentication Login</a> for further details and examples.</p></div>
+<div class="section">
+<h4>External Login<a name="External_Login"></a></h4>
+<p>While the default setup in Oak is solely relying on repository functionality to ensure proper authentication it quite common to authenticate against different systems (e.g. LDAP). For those setups that wish to combine initial authentication against a third party system with repository functionality, Oak provides a default implementation with extension points:</p>
 
 <ul>
   
-<li>if the user exists in the repository and is not an externally synced, <b>return <tt>false</tt></b></li>
+<li><a href="authentication/externalloginmodule.html">External Authentication</a>: Summary of  the external authentication and details about the <tt>ExternalLoginModule</tt>.</li>
   
-<li>if the user exists in the 3rd party system but the credentials don&#x2019;t match it <b>throws <tt>LoginException</tt></b></li>
+<li><a href="authentication/usersync.html">User and Group Synchronization</a>: Details regarding  user and group synchronization as well as a list of configuration options provided  by the the default implementations present with Oak.</li>
   
-<li>if the user exists in the 3rd party system and the credentials match
+<li><a href="authentication/identitymanagement.html">Identity Management</a>: Further information regarding extenal identity management.</li>
   
-<ul>
-    
-<li>put the credentials in the shared and private state</li>
-    
-<li>possibly sync the user</li>
-    
-<li>and <b>returns <tt>true</tt></b></li>
-  </ul></li>
-  
-<li>if the user does not exist in the 3rd party system, checks if it needs to remove the user and then it <b>returns <tt>false</tt></b></li>
+<li><a href="authentication/ldap.html">LDAP Integration</a>: How to make use of the <tt>ExternalLoginModule</tt>  with the LDAP identity provider implementation. This combination is aimed to replace  <a class="externalLink" href="http://dev.day.com/docs/en/crx/current/administering/ldap_authentication.html">com.day.crx.security.ldap.LDAPLoginModule</a>, which relies on Jackrabbit internals  and will no longer work with Oak.</li>
 </ul>
-<p>upon commit():</p>
+<div class="section">
+<h5>External Login Module<a name="External_Login_Module"></a></h5>
+<p>The external login module is a base implementation that allows easy integration of 3rd party authentication and identity systems, such as <a href="ldap.html">LDAP</a>. The general mode of the external login module is to use the external system as authentication source and as a provider for users and groups that may also be synchronized into the repository.</p>
+<p>This login module implementation requires an valid <tt>SyncHandler</tt> and <tt>IdentityProvider</tt> to be present. The detailed behavior of the <tt>ExternalLoginModule</tt> is described in section <a href="authentication/externalloginmodule.html">External Authentication</a>.</p></div></div></div>
+<div class="section">
+<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>
 
 <ul>
   
-<li>if there is no credentials in the private state, it <b>returns <tt>false</tt></b></li>
+<li><tt>LoginContextProvider</tt>: Configurable provider of the <tt>LoginContext</tt> (see below)</li>
+  
+<li><tt>LoginContext</tt>: Interface version of the JAAS LoginContext aimed to ease integration with non-JAAS components</li>
   
-<li>if there are credentials in the private state propagate the subject and <b>return <tt>true</tt></b></li>
+<li><tt>Authentication</tt>: Aimed to validate credentials during the first phase of the (JAAS) login process.</li>
 </ul></div></div>
 <div class="section">
-<h4>User and Group Synchronization<a name="User_and_Group_Synchronization"></a></h4>
-<p>The synchronization of users and groups is triggered by the external login module, after a user is successfully authenticated against the IDP or if it&#x2019;s no longer present on the IDP.</p>
-<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 <a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/impl/DefaultSyncConfig.html">org.apache.jackrabbit.oak.spi.security.authentication.external.impl.DefaultSyncConfig</a>. The handler is configured either via OSGi or during manual <a href="../construct.html">Repository Construction</a>.</p>
+<h4>Token Management<a name="Token_Management"></a></h4>
+<p>See section <a href="authentication/tokenmanagement.html">token management</a> for details.</p>
 
-<table border="0" class="table table-striped">
-  <thead>
-    
-<tr class="a">
-      
-<th>Name </th>
-      
-<th>Property </th>
-      
-<th>Description </th>
-    </tr>
-  </thead>
-  <tbody>
-    
-<tr class="b">
-      
-<td>Sync Handler Name </td>
-      
-<td><tt>handler.name</tt> </td>
-      
-<td>Name of this sync configuration. This is used to reference this handler by the login modules. </td>
-    </tr>
-    
-<tr class="a">
-      
-<td>User auto membership </td>
-      
-<td><tt>user.autoMembership</tt> </td>
-      
-<td>List of groups that a synced user is added to automatically </td>
-    </tr>
-    
-<tr class="b">
-      
-<td>User Expiration Time </td>
-      
-<td><tt>user.expirationTime</tt> </td>
-      
-<td>Duration until a synced user gets expired (eg. &#x2018;1h 30m&#x2019; or &#x2018;1d&#x2019;). </td>
-    </tr>
-    
-<tr class="a">
-      
-<td>User Membership Expiration </td>
-      
-<td><tt>user.membershipExpTime</tt> </td>
-      
-<td>Time after which membership expires (eg. &#x2018;1h 30m&#x2019; or &#x2018;1d&#x2019;). </td>
-    </tr>
-    
-<tr class="b">
-      
-<td>User membership nesting depth </td>
-      
-<td><tt>user.membershipNestingDepth</tt> </td>
-      
-<td>Returns the maximum depth of group nesting when membership relations are synced. A value of 0 effectively disables group membership lookup. A value of 1 only adds the direct groups of a user. This value has no effect when syncing individual groups only when syncing a users membership ancestry. </td>
-    </tr>
-    
-<tr class="a">
-      
-<td>User Path Prefix </td>
-      
-<td><tt>user.pathPrefix</tt> </td>
-      
-<td>The path prefix used when creating new users. </td>
-    </tr>
-    
-<tr class="b">
-      
-<td>User property mapping </td>
-      
-<td><tt>user.propertyMapping</tt> </td>
-      
-<td>List mapping definition of local properties from external ones. eg: &#x2018;profile/email=mail&#x2019;.Use double quotes for fixed values. eg: &#x2019;profile/nt:primaryType=&#x201c;nt:unstructured&#x201d; </td>
-    </tr>
-    
-<tr class="a">
-      
-<td>Group auto membership </td>
-      
-<td><tt>group.autoMembership</tt> </td>
-      
-<td>List of groups that a synced group is added to automatically </td>
-    </tr>
-    
-<tr class="b">
-      
-<td>Group Expiration Time </td>
-      
-<td><tt>group.expirationTime</tt> </td>
-      
-<td>Duration until a synced group expires (eg. &#x2018;1h 30m&#x2019; or &#x2018;1d&#x2019;). </td>
-    </tr>
-    
-<tr class="a">
-      
-<td>Group Path Prefix </td>
-      
-<td><tt>group.pathPrefix</tt> </td>
-      
-<td>The path prefix used when creating new groups. </td>
-    </tr>
-    
-<tr class="b">
-      
-<td>Group property mapping </td>
-      
-<td><tt>group.propertyMapping</tt> </td>
-      
-<td>List mapping definition of local properties from external ones. </td>
-    </tr>
-    
-<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>
-    </tr>
-  </tbody>
-</table></div></div>
-<div class="section">
-<h4>External Identity Provider<a name="External_Identity_Provider"></a></h4>
-<p><i>todo</i></p></div></div></div>
-<div class="section">
-<h2>Authentication related Interfaces and Extension Points in Oak<a name="Authentication_related_Interfaces_and_Extension_Points_in_Oak"></a></h2>
-<div class="section">
-<h3>Token Management<a name="Token_Management"></a></h3>
-<p><i>todo</i></p>
-<div class="section">
-<h4>TokenProvider<a name="TokenProvider"></a></h4></div>
-<div class="section">
-<h4>TokenInfo<a name="TokenInfo"></a></h4></div></div>
+<ul>
+  
+<li><tt>TokenConfiguration</tt>: Interface to obtain a <tt>TokenProvider</tt> instance.</li>
+  
+<li><tt>TokenProvider</tt>: Interface to manage login tokens.</li>
+  
+<li><tt>TokenInfo</tt>: Information related to a login token and token validity.</li>
+</ul></div>
 <div class="section">
-<h3>External Identity Management<a name="External_Identity_Management"></a></h3>
-<p><i>todo</i></p>
+<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>
 <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>
 <div class="section">
-<h5>LDAP Identity Provider<a name="LDAP_Identity_Provider"></a></h5>
-<p>Oak comes with a default implementation of an LDAP identity provider.</p>
+<h3>Configuration<a name="Configuration"></a></h3>
+
+<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>
+</ul>
 <div class="section">
-<h6>Configuration<a name="Configuration"></a></h6>
-<p>The LDAP IPDs are configured through the <a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/security/authentication/ldap/impl/LdapProviderConfig.html">org.apache.jackrabbit.oak.security.authentication.ldap.impl.LdapProviderConfig</a> which is populated either via OSGi or during manual <a href="../construct.html">Repository Construction</a>.</p>
+<h4>JAAS Configuration Utilities<a name="JAAS_Configuration_Utilities"></a></h4>
+<p>There also exists a utility class that allows to obtain different <tt>javax.security.auth.login.Configuration</tt> for the most common setup [11]:</p>
 
-<table border="0" class="table table-striped">
-  <thead>
-    
-<tr class="a">
-      
-<th>Name </th>
-      
-<th>Property </th>
-      
-<th>Description </th>
-    </tr>
-  </thead>
-  <tbody>
-    
-<tr class="b">
-      
-<td>LDAP Provider Name </td>
-      
-<td><tt>provider.name</tt> </td>
-      
-<td>Name of this LDAP provider configuration. This is used to reference this provider by the login modules. </td>
-    </tr>
-    
-<tr class="a">
-      
-<td>Bind DN </td>
-      
-<td><tt>bind.dn</tt> </td>
-      
-<td>DN of the user for authentication. Leave empty for anonymous bind. </td>
-    </tr>
-    
-<tr class="b">
-      
-<td>Bind Password </td>
-      
-<td><tt>bind.password</tt> </td>
-      
-<td>Password of the user for authentication. </td>
-    </tr>
-    
-<tr class="a">
-      
-<td>LDAP Server Hostname </td>
-      
-<td><tt>host.name</tt> </td>
-      
-<td>Hostname of the LDAP server </td>
-    </tr>
-    
-<tr class="b">
-      
-<td>Disable certificate checking </td>
-      
-<td><tt>host.noCertCheck</tt> </td>
-      
-<td>Indicates if server certificate validation should be disabled. </td>
-    </tr>
-    
-<tr class="a">
-      
-<td>LDAP Server Port </td>
-      
-<td><tt>host.port</tt> </td>
-      
-<td>Port of the LDAP server </td>
-    </tr>
-    
-<tr class="b">
-      
-<td>Use SSL </td>
-      
-<td><tt>host.ssl</tt> </td>
-      
-<td>Indicates if an SSL (LDAPs) connection should be used. </td>
-    </tr>
-    
-<tr class="a">
-      
-<td>Use TLS </td>
-      
-<td><tt>host.tls</tt> </td>
-      
-<td>Indicates if TLS should be started on connections. </td>
-    </tr>
-    
-<tr class="b">
-      
-<td>Search Timeout </td>
-      
-<td><tt>searchTimeout</tt> </td>
-      
-<td>Time in until a search times out (eg: &#x2018;1s&#x2019; or &#x2018;1m 30s&#x2019;). </td>
-    </tr>
-    
-<tr class="a">
-      
-<td>User base DN </td>
-      
-<td><tt>user.baseDN</tt> </td>
-      
-<td>The base DN for user searches. </td>
-    </tr>
-    
-<tr class="b">
-      
-<td>User extra filter </td>
-      
-<td><tt>user.extraFilter</tt> </td>
-      
-<td>Extra LDAP filter to use when searching for users. The final filter is formatted like: <tt>(&amp;(&lt;idAttr&gt;=&lt;userId&gt;)(objectclass=&lt;objectclass&gt;)&lt;extraFilter&gt;)</tt> </td>
-    </tr>
-    
-<tr class="a">
-      
-<td>User id attribute </td>
-      
-<td><tt>user.idAttribute</tt> </td>
-      
-<td>Name of the attribute that contains the user id. </td>
-    </tr>
-    
-<tr class="b">
-      
-<td>User DN paths </td>
-      
-<td><tt>user.makeDnPath</tt> </td>
-      
-<td>Controls if the DN should be used for calculating a portion of the intermediate path. </td>
-    </tr>
-    
-<tr class="a">
-      
-<td>User object classes </td>
-      
-<td><tt>user.objectclass</tt> </td>
-      
-<td>The list of object classes an user entry must contain. </td>
-    </tr>
-    
-<tr class="b">
-      
-<td>Group base DN </td>
-      
-<td><tt>group.baseDN</tt> </td>
-      
-<td>The base DN for group searches. </td>
-    </tr>
+<ul>
+  
+<li><tt>ConfigurationUtil#getDefaultConfiguration</tt>: default OAK configuration supporting uid/pw login configures <tt>LoginModuleImpl</tt> only</li>
+  
+<li><tt>ConfigurationUtil#getJackrabbit2Configuration</tt>: backwards compatible configuration that provides the functionality covered by jackrabbit-core DefaultLoginModule, namely:
+  
+<ul>
     
-<tr class="a">
-      
-<td>Group extra filter </td>
-      
-<td><tt>group.extraFilter</tt> </td>
-      
-<td>Extra LDAP filter to use when searching for groups. The final filter is formatted like: <tt>(&amp;(&lt;nameAttr&gt;=&lt;groupName&gt;)(objectclass=&lt;objectclass&gt;)&lt;extraFilter&gt;)</tt> </td>
-    </tr>
+<li><tt>GuestLoginModule</tt>: null login falls back to anonymous</li>
     
-<tr class="b">
-      
-<td>Group DN paths </td>
-      
-<td><tt>group.makeDnPath</tt> </td>
-      
-<td>Controls if the DN should be used for calculating a portion of the intermediate path. </td>
-    </tr>
+<li><tt>TokenLoginModule</tt>: covers token base authentication</li>
     
-<tr class="a">
-      
-<td>Group member attribute </td>
-      
-<td><tt>group.memberAttribute</tt> </td>
-      
-<td>Group attribute that contains the member(s) of a group. </td>
-    </tr>
+<li><tt>LoginModuleImpl</tt>: covering regular uid/pw login</li>
+  </ul></li>
+</ul></div></div>
+<div class="section">
+<h3>Further Reading<a name="Further_Reading"></a></h3>
+
+<ul>
+  
+<li><a href="authentication/differences.html">Differences wrt Jackrabbit 2.x</a></li>
+  
+<li><a href="authentication/tokenmanagement.html">Token Authentication and Token Management</a></li>
+  
+<li><a href="authentication/externalloginmodule.html">External Authentication</a>
+  
+<ul>
     
-<tr class="b">
-      
-<td>Group name attribute </td>
-      
-<td><tt>group.nameAttribute</tt> </td>
-      
-<td>Name of the attribute that contains the group name. </td>
-    </tr>
+<li><a href="authentication/usersync.html">User and Group Synchronization</a></li>
     
-<tr class="a">
-      
-<td>Group object classes </td>
-      
-<td><tt>group.objectclass</tt> </td>
-      
-<td>The list of object classes a group entry must contain. </td>
-    </tr>
+<li><a href="authentication/identitymanagement.html">Identity Management</a></li>
     
-<tr class="b">
-      
-<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; </td>
-      
-<td> </td>
-      
-<td> </td>
-    </tr>
-  </tbody>
-</table>
-<!-- references --></div></div></div></div></div>
+<li><a href="authentication/ldap.html">LDAP Integration</a></li>
+  </ul></li>
+  
+<li><a href="authentication/preauthentication.html">Pre-Authentication</a></li>
+</ul>
+<!-- references --></div></div>
                   </div>
             </div>
           </div>



Mime
View raw message