jackrabbit-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ang...@apache.org
Subject svn commit: r1567091 - in /jackrabbit/site/live/oak/docs: known_issues.html security/external_login_module.html
Date Tue, 11 Feb 2014 12:32:45 GMT
Author: angela
Date: Tue Feb 11 12:32:45 2014
New Revision: 1567091

URL: http://svn.apache.org/r1567091
Log:
OAK-936: Site checkin for project Oak Documentation-0.16-SNAPSHOT

Added:
    jackrabbit/site/live/oak/docs/security/external_login_module.html   (with props)
Modified:
    jackrabbit/site/live/oak/docs/known_issues.html

Modified: jackrabbit/site/live/oak/docs/known_issues.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/known_issues.html?rev=1567091&r1=1567090&r2=1567091&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/known_issues.html (original)
+++ jackrabbit/site/live/oak/docs/known_issues.html Tue Feb 11 12:32:45 2014
@@ -1,13 +1,13 @@
 <!DOCTYPE html>
 <!--
- | Generated by Apache Maven Doxia at 2014-02-05
+ | Generated by Apache Maven Doxia at 2014-02-11
  | 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="20140205" />
+    <meta name="Date-Revision-yyyymmdd" content="20140211" />
     <meta http-equiv="Content-Language" content="en" />
     <title>Jackrabbit Oak - Known issues</title>
     <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -154,7 +154,7 @@
         <ul class="breadcrumb">
                 
                     
-                  <li id="publishDate">Last Published: 2014-02-05</li>
+                  <li id="publishDate">Last Published: 2014-02-11</li>
                   <li class="divider">|</li> <li id="projectVersion">Version:
0.16-SNAPSHOT</li>
                       
                 
@@ -395,17 +395,6 @@
 <li>Cross workspace operations are not implemented yet  See <a class="externalLink"
href="https://issues.apache.org/jira/browse/OAK-916">OAK-916</a></li>
     
 <li>Workspace Management (creating/deleting workspaces) is not implemented yet  See
<a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-916">OAK-916</a></li>
-    
-<li><tt>Workspace#copy()</tt> is not properly implemented  See <a class="externalLink"
href="https://issues.apache.org/jira/browse/OAK-917">OAK-917</a> and sub tasks
-    
-<ul>
-      
-<li>copy of versionable nodes does not create new version history  See <a class="externalLink"
href="https://issues.apache.org/jira/browse/OAK-918">OAK-918</a></li>
-      
-<li>copy of locked nodes does not remove the lock  See <a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-919">OAK-919</a></li>
-      
-<li>copy of trees with limited read access  See <a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-920">OAK-920</a></li>
-    </ul></li>
   </ul></li>
 </ul>
 <p>In some cases Oak throws Runtime exceptions instead of a properly typed exception.
We are working on correcting this. Please do not work around this by adapting catch clauses
in your application.</p>

Added: jackrabbit/site/live/oak/docs/security/external_login_module.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/external_login_module.html?rev=1567091&view=auto
==============================================================================
--- jackrabbit/site/live/oak/docs/security/external_login_module.html (added)
+++ jackrabbit/site/live/oak/docs/security/external_login_module.html Tue Feb 11 12:32:45
2014
@@ -0,0 +1,734 @@
+<!DOCTYPE html>
+<!--
+ | Generated by Apache Maven Doxia at 2014-02-11
+ | 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="20140211" />
+    <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" />
+    <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>
+                  
+                      <li>      <a href="../from_here.html"  title="From here">From
here</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="Understanding
the node state model">Understanding the node state model</a>
+</li>
+                  
+                      <li>      <a href="../microkernel.html"  title="Microkernel">Microkernel</a>
+</li>
+                  
+                      <li>      <a href="../query.html"  title="Query">Query</a>
+</li>
+                  
+                      <li>      <a href="../blobstore.html"  title="BlobStore">BlobStore</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="../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>
+                          </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-02-11</li>
+                  <li class="divider">|</li> <li id="projectVersion">Version:
0.16-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>
+    
+                          <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>
+    
+                          <a href="../overview.html" title="Overview">
+          <i class="none"></i>
+        Overview</a>
+            </li>
+                  
+      <li>
+    
+                          <a href="../nodestate.html" title="Understanding the node state
model">
+          <i class="none"></i>
+        Understanding the node state model</a>
+            </li>
+                  
+      <li>
+    
+                          <a href="../microkernel.html" title="Microkernel">
+          <i class="none"></i>
+        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 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="../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="../when_things_go_wrong.html" title="When things go
wrong">
+          <i class="none"></i>
+        When things go wrong</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. --><h1>The Oak Security Layer</h1>
+<div class="section">
+<h2>External Login Module<a name="External_Login_Module"></a></h2>
+<div class="section">
+<h3>Overview<a name="Overview"></a></h3>
+<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>
+
+<ul>
+  
+<li>facilitate the use of a 3rd party system for authentication</li>
+  
+<li>simplify populating the oak user manager with identities from a 3rd party system</li>
+</ul>
+<p>what it does not:</p>
+
+<ul>
+  
+<li>provide a transparent oak user manager</li>
+  
+<li>provide a transparent oak principal provider.</li>
+  
+<li>offer services for background synchronization of users and groups</li>
+</ul></div>
+<div class="section">
+<h3>Types of login modules<a name="Types_of_login_modules"></a></h3>
+<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>
+
+<ol style="list-style-type: decimal">
+  
+<li>
+  
+<ol style="list-style-type: decimal">
+    
+<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>
+  </ol></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>
+  
+<li>
+  
+<ol style="list-style-type: decimal">
+    
+<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>
+  </ol></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>
+  
+<li>If the overall <tt>LoginContext</tt> authentication succeeded and the
<tt>LoginModule</tt>&#x2019;s own authentication succeeded, then  the <tt>commit</tt>
method associates the relevant Principals (authenticated identities) and Credentials (authentication
 data such as cryptographic keys) with the Subject located within the <tt>LoginModule</tt>.</li>
+  
+<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>
+<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>
+
+<ol style="list-style-type: decimal">
+  
+<li><b>Required</b></li>
+</ol>
+<p>: The LoginModule is required to succeed.<br /> If it succeeds or fails, authentication
still continues to proceed down the LoginModule list.</p>
+
+<ol style="list-style-type: decimal">
+  
+<li><b>Requisite</b></li>
+</ol>
+<p>: 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).</p>
+
+<ol style="list-style-type: decimal">
+  
+<li><b>Sufficient</b></li>
+</ol>
+<p>: 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.</p>
+
+<ol style="list-style-type: decimal">
+  
+<li><b>Optional</b></li>
+</ol>
+<p>: The LoginModule is not required to succeed.<br /> If it succeeds or fails,
authentication still continues to proceed down the LoginModule list.</p>
+<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 class="section">
+<h4>Authentication and subject population<a name="Authentication_and_subject_population"></a></h4>
+<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 class="section">
+<h4>Password caching<a name="Password_caching"></a></h4>
+<p>In order to prevent extensive authentication calls against the 3rd party system
the user&#x2019;s credentials, in particular the passwords need to be cached. There are
two different way doing this.</p>
+<p>The first way is to only cache the password (encrypted) in memory and expire them
over time. this has the advantage that they are not copied to the local repository and can
be invalidated easier and with a different cycle than the actual user synchronization. It
has the disadvantage, that users won&#x2019;t be able to login, if the 3rd party system
is offline.</p>
+<p>The alternative is to cache the passwords in the repository together with the synced
user. this has the advantage that the 3rd party system can be offline and users will still
be able to login. It has the disadvantage that password are copied to the local system and
stored with the users in a encrypted form. this might be a security concern and might not
comply with security policies. Another disadvantage to this approach is that it only works
for simple password based credentials.</p></div></div>
+<div class="section">
+<h3>Behavior of the External Login Module<a name="Behavior_of_the_External_Login_Module"></a></h3>
+<div class="section">
+<h4>General<a name="General"></a></h4>
+<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. If authentication
succeeds, it must return <tt>true</tt> or throw a <tt>LoginException</tt>
if authentication failed. </p>
+<p>There are some nuances to this and it is important to understand the exact behavior
of the login module(s) so that the JAAS login can be configured correctly:</p>
+<p><b>LoginModuleImpl</b></p>
+<p>The behavior of the default login module is relatively simple, so it is explained
first:</p>
+<p>upon login():</p>
+
+<ul>
+  
+<li>if a user does not exist in the repository (i.e. cannot be provided by the user
manager) it <b>returns <tt>false</tt></b>.</li>
+  
+<li>if a user exists in the repository and the credentials don&#x2019;t match,
it <b>throws <tt>LoginException</tt></b></li>
+  
+<li>if a user exists in the repository and the credentials match, it <b>returns
<tt>true</tt></b></li>
+  
+<li>also, it adds the credentials to the shared state</li>
+  
+<li>also, it adds the login name to the shared state</li>
+  
+<li>also, it calculates the principals and adds them to the private state</li>
+  
+<li>also, it adds the credentials to the private state</li>
+</ul>
+<p>upon commit():</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>
+<p><b>ExternalLoginModule</b></p>
+<p>Note:</p>
+
+<ul>
+  
+<li>users (and groups) that are synced from the 3rd party system contain a <tt>rep:syncSource</tt>
(TBD) property. This allows to identify the external users and distinguish them from others.</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>
+</ul>
+<p>upon login():</p>
+
+<ul>
+  
+<li>if the passwords are cached in memory and the credentials are valid, it puts the
credentials in the private state and <b>returns <tt>true</tt></b></li>
+  
+<li>if the user exists in the 3rd party system and the credentials match, it puts the
credentials in the private state and <b>returns <tt>true</tt></b></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>if the user does not exist in the 3rd party system, it <b>returns <tt>false</tt></b></li>
+</ul>
+<p>upon commit():</p>
+
+<ul>
+  
+<li>if there is no credentials in the private state, it <b>returns <tt>false</tt></b></li>
+  
+<li>if there are credentials in the private state, possibly sync the user and then
propagate the subject and <b>return <tt>true</tt></b></li>
+</ul>
+<!-- * If a user does **not** exist in the 3rd party system, it could be that
+    1. the user was not and will never exist there, and authentication should proceed to
the next login module.
+       This is for example the case for the *admin* user that only exists locally.
+    2. the user was removed from the 3rd party system but still exists locally. In this case,
the user needs to be
+       removed locally and authentication needs to proceed to the next login module
+  
+  So in both cases above, the external login module needs to returns `false` in its `login()`
method.
+  
+* If a user **does** exist in the 3rd party system, it could be that
+    1. no local user with the same userid exists, so the result of the 3rd party authentication
is sufficient enough.
+    2. a local user with the same userid exists (who is not an imported 3rd party user) then
it depends on the
+       configuration if to rely on the external authentication or not. This problem is especially
important to note, 
+       if the external and local users cannot be distinguished by principal name (which is
usually the case).  
+       A good default is to decline authentication (i.e. return `false`) and rely on the
default login module in such
+       cases.
+       
+Any `ExternalLoginModule` needs to be configured as **sufficient** and listed **before**
the default `LoginModuleImpl`. 
+this will lead to the following behaviors:
+
+1. if a (remote) user does not exist in the repository, he is authenticated against the 3rd
party system and...
+    * if the user does not exist in the 3rd party system, the `login()` returns `false` and
the JAAS authentication 
+      continues with the next login module.
+    * if authentication fails, the `login()` throws a `LoginException` and the overall JAAS
authentication continues
+      with the next module. Note that this will allow local user override that also exist
in the external system.
+    * if authentication succeeds, the 1. phase of the JAAS authentication is completed. There
are extra steps that
+      the external login module needs to perform in order to sync the user.
+2. if a (remote) user exists in the repository and he does not need re-authentication, the
`login()` method returns
+   `true` and authentication completes. 
+3. if a (remote) user exists in the repository and he needs re-authentication then the user
is removed from the
+   repository and the same steps as in 1. above apply.
+   
+Since the module is configured as **sufficient** any successful authentication against the
3rd party system will
+complete the first phase of the JAAS authentication and the `ExternalLoginModule` has time
to actually sync the
+user during the 2nd phase in the `commit()` method. But this depends again on the mode of
operation. see pseudo
+code sections below. --></div>
+<div class="section">
+<h4>User Synchronization<a name="User_Synchronization"></a></h4>
+<p>TODO</p></div>
+<div class="section">
+<h4>Groups Synchronization<a name="Groups_Synchronization"></a></h4>
+<p>TODO</p></div></div>
+<div class="section">
+<h3>Configuration<a name="Configuration"></a></h3>
+<div class="section">
+<h4>JAAS Configuration<a name="JAAS_Configuration"></a></h4>
+<p>The external login module as usually configured as <b>sufficient</b>
and <b>before</b> the <tt>LoginModuleImpl</tt>.</p>
+<p>other config</p>
+
+<ul>
+  
+<li>password caching expiration time (0 == disable password caching)</li>
+  
+<li>maximum passwords to cache (i.e. num users)</li>
+  
+<li>synced user expiration</li>
+  
+<li>synced group expiration</li>
+  
+<li>synced membership expiration</li>
+  
+<li>sync groups</li>
+  
+<li>user intermediate path / split dn</li>
+  
+<li>group intermediate path / split dn</li>
+  
+<li>user sync modification attribute</li>
+  
+<li>group sync modification attribute</li>
+  
+<li>autoGroupMembership (user / groups)</li>
+  
+<li>userAttributeMapping</li>
+  
+<li>groupAttributeMapping</li>
+  
+<li>ldap user root (dn)</li>
+  
+<li>ldap group root (dn)</li>
+  
+<li>ldap userIdAttribute</li>
+  
+<li>ldap userFilter</li>
+  
+<li>ldap groupFilter</li>
+  
+<li>ldap groupNameAttribute</li>
+  
+<li>ldap groupMembershipAttribute</li>
+  
+<li>ldap searchTimeout</li>
+  
+<li>groupNestingDepth</li>
+  
+<li>
+<p>local/external user precedence. default is: local wins. best use include/exclude
of user patterns. e.g. admin  should never be external.</p></li>
+  
+<li>password sync or not.</li>
+  
+<li>various cache expiration times (pwd, users, groups)</li>
+  
+<li></li>
+</ul></div>
+<div class="section">
+<h4>pseudo code for users with synced passwords<a name="pseudo_code_for_users_with_synced_passwords"></a></h4>
+
+<div class="source">
+<pre>login() {
+    extract userid and password from credentials    
+    find user in repository
+    if (user exists in repository) {
+        if (user is local user) {
+            // not our user - decline.
+            return false;
+        }
+        if (user needs sync) {
+            flag user to be synced
+        } else {
+            // delegate work to default login module
+            return false;    
+        }
+    }    
+    find user in remote system
+    if (user exists in remote system) {
+        authenticate user against remote system
+        if (authentication successful) {
+            sync user including the provided password locally
+            // delegate further work to default login module
+            return false;
+        } else {
+            throw LoginException();
+        }
+    } else {
+        if (user is flagged) {
+            remove user
+        }
+        return false;
+    }
+}
+commit() {
+    // nothing to do
+    return false;
+}
+</pre></div></div>
+<div class="section">
+<h4>pseudo code for users without synced passwords<a name="pseudo_code_for_users_without_synced_passwords"></a></h4>
+
+<div class="source">
+<pre>login() {
+    extract userid and password from credentials
+    find user in repository
+    if (user exists in repository) {
+        if (user is local user) {
+            // not our user - decline.
+            return false;    
+        }
+        if (user needs sync) {
+            flag user to be synced
+        } else {
+            check if users credentials are cached and not expired
+            if (cached credentials match) {
+                // authentication successful
+                return true;
+            }
+            // here it could be that the user changed his password on the IDP
+            // and he already provided the new password in the login. so we can't
+            // throw the LoginException here but need to revalidate him against the IDP.
+        }
+        clear cached credentials
+    }
+    find user in remote system
+    if (user exists in remote system) {
+        authenticate user against remote system
+        if (authentication successful) {
+            flag user to be  synced
+            cache credentials
+            return true;
+        } else {
+            throw LoginException();
+        }
+    } else {
+        if (user is flagged) {
+            remove user
+        }
+        return false;
+    }
+}
+commit() {
+    if (user needs to be synced ) {
+        sync user
+    }
+    if (this module did authenticate the user) {
+        populate subject with the correct principals
+        return true;
+    } else {
+        return false;
+    }
+}
+</pre></div>
+<!-- references --></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

Propchange: jackrabbit/site/live/oak/docs/security/external_login_module.html
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message