You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jackrabbit.apache.org by th...@apache.org on 2014/10/29 09:38:15 UTC
svn commit: r1635069 - in /jackrabbit/site/live/oak/docs: .DS_Store
coldstandby/coldstandby.html construct.html query.html
security/authentication/differences.html security/overview.html
security/user.html security/user/expiry.html
Author: thomasm
Date: Wed Oct 29 08:38:14 2014
New Revision: 1635069
URL: http://svn.apache.org/r1635069
Log:
OAK-936: Site checkin for project Oak Documentation-1.1-SNAPSHOT
Added:
jackrabbit/site/live/oak/docs/security/user/expiry.html
Modified:
jackrabbit/site/live/oak/docs/.DS_Store
jackrabbit/site/live/oak/docs/coldstandby/coldstandby.html
jackrabbit/site/live/oak/docs/construct.html
jackrabbit/site/live/oak/docs/query.html
jackrabbit/site/live/oak/docs/security/authentication/differences.html
jackrabbit/site/live/oak/docs/security/overview.html
jackrabbit/site/live/oak/docs/security/user.html
Modified: jackrabbit/site/live/oak/docs/.DS_Store
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/.DS_Store?rev=1635069&r1=1635068&r2=1635069&view=diff
==============================================================================
Binary files - no diff available.
Modified: jackrabbit/site/live/oak/docs/coldstandby/coldstandby.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/coldstandby/coldstandby.html?rev=1635069&r1=1635068&r2=1635069&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/coldstandby/coldstandby.html (original)
+++ jackrabbit/site/live/oak/docs/coldstandby/coldstandby.html Wed Oct 29 08:38:14 2014
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2014-10-06
+ | Generated by Apache Maven Doxia at 2014-10-29
| 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="20141006" />
+ <meta name="Date-Revision-yyyymmdd" content="20141029" />
<meta http-equiv="Content-Language" content="en" />
<title>Jackrabbit Oak - Cold Standby</title>
<link rel="stylesheet" href="../css/apache-maven-fluido-1.3.0.min.css" />
@@ -185,7 +185,7 @@
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2014-10-06</li>
+ <li id="publishDate">Last Published: 2014-10-29</li>
<li class="divider">|</li> <li id="projectVersion">Version: 1.1-SNAPSHOT</li>
@@ -431,10 +431,10 @@
<div class="section">
<div class="section">
<h3>What is it?<a name="What_is_it"></a></h3>
-<p>The <i>Cold Standby</i> feature allows one or more clients to connect to a master instance and ensure automatic on-the-fly synchronization of the repository state from the master to the client(s). The sync process is one-way only. Data stored on the master is never changed. The only purpose of this client installation(s) is to garantuee a (almost live) data copy and enable a quick switch from the master to a client installation without data loss.</p></div>
+<p>The <i>Cold Standby</i> feature allows one or more clients to connect to a primary instance and ensure automatic on-the-fly synchronization of the repository state from the master to the client(s). The sync process is one-way only. Data stored on the master is never changed. The only purpose of this client installation(s) is to guarantee an (almost live) data copy and enable a quick switch from the master to a client installation without data loss.</p></div>
<div class="section">
<h3>What is isn’t<a name="What_is_isnt"></a></h3>
-<p>The <i>Cold Standby</i> feature does not garantuee file, filesystem or even repository <b>integrity</b>! If the content of a tar file is corrupted, a file is missing or anything similar happens to the locally stored files the installation will break because these situation or not checked, detected or treated!</p></div>
+<p>The <i>Cold Standby</i> feature does not guarantee file, filesystem or even repository <b>integrity</b>! If the content of a tar file is corrupted, a file is missing or anything similar happens to the locally stored files the installation will break because these situation or not checked, detected or treated!</p></div>
<div class="section">
<h3>How it works<a name="How_it_works"></a></h3>
<p>On the master a TCP port is opened and listening to incoming messages. Currently there a two messages implemented:</p>
@@ -456,31 +456,34 @@
<li>Perform a filesystem based copy of the master repository.</li>
-<li>on the master activate the feature by specifying the runmode <!-- TODO: this must be changed --> <tt>syncmaster</tt>. If the repository is running within a OSGI environment the feature will be activated by a corresponding configuration. <!-- TODO: add some OSGI specific info here --></li>
+<li>on the master activate the feature by specifying the runmode <tt>primary</tt>.</li>
-<li>on the client(s) activate the feature by specifying the runmode <tt>syncslave</tt> (add additional parameters if desired) and specify the path to the repository (-tar) files</li>
+<li>on the client(s) activate the feature by specifying the runmode <tt>standby</tt> (add additional parameters if desired) and specify the path to the repository</li>
<li>start the master and the client(s).</li>
</ol>
<p>You can add the additional argument <tt>--secure true</tt> if you like a SSL secured connection between the client and the master. It must be garantueed that <b>all</b> clients and the master either use secure or standard connections! A mixed configuration will definitely fail.</p>
-<p>The clients specify the master host using the <tt>--host</tt> (default is <tt>localhost</tt>) and <tt>--port</tt> (default is <tt>8023</tt>) arguments. For monitoring reasons (see below) the client(s) must be distinctable. Therefore a generic UUID is automatically created for each running client and this UUID is used to identify the client on the master. If you want to specify the name of the client you can set a system property <tt>failOverID</tt>.</p>
+<p>The clients specify the master host using the <tt>--host</tt> (default is <tt>localhost</tt>) and <tt>--port</tt> (default is <tt>8023</tt>) arguments. For monitoring reasons (see below) the client(s) must be distinctable. Therefore a generic UUID is automatically created for each running client and this UUID is used to identify the client on the master. If you want to specify the name of the client you can set a system property <tt>standbyID</tt>.</p>
<p>To sum it up a typical client command line could be:</p>
<div class="source">
-<pre>java -DfailOverID="Client#1" -jar oak-run.jar syncslave --secure false --host 192.168.0.1 crx-quickstart/repository/segmentstore
+<pre>java -DstandbyID="Client#1" -jar oak-run.jar syncslave --secure false --host 192.168.0.1 crx-quickstart/repository/segmentstore
</pre></div>
<!-- TODO: add the master specific arguments (like the accepted incoming IP ranges) -->
-<p>The master can define the TCP port the feature is listening (default is <tt>8023</tt>) using the <tt>--port</tt> argument. If you want to restrict the communication you can specify a list of allowed IPs or IP ranges….</p></div>
+<p>The master can define the TCP port the feature is listening (default is <tt>8023</tt>) using the <tt>--port</tt> argument. If you want to restrict the communication you can specify a list of allowed IPs or IP ranges….</p>
+<div class="section">
+<h4>OSGi setup<a name="OSGi_setup"></a></h4>
+<p>If the repository is running within a OSGI environment the feature will be activated by a corresponding configuration. See examples attached to the <a class="externalLink" href="https://github.com/apache/jackrabbit-oak/tree/trunk/oak-tarmk-standby/osgi-conf">oak-tarmk-standby module</a></p></div></div>
<div class="section">
<h3>Robustness<a name="Robustness"></a></h3>
<p>The data flow is designed to detect and handle connection and network related problems automatically. All packets are bundled with checksums and as soon as problems with the connection or damaged packets occur retry mechanisms are triggered.</p></div>
<div class="section">
<h3>Monitoring<a name="Monitoring"></a></h3>
-<p>The <i>Cold Standby</i> feature exposes informations using JMX/MBeans. Doing so you can inspect the current state of the client(s) and the master using standard tools like <tt>jconsole</tt> or <tt>jmc</tt> (if running JDK 1.7 or higher). The information can be found if you look for a <tt>org.apache.jackrabbit.oak:type="FailOver"</tt> MBean named <tt>Status</tt>.</p>
+<p>The <i>Cold Standby</i> feature exposes informations using JMX/MBeans. Doing so you can inspect the current state of the client(s) and the master using standard tools like <tt>jconsole</tt> or <tt>jmc</tt> (if running JDK 1.7 or higher). The information can be found if you look for a <tt>org.apache.jackrabbit.oak:type="Standby"</tt> MBean named <tt>Status</tt>.</p>
<div class="section">
<div class="section">
<h5>Client<a name="Client"></a></h5>
-<p>Observing a client you will notice exactly one node (the id is either a generic UUID or the name specified by the <tt>failOverID</tt> system property). This node has five readonly attributes:</p>
+<p>Observing a client you will notice exactly one node (the id is either a generic UUID or the name specified by the <tt>standbyID</tt> system property). This node has five readonly attributes:</p>
<ul>
Modified: jackrabbit/site/live/oak/docs/construct.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/construct.html?rev=1635069&r1=1635068&r2=1635069&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/construct.html (original)
+++ jackrabbit/site/live/oak/docs/construct.html Wed Oct 29 08:38:14 2014
@@ -1,15 +1,15 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2014-10-06
+ | Generated by Apache Maven Doxia at 2014-10-29
| 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="20141006" />
+ <meta name="Date-Revision-yyyymmdd" content="20141029" />
<meta http-equiv="Content-Language" content="en" />
- <title>Jackrabbit Oak - Repository construction</title>
+ <title>Jackrabbit Oak - Repository Construction</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" />
@@ -185,7 +185,7 @@
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2014-10-06</li>
+ <li id="publishDate">Last Published: 2014-10-29</li>
<li class="divider">|</li> <li id="projectVersion">Version: 1.1-SNAPSHOT</li>
@@ -427,41 +427,47 @@
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>Repository construction</h1>
-<p>Oak comes with a simple mechanism for constructing content repositories for use in embedded deployments and test cases. This article describes this mechanism. Deployments in managed environments like OSGi should use the native construction/configuration mechanism of the environment.</p>
-<p>The core class to use is called <tt>Oak</tt> and can be found in the <tt>org.apache.jackrabbit.oak</tt> package inside <tt>oak-core</tt>. It takes a <tt>MicroKernel</tt> instance and wraps it into a <tt>ContentRepository</tt>:</p>
+ limitations under the License. --><h1>Repository Construction</h1>
+<p>Oak comes with a simple and flexible mechanism for constructing content repositories for use in embedded deployments and test cases. This article describes this mechanism. Deployments in managed environments like OSGi should use the native construction/configuration mechanism of the environment.</p>
+<p>First, we construct a Repository instance. Both the <tt>Oak</tt> and the <tt>Jcr</tt> classes support <tt>with()</tt> methods, so you can easily extend the repository with custom functionality if you like. The <tt>OpenSecurityProvider</tt> will cause all login attempts will work. To construct an in-memory repository, use:</p>
<div class="source">
-<pre>MicroKernel kernel = ...;
-ContentRepository repository = new Oak(kernel).createContentRepository();
+<pre> Repository repo = new Jcr(new Oak())
+ .with(new OpenSecurityProvider())
+ .createRepository();
</pre></div>
-<p>For test purposes you can use the default constructor that automatically instantiates an in-memory <tt>MicroKernel</tt> for use with the repository. And if you’re only using the test repository for a single <tt>ContentSession</tt> or just a singe <tt>Root</tt>, then you can shortcut the login steps by using either of the last two statements below:</p>
+<p>To use a MongoDB backend, use:</p>
<div class="source">
-<pre>ContentRepository repository = new Oak().createContentRepository();
-ContentSession session = new Oak().createContentSession();
-Root root = new Oak().createRoot();
+<pre> DB db = new MongoClient("127.0.0.1", 27017).getDB("test2");
+ DocumentNodeStore ns = new DocumentMK.Builder().
+ setMongoDB(db).getNodeStore();
+ Repository repo = new Jcr(new Oak(ns))
+ .with(new OpenSecurityProvider())
+ .createRepository();
</pre></div>
-<p>By default no pluggable components are associated with the created repository, so all login attempts will work and result in full write access. </p>
-<p>To add extra functionality like type validation or indexing support, use the <tt>with()</tt> method. The method takes all kinds of Oak plugins and adds them to the repository to be created. The method returns the Oak instance being used, so you can chain method calls like this:</p>
+<p>To login to the repository and do some work:</p>
<div class="source">
-<pre>ContentRepository repository = new Oak(kernel)
- .with(new InitialContent()) // add initial content
- .with(new DefaultTypeEditor()) // automatically set default types
- .with(new NameValidatorProvider()) // allow only valid JCR names
- .with(new SecurityProviderImpl()) // use the default security
- .with(new PropertyIndexHook()) // simple indexing support
- .with(new PropertyIndexProvider()) // search support for the indexes
- .createContentRepository();
+<pre> Session session = repo.login();
+ Node root = session.getRootNode();
+ if (root.hasNode("hello")) {
+ Node hello = root.getNode("hello");
+ long count = hello.getProperty("count").getLong();
+ hello.setProperty("count", count + 1);
+ System.out.println("found the hello node, count = " + count);
+ } else {
+ System.out.println("creating the hello node");
+ root.addNode("hello").setProperty("count", 1);
+ }
+ session.save();
</pre></div>
-<p>As you can see, constructing a fully featured JCR repository like this will require quite a few plugins. To avoid having to specify them all whenever constructing a new repository, we also have a class called <tt>Jcr</tt> in the <tt>org.apache.jackrabbit.oak.jcr</tt> package in <tt>oak-jcr</tt>. That class works much like the <tt>Oak</tt> class, but it constructs <tt>javax.jcr.Repository</tt> instances instead of <tt>ContentRepositories</tt> and automatically includes all the plugin components needed for proper JCR functionality:</p>
+<p>To logout and close the backend store:</p>
<div class="source">
-<pre>MicroKernel kernel = ...;
-Repository repository = new Jcr(kernel).createRepository();
+<pre> session.logout();
+ ns.dispose();
</pre></div>
-<p>The <tt>Jcr</tt> class supports all the same <tt>with()</tt> methods as the <tt>Oak</tt> class does, so you can easily extend the constructed JCR repository with custom functionality if you like. For test purposes the <tt>Jcr</tt> class also has an empty default constructor that works like the one in the <tt>Oak</tt> class.</p>
</div>
</div>
</div>
Modified: jackrabbit/site/live/oak/docs/query.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/query.html?rev=1635069&r1=1635068&r2=1635069&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/query.html (original)
+++ jackrabbit/site/live/oak/docs/query.html Wed Oct 29 08:38:14 2014
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2014-10-06
+ | Generated by Apache Maven Doxia at 2014-10-29
| 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="20141006" />
+ <meta name="Date-Revision-yyyymmdd" content="20141029" />
<meta http-equiv="Content-Language" content="en" />
<title>Jackrabbit Oak - The Query Engine</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" />
@@ -185,7 +185,7 @@
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2014-10-06</li>
+ <li id="publishDate">Last Published: 2014-10-29</li>
<li class="divider">|</li> <li id="projectVersion">Version: 1.1-SNAPSHOT</li>
@@ -599,7 +599,21 @@ org.apache.jackrabbit.oak.query.QueryEng
}
</pre></div>
<p><b>Note on <tt>propertyNames</tt></b> Adding a property index definition that contains two or more properties will only include nodes that have <i>all</i> specified properties present. This is different than adding a dedicated property index for each and letting the query engine make use of them.</p>
-<p><b>Note</b> Is is currently not possible to add more than one property index on the same property name, even if it might be used in various combinations with other property names. This rule is not enforced in any way, but the behavior is undefined, one of the defined indexes will be updated while the others will simply be ignored by the indexer which can result in empty result sets at query time.</p></div>
+<p><b>Note</b> Is is currently not possible to add more than one property index on the same property name, even if it might be used in various combinations with other property names. This rule is not enforced in any way, but the behavior is undefined, one of the defined indexes will be updated while the others will simply be ignored by the indexer which can result in empty result sets at query time.</p>
+<div class="section">
+<h4>Reindexing<a name="Reindexing"></a></h4>
+<p>Reindexing a property index happens synchronously by setting the <b><tt>reindex</tt></b> flag to <b><tt>true</tt></b>. This means that the first #save call will generate a full repository traversal with the purpose of building the index content and it might take a long time.</p>
+<p>Asynchronous reindexing of a property index is available as of OAK-1456. The way this works is by pushing the property index updates to a background job and when the indexing process is done, the property definition will be switched back to a synchronous updates mode. To enable this async reindex behaviour you need to first set the <b><tt>reindex-async</tt></b> and <b><tt>reindex</tt></b> flags to <b><tt>true</tt></b> (call #save). You can verify the initial setup worked by refreshing the index definition node and looking for the <b><tt>async</tt></b> = <b><tt>async-reindex</tt></b> property. Next you need to start the dedicated background job via a jmx call to the <b><tt>PropertyIndexAsyncReindex#startPropertyIndexAsyncReindex</tt></b> MBean.</p>
+<p>Example:</p>
+
+<div class="source">
+<pre>{
+ NodeBuilder index = root.child("oak:index");
+ index.child("property")
+ .setProperty("reindex-async", true)
+ .setProperty("reindex", true);
+}
+</pre></div></div></div>
<div class="section">
<h3>The Ordered Index<a name="The_Ordered_Index"></a></h3>
<p>Extension of the Property index will keep the order of the indexed property persisted in the repository.</p>
Modified: jackrabbit/site/live/oak/docs/security/authentication/differences.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/authentication/differences.html?rev=1635069&r1=1635068&r2=1635069&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/authentication/differences.html (original)
+++ jackrabbit/site/live/oak/docs/security/authentication/differences.html Wed Oct 29 08:38:14 2014
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2014-10-06
+ | Generated by Apache Maven Doxia at 2014-10-29
| 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="20141006" />
+ <meta name="Date-Revision-yyyymmdd" content="20141029" />
<meta http-equiv="Content-Language" content="en" />
<title>Jackrabbit Oak - Authentication : Differences wrt Jackrabbit 2.x</title>
<link rel="stylesheet" href="../../css/apache-maven-fluido-1.3.0.min.css" />
@@ -185,7 +185,7 @@
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2014-10-06</li>
+ <li id="publishDate">Last Published: 2014-10-29</li>
<li class="divider">|</li> <li id="projectVersion">Version: 1.1-SNAPSHOT</li>
@@ -451,7 +451,7 @@
</ul></div>
<div class="section">
<h5>Pre-Authentication<a name="Pre-Authentication"></a></h5>
-<p>Oak provides two different mechanisms to create pre-authentication that doesn’t involve the repositories internal authentication mechanism for credentials validation. See the corresponding section <a href="security/authentication/preauthentication.html">Pre-Authentication</a> for details and examples.</p>
+<p>Oak provides two different mechanisms to create pre-authentication that doesn’t involve the repositories internal authentication mechanism for credentials validation. See the corresponding section <a href="preauthentication.html">Pre-Authentication</a> for details and examples.</p>
<ul>
Modified: jackrabbit/site/live/oak/docs/security/overview.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/overview.html?rev=1635069&r1=1635068&r2=1635069&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/overview.html (original)
+++ jackrabbit/site/live/oak/docs/security/overview.html Wed Oct 29 08:38:14 2014
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2014-10-06
+ | Generated by Apache Maven Doxia at 2014-10-29
| 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="20141006" />
+ <meta name="Date-Revision-yyyymmdd" content="20141029" />
<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" />
@@ -185,7 +185,7 @@
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2014-10-06</li>
+ <li id="publishDate">Last Published: 2014-10-29</li>
<li class="divider">|</li> <li id="projectVersion">Version: 1.1-SNAPSHOT</li>
@@ -506,6 +506,8 @@
<li><a href="user/authorizableaction.html">Authorizable Actions</a></li>
<li><a href="user/query.html">Searching Users and Groups</a></li>
+
+<li><a href="user/expiry.html">Password Expiry and Force Initial Password Change</a></li>
</ul></div></div>
</div>
</div>
Modified: jackrabbit/site/live/oak/docs/security/user.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/user.html?rev=1635069&r1=1635068&r2=1635069&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/user.html (original)
+++ jackrabbit/site/live/oak/docs/security/user.html Wed Oct 29 08:38:14 2014
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia at 2014-10-06
+ | Generated by Apache Maven Doxia at 2014-10-29
| 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="20141006" />
+ <meta name="Date-Revision-yyyymmdd" content="20141029" />
<meta http-equiv="Content-Language" content="en" />
<title>Jackrabbit Oak - User Management</title>
<link rel="stylesheet" href="../css/apache-maven-fluido-1.3.0.min.css" />
@@ -185,7 +185,7 @@
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2014-10-06</li>
+ <li id="publishDate">Last Published: 2014-10-29</li>
<li class="divider">|</li> <li id="projectVersion">Version: 1.1-SNAPSHOT</li>
@@ -605,6 +605,18 @@
</ul>
<p>In the default implementation the corresponding configuration parameter is <tt>PARAM_AUTHORIZABLE_NODE_NAME</tt>. The default name generator can be replace by installing an OSGi service that implementats the <tt>AuthorizableNodeName</tt> interface. In a non-OSGi setup the user configuration must be initialized with configuration parameters that provide the custom generator implementation.</p></div>
<div class="section">
+<h4>Password Expiry and Force Initial Password Change<a name="Password_Expiry_and_Force_Initial_Password_Change"></a></h4>
+<p>Since Oak 1.1.0 the default user management and authentication implementation provides password expiry and initial password change.</p>
+<p>By default these features are disabled. The corresponding configuration options are</p>
+
+<ul>
+
+<li><tt>PARAM_PASSWORD_MAX_AGE</tt>: number of days until the password expires.</li>
+
+<li><tt>PARAM_PASSWORD_INITIAL_CHANGE</tt>: boolean flag to enable this feature.</li>
+</ul>
+<p>See section <a href="user/expiry.html">Password Expiry and Force Initial Password Change</a> for details.</p></div>
+<div class="section">
<h4>Utilities<a name="Utilities"></a></h4>
<p><tt>org.apache.jackrabbit.oak.spi.security.user.*</tt></p>
@@ -766,6 +778,24 @@
<tr class="a">
+<td><tt>PARAM_PASSWORD_MAX_AGE</tt> </td>
+
+<td>int </td>
+
+<td>0 </td>
+ </tr>
+
+<tr class="b">
+
+<td><tt>PARAM_PASSWORD_INITIAL_CHANGE</tt> </td>
+
+<td>boolean </td>
+
+<td>false </td>
+ </tr>
+
+<tr class="a">
+
<td> </td>
<td> </td>
@@ -847,6 +877,8 @@ Repository repo = new Jcr(new Oak()).wit
<li><a href="user/authorizableaction.html">Authorizable Actions</a></li>
<li><a href="user/query.html">Searching Users and Groups</a></li>
+
+<li><a href="user/expiry.html">Password Expiry and Force Initial Password Change</a></li>
</ul>
<!-- hidden references --></div></div>
</div>
Added: jackrabbit/site/live/oak/docs/security/user/expiry.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/user/expiry.html?rev=1635069&view=auto
==============================================================================
--- jackrabbit/site/live/oak/docs/security/user/expiry.html (added)
+++ jackrabbit/site/live/oak/docs/security/user/expiry.html Wed Oct 29 08:38:14 2014
@@ -0,0 +1,532 @@
+<!DOCTYPE html>
+<!--
+ | Generated by Apache Maven Doxia at 2014-10-29
+ | 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="20141029" />
+ <meta http-equiv="Content-Language" content="en" />
+ <title>Jackrabbit Oak - Password Expiry and Force Initial Password Change</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="../../architecture/overview.html" title="Overview">Overview</a>
+</li>
+
+ <li> <a href="../../architecture/nodestate.html" title="The Node State Model">The Node State Model</a>
+</li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Main APIs <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="http://www.day.com/specs/jcr/2.0/index.html" title="JCR API">JCR API</a>
+</li>
+
+ <li> <a href="../../oak_api/overview.html" title="Oak API">Oak API</a>
+</li>
+
+ <li> <a href="../../nodestore/overview.html" title="NodeStore and MicroKernel API">NodeStore and MicroKernel API</a>
+</li>
+ </ul>
+ </li>
+ <li class="dropdown">
+ <a href="#" class="dropdown-toggle" data-toggle="dropdown">Features and Plugins <b class="caret"></b></a>
+ <ul class="dropdown-menu">
+
+ <li> <a href="../../query.html" title="Query">Query</a>
+</li>
+
+ <li> <a href="../../security/overview.html" title="Security">Security</a>
+</li>
+
+ <li> <a href="../../plugins/blobstore.html" title="BlobStore">BlobStore</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="../../command_line.html" title="Command Line Tools">Command Line Tools</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="../../coldstandby/coldstandby.html" title="Cold Standby">Cold Standby</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-10-29</li>
+ <li class="divider">|</li> <li id="projectVersion">Version: 1.1-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="../../architecture/overview.html" title="Overview">
+ <i class="none"></i>
+ Overview</a>
+ </li>
+
+ <li>
+
+ <a href="../../architecture/nodestate.html" title="The Node State Model">
+ <i class="none"></i>
+ The Node State Model</a>
+ </li>
+ <li class="nav-header">Main APIs</li>
+
+ <li>
+
+ <a href="http://www.day.com/specs/jcr/2.0/index.html" class="externalLink" title="JCR API">
+ <i class="none"></i>
+ JCR API</a>
+ </li>
+
+ <li>
+
+ <a href="../../oak_api/overview.html" title="Oak API">
+ <i class="none"></i>
+ Oak API</a>
+ </li>
+
+ <li>
+
+ <a href="../../nodestore/overview.html" title="NodeStore and MicroKernel API">
+ <i class="none"></i>
+ NodeStore and MicroKernel API</a>
+ </li>
+ <li class="nav-header">Features and Plugins</li>
+
+ <li>
+
+ <a href="../../query.html" title="Query">
+ <i class="none"></i>
+ Query</a>
+ </li>
+
+ <li>
+
+ <a href="../../security/overview.html" title="Security">
+ <i class="none"></i>
+ Security</a>
+ </li>
+
+ <li>
+
+ <a href="../../plugins/blobstore.html" title="BlobStore">
+ <i class="none"></i>
+ BlobStore</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="../../command_line.html" title="Command Line Tools">
+ <i class="none"></i>
+ Command Line Tools</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="../../coldstandby/coldstandby.html" title="Cold Standby">
+ <i class="none"></i>
+ Cold Standby</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/docs/" 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>Password Expiry and Force Initial Password Change<a name="Password_Expiry_and_Force_Initial_Password_Change"></a></h2>
+<div class="section">
+<h3>General<a name="General"></a></h3>
+<p>Oak provides functionality to expire passwords of users as well as force users to change their password upon initial (first-time) login.</p></div>
+<div class="section">
+<h3>Password Expiry<a name="Password_Expiry"></a></h3>
+<p>Administrators may configure passwords to expire within a configurable amount of time (days). A user whose password has expired will no longer be able to obtain a session/login.</p></div>
+<div class="section">
+<h3>Force Initial Password Change<a name="Force_Initial_Password_Change"></a></h3>
+<p>An administrator may configure the system such that a user is forced to set a new password upon first login. This is a special form of Password Expiry above, in that upon creation a user account’s password is expired by default. Upon initial login, the user will not be able to obtain a session/login and the password needs to be changed prior to a next attempt. For specifying the new password, the initial password has to be provided.</p></div>
+<div class="section">
+<h3>Configuration of Expiry / Force Initial Password Change<a name="Configuration_of_Expiry__Force_Initial_Password_Change"></a></h3>
+<p>An administrator may enable password expiry and initial password change via the <i>org.apache.jackrabbit.oak.security.user.UserConfigurationImpl</i> OSGi configuration. By default expiry is disabled.</p>
+<p>The following configuration options are supported:</p>
+
+<ul>
+
+<li>Maximum Password Age (<i>maxPasswordAge</i>, days): When greater 0 enables password expiry and sets the expiration time in days.</li>
+
+<li>Change Password On First Login (<i>initialPasswordChange</i>, true|false): When enabled, forces users to change their password upon first login.</li>
+</ul></div>
+<div class="section">
+<h3>How it works<a name="How_it_works"></a></h3>
+<div class="section">
+<h4>Definition of Expired Password<a name="Definition_of_Expired_Password"></a></h4>
+<p>An expired password is defined as follows:</p>
+
+<ul>
+
+<li>The current date-time is after or on the date-time + maxPasswordAge specified in a <i>rep:passwordLastModified</i> property</li>
+
+<li>OR: Expiry and/or Enforce Password Change is enabled, but no <i>rep:passwordLastModified</i> property exists</li>
+</ul>
+<p>For the above, a password node <i>rep:pw</i> and a property <i>rep:passwordLastModified</i>, governed by a new <i>rep:Password</i> node type and located in the user’s home, have been introduced, leaving open future enhancements to password management (such as password policies, history, et al):</p>
+<div class="section">
+<h5>Node Type rep:Password<a name="Node_Type_rep:Password"></a></h5>
+
+<div class="source">
+<pre>[rep:Password]
+ - * (UNDEFINED) protected
+ - * (UNDEFINED) protected multiple
+</pre></div></div>
+<div class="section">
+<h5>Node rep:passwords and Property rep:passwordLastModified<a name="Node_rep:passwords_and_Property_rep:passwordLastModified"></a></h5>
+
+<div class="source">
+<pre>[rep:User] > rep:Authorizable, rep:Impersonatable
+ + rep:pw (rep:Password) = rep:Password protected
+ ...
+</pre></div>
+<p>The <i>rep:pw</i> node and the <i>rep:passwordLastModified</i> property are defined protected in order to guard against the user modifying (overcoming) her password expiry. The new sub-node also has the advantage of allowing repository consumers to e.g. register specific commit hooks / actions on such a node.</p>
+<p>In the future the <i>rep:password</i> property on the user node may be migrated to the <i>rep:pw</i> sub-node.</p></div></div>
+<div class="section">
+<h4>User Creation With Default Expired Password<a name="User_Creation_With_Default_Expired_Password"></a></h4>
+<p>Upon initial creation of a user, the <i>rep:passwordLastModified</i> property is omitted. If expiry or <i>initialPasswordChange</i> are enabled, the absence of the property will be interpreted as immediate expiry of the password. When subsequently the user changes her password via <i>User#changePassword</i>, the <i>rep:passwordLastModified</i> property is set and henceforth interpreted.</p></div>
+<div class="section">
+<h4>Core Authentication Password Expiry Aware<a name="Core_Authentication_Password_Expiry_Aware"></a></h4>
+<p>A login module must throw a <i>javax.security.auth.login.CredentialExpiredException</i> upon encountering an expired password. A consumer implementation can then differentiate between a failed login (due to a wrong password specified) and an expired password, allowing the consumer to take action, e.g. to redirect to a change password form.</p>
+<p>In Oak, the Authentication (currently <i>UserAuthentication</i>) implementation compares within its <i>#authenticate()</i> method the system time with the value stored in the rep:passwordLastModified_ and throws a <i>CredentialExpiredException</i> if now is after or on the date-time specified by the value.</p>
+<p>In the case of <i>initialPasswordChange</i> a password is considered expired if no <i>rep:passwordLastModified</i> property can be found on login.</p>
+<p>Both expiry and force initial password change are checked <i>after</i> regular credentials verification, so as to prevent an attacker identifying valid users by being redirected to a change password form upon expiry.</p></div>
+<div class="section">
+<h4>Oak JCR XML Import<a name="Oak_JCR_XML_Import"></a></h4>
+<p>When users are imported via the Oak JCR XML importer, the expiry relevant nodes and property are supported. If the XML specifies a <i>rep:pw</i> node and optionally a <i>rep:passwordLastModified</i> property, these are imported, irrespective of the password expiry or force initial password change being enabled in the configuration. If they’re enabled, the imported property will be used in the normal login process as described above. If not enabled, the imported property will have no effect.</p>
+<p>On the other hand, if the imported user already exists, potentially existing <i>rep:passwordLastModified</i> properties will be overwritten with the value from the import. If password expiry is enabled, this may cause passwords to expire earlier or later than anticipated, governed by the new value. Also, an import may create such a property where none previously existed, thus effectively cancelling the need to change the password on first login - if the feature is enabled.</p>
+<p>Therefore customers using the importer in such fashion should be aware of the potential need to enable password expiry/force initial password change for the imported data to make sense, and/or the effect on already existing/overwritten data.</p></div>
+<div class="section">
+<h4>Changing an Expired Password<a name="Changing_an_Expired_Password"></a></h4>
+<p>Oak supports changing a user’s expired password as part of the normal login process.</p>
+<p>Consumers of the repository already specify <i>javax.jcr.SimpleCredentials</i> during login, as part of the normal authentication process. In order to change the password for an expired user, the login may be called with the affected user’s <i>javax.jcr.SimpleCredentials</i>, while additionally providing the new password via a credentials attribute <i>newPassword</i>.</p>
+<p>After verifying the user’s credentials, <i>before</i> checking expiry, said attribute is then used by the <i>UserAuthentication</i> to change the user’s password.</p>
+<p>This way the user can change the password while the expiry check succeeds (password expired = false) and a session/login is provided at the same time.</p>
+<p>This method of changing password via the normal login call only works if a user’s password is in fact expired and cannot be used for regular password changes (attribute is ignored, use <i>User#changePassword</i> directly instead).</p></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_thin_badge.js"></script>
+ </div>
+ </div>
+ </footer>
+ </body>
+</html>
\ No newline at end of file