You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jackrabbit.apache.org by an...@apache.org on 2014/02/11 13:32:45 UTC
svn commit: r1567091 - in /jackrabbit/site/live/oak/docs: known_issues.html
security/external_login_module.html
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>’s <tt>login</tt> method gets invoked by the <tt>LoginContext</tt>’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>’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>’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>’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>’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>’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>“the users stored in an external system for authentication and authorization in the Oak content repository”</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’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’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’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’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 © 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