You are viewing a plain text version of this content. The canonical link for it is here.
Posted to oak-commits@jackrabbit.apache.org by an...@apache.org on 2016/02/12 11:14:10 UTC
svn commit: r1729970 - in /jackrabbit/oak/trunk:
oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/user/action/
oak-core/src/main/resources/org/apache/jackrabbit/oak/plugins/nodetype/write/
oak-doc/src/site/markdown/security/authorization/ ...
Author: angela
Date: Fri Feb 12 10:14:09 2016
New Revision: 1729970
URL: http://svn.apache.org/viewvc?rev=1729970&view=rev
Log:
OAK-3946 - Document oak-authorization-cug (WIP)
minor improvement: security documentation, javadoc, since tags with node type definitions
Modified:
jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/user/action/AuthorizableAction.java
jackrabbit/oak/trunk/oak-core/src/main/resources/org/apache/jackrabbit/oak/plugins/nodetype/write/builtin_nodetypes.cnd
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/cug.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/authorizableaction.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/default.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/expiry.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/history.md
Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/user/action/AuthorizableAction.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/user/action/AuthorizableAction.java?rev=1729970&r1=1729969&r2=1729970&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/user/action/AuthorizableAction.java (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/user/action/AuthorizableAction.java Fri Feb 12 10:14:09 2016
@@ -37,9 +37,15 @@ import org.apache.jackrabbit.oak.spi.sec
* <li>{@link #onPasswordChange User password modification}.</li>
* </ul>
*
- * Note, that in contrast to {@link org.apache.jackrabbit.oak.spi.commit.Validator}
+ * <p>Please be aware, that in contrast to {@link org.apache.jackrabbit.oak.spi.commit.Validator}
* the authorizable actions will only be enforced when user related content
- * modifications are generated by using the user management API.
+ * modifications are generated by using the user management API.</p>
+ *
+ * </p>
+ * <strong>Note:</strong> user management operations are defined to perform transient
+ * modifications, which require an explicit save/commit call by the API consumer to
+ * be persisted. For consistency, implementations of the {@code AuthorizableAction} are expected
+ * to adhere to this rule and must not pre-emptively call {@code Root.commit()}.</p>
*
* @see org.apache.jackrabbit.oak.spi.security.ConfigurationParameters
* @since OAK 1.0
Modified: jackrabbit/oak/trunk/oak-core/src/main/resources/org/apache/jackrabbit/oak/plugins/nodetype/write/builtin_nodetypes.cnd
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/resources/org/apache/jackrabbit/oak/plugins/nodetype/write/builtin_nodetypes.cnd?rev=1729970&r1=1729969&r2=1729970&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/resources/org/apache/jackrabbit/oak/plugins/nodetype/write/builtin_nodetypes.cnd (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/resources/org/apache/jackrabbit/oak/plugins/nodetype/write/builtin_nodetypes.cnd Fri Feb 12 10:14:09 2016
@@ -735,7 +735,7 @@
- rep:password (STRING) protected
- rep:disabled (STRING) protected
-[rep:SystemUser] > rep:User
+[rep:SystemUser] > rep:User /* @since oak 1.1.0 */
[rep:Group] > rep:Authorizable, rep:MemberReferences
+ rep:members (rep:Members) = rep:Members multiple protected VERSION /* @deprecated since oak 1.0 (remove?) */
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/cug.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/cug.md?rev=1729970&r1=1729969&r2=1729970&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/cug.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/cug.md Fri Feb 12 10:14:09 2016
@@ -20,7 +20,25 @@ Managing Access with "Closed User Groups
### General
-_todo_
+The `oak-authorization-cug` module provides a alternative authorization model
+intended to limit read access to certain paths for a selected, small set of
+`Principal`s.
+
+These restricted areas called `CUG` are marked by a dedicated policy type and
+effectively prevent read-access for anybody not explicitly allowed.
+
+This implies that the CUG-authorization model solely evaluates and enforces read
+access to regular nodes and properties. Therefore it may only be used as an additional,
+complementary authorization scheme while the primary module(s) is/are in charge
+of enforcing the complete set of permissions including read/write access,
+repository operations and any kind of special permissions like reading and
+writing access control content. See section [Combining Multiple Authorization Models](composite.html)
+for information aggregating access control management and permission evaluation
+from different implementations.
+
+By default the `oak-authorization-cug` model is disabled and it requires
+manual [configuration](#configuration) steps in order to plug it into the Oak
+security setup.
<a name="jackrabbit_api"/>
### Jackrabbit API
@@ -37,8 +55,27 @@ for details and the methods exposed by t
<a name="api_extensions"/>
### API Extensions
-_todo: CugPolicy_
-_todo: CugExclude_
+The module comes with the following extension in the
+`org.apache.jackrabbit.oak.spi.security.authorization.cug` package space:
+
+- [CugPolicy] marker interface extending `PrincipalSetPolicy`
+- [CugExclude]
+
+#### CugExclude
+
+The `CugExclude` allows to customize the set of principals excluded from evaluation
+of the restricted areas. These principals will consequently never be prevented
+from accessing any of the configured CUGs and read permission evaluation is
+delegated to any other module present in the setup.
+
+The feature ships with two implementations out of the box:
+
+- `CugExclude.Default`: Default implementation that excludes admin, system and
+system-user principals. It will be used as fallback if no other implementation is configured.
+- `CugExcludeImpl`: OSGi service extending from the default that additionally
+allows to excluded principals by their names at runtime.
+
+See also section [Pluggability](#pluggability) below.
### Implementation Details
@@ -78,9 +115,10 @@ all of type `AccessControl` with the fol
_todo_
-#### Configuration Parameters
+#### Configuration Parameters of the CugConfiguration
-The implementation supports the following configuration parameters:
+The `org.apache.jackrabbit.oak.spi.security.authorization.cug.impl.CugConfiguration`
+supports the following configuration parameters:
| Parameter | Type | Default | Description |
|-----------------------------|----------------|----------|-------------|
@@ -89,11 +127,37 @@ The implementation supports the followin
| `PARAM_RANKING` | int | 200 | Ranking within the composite authorization setup. |
| | | | |
+#### Configure the Excluded Principals
+
+The CUG authorization setup can be further customized by enabling the
+`CugExcludeImpl` service with allows to list additional principals that need
+to be excluded from the evaluation of restricted areas:
+
+| Parameter | Type | Default | Description |
+|-----------------------------|----------------|----------|-------------|
+| `principalNames` | Set\<String\> | \- | Name of principals that are always excluded from CUG evaluation. |
+| | | | |
+
+Note: this is an optional feature that may be used to extend the default exclusion.
+Alternatively, it is possible to plug a custom `CugExclude` implementation matching
+specific needs (see [below](#pluggability).
+
<a name="pluggability"/>
### Pluggability
+#### Deploy CugConfiguration
+
+##### OSGi Setup
+
_todo: deploying cug-authorization in an oak repository_
-_todo: customize cug-authorization by providing custom CugExclude implementation_
+
+##### Non-OSGi Setup
+
+_todo: deploying cug-authorization in an oak repository_
+
+#### Customize CugExclude
+
+_todo: customize cug-authorization by providing custom CugExclude implementation_
##### Examples
@@ -101,4 +165,5 @@ _todo_
<!-- hidden references -->
[Principal]: http://docs.oracle.com/javase/7/docs/api/java/security/Principal.html
-[AccessControlPolicy]: http://www.day.com/specs/javax.jcr/javadocs/jcr-2.0/javax/jcr/security/AccessControlPolicy.html
\ No newline at end of file
+[AccessControlPolicy]: http://www.day.com/specs/javax.jcr/javadocs/jcr-2.0/javax/jcr/security/AccessControlPolicy.html
+[CugPolicy]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/cug/CugPolicy.html
\ No newline at end of file
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/authorizableaction.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/authorizableaction.md?rev=1729970&r1=1729969&r2=1729970&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/authorizableaction.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/authorizableaction.md Fri Feb 12 10:14:09 2016
@@ -41,10 +41,14 @@ The following public interfaces are prov
- [AuthorizableActionProvider]
The `AuthorizableAction` interface itself allows to perform validations or write
-addition application specific content while executing user management related
-write operations. Note that the actions are consequently executed as part of the
-transient modifications and contrast to `org.apache.jackrabbit.oak.spi.commit.CommitHook`s
-that are triggered upon persisting content modifications.
+additional application specific content while executing user management related
+write operations. Therefore these actions are executed as part of the transient
+user management modifications. This contrasts to `org.apache.jackrabbit.oak.spi.commit.CommitHook`s
+which in turn are only triggered once modifications are persisted.
+
+Consequently, implementations of the `AuthorizableAction` interface are expected
+to adhere to this rule and perform transient repository operation or validation.
+They must not force changes to be persisted by calling `org.apache.jackrabbit.oak.api.Root.commit()`.
### Default Implementations
@@ -72,7 +76,6 @@ As in Jackrabbit 2.x the actions are exe
target operation will fail if any of the configured actions fails (e.g. due to
insufficient permissions by the editing Oak ContentSession).
-
### Pluggability
The default security setup as present with Oak 1.0 is able to provide custom
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/default.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/default.md?rev=1729970&r1=1729969&r2=1729970&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/default.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/default.md Fri Feb 12 10:14:09 2016
@@ -76,8 +76,8 @@ guest login.
#### Everyone Group
The default user management implementation in Oak contains special handling for
-the optional group that represents _everyone_, which is marked by the reserved
-name [everyone] and corresponds to the `EveryonePrincipal`.
+the optional group that represents the [everyone] principal, which is marked by
+the reserved principal name and by definition has all other principals as members.
This special group always contains all Authorizable as member and cannot be edited
with user management API. As of OAK this fact is consistently reflected in all
@@ -100,8 +100,7 @@ of the underlaying JCR node but only com
#### Creating Authorizables
* The `rep:password` property is no longer defined to be mandatory. Therefore a new user might be created without specifying a password. Note however, that `User#changePassword` does not allow to remove the password property.
-* `UserManager#createGroup(Principal)` will no longer generate a groupID in case the principal name collides with an existing user or group ID. This has been considered redundant as the Jackrabbit API in the mean time added `UserManager#createGroup(String groupID)`.
-* Since OAK is designed to scale with flat hierarchies the former configuration options `autoExpandTree` and `autoExpandSize` are no longer supported.
+* Since version 1.1.0 Oak supports the new API to create dedicated system users [JCR-3802](https://issues.apache.org/jira/browse/JCR-3802).
#### Query
@@ -134,31 +133,20 @@ import. Other differences compared to Ja
Since Oak 1.1.0 the default user management and authentication implementation
provides password expiry and initial password change.
-By default these features are disabled. The corresponding configuration options
-are
-
-- `PARAM_PASSWORD_MAX_AGE`: number of days until the password expires.
-- `PARAM_PASSWORD_INITIAL_CHANGE`: boolean flag to enable this feature.
-
-See section [Password Expiry and Force Initial Password Change](expiry.html)
+By default these features are disabled. See section [Password Expiry and Force Initial Password Change](expiry.html)
for details.
#### Password History
Since Oak 1.3.3 the default user management implementation provides password
-history support.
-
-By default this feature is disabled. The corresponding configuration option is
-
-- `PARAM_PASSWORD_HISTORY_SIZE`: number of changed passwords to remember.
+history support. By default this feature is disabled.
See section [Password History](history.html) for details.
-
### User/Group Representation in the Repository
The following block lists the built-in node types related to user management tasks:
-
+
[rep:Authorizable] > mix:referenceable, nt:hierarchyNode
abstract
+ * (nt:base) = nt:unstructured VERSION
@@ -166,20 +154,41 @@ The following block lists the built-in n
- rep:authorizableId (STRING) protected /* @since oak 1.0 */
- * (UNDEFINED)
- * (UNDEFINED) multiple
-
+
+ [rep:User] > rep:Authorizable, rep:Impersonatable
+ + rep:pwd (rep:Password) = rep:Password protected /* @since oak 1.1.0 */
+ - rep:password (STRING) protected
+ - rep:disabled (STRING) protected
+
+ [rep:SystemUser] > rep:User /* @since oak 1.1.0 */
+
+ [rep:Impersonatable]
+ mixin
+ - rep:impersonators (STRING) protected multiple
+
+ /* @since oak 1.1.0 */
+ [rep:Password]
+ - * (UNDEFINED) protected
+ - * (UNDEFINED) protected multiple
+
[rep:Group] > rep:Authorizable, rep:MemberReferences
- + rep:members (rep:Members) = rep:Members multiple protected VERSION /* @deprecated */
- + rep:membersList (rep:MemberReferencesList) = rep:MemberReferencesList protected COPY
-
- /** @since oak 1.0 */
+ + rep:members (rep:Members) = rep:Members multiple protected VERSION /* @deprecated since oak 1.0 */
+ + rep:membersList (rep:MemberReferencesList) = rep:MemberReferencesList protected COPY /* @since oak 1.0 */
+
+
+ [rep:AuthorizableFolder] > nt:hierarchyNode
+ + * (rep:Authorizable) = rep:User VERSION
+ + * (rep:AuthorizableFolder) = rep:AuthorizableFolder VERSION
+
+ /* @since oak 1.0 */
[rep:MemberReferences]
- rep:members (WEAKREFERENCE) protected multiple < 'rep:Authorizable'
-
- /** @since oak 1.0 */
+
+ /* @since oak 1.0 */
[rep:MemberReferencesList]
+ * (rep:MemberReferences) = rep:MemberReferences protected COPY
-
- /** @deprecated since oak 1.0 */
+
+ /* @deprecated since oak 1.0 */
[rep:Members]
orderable
+ * (rep:Members) = rep:Members protected multiple
@@ -309,3 +318,4 @@ implementation.
[everyone]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/principal/EveryonePrincipal.html#NAME
[UserConfiguration]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/user/UserConfiguration.html
[UserAuthenticationFactory]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/user/UserAuthenticationFactory.html
+[Authentication]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/Authentication.html
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/expiry.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/expiry.md?rev=1729970&r1=1729969&r2=1729970&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/expiry.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/expiry.md Fri Feb 12 10:14:09 2016
@@ -20,8 +20,8 @@ Password Expiry and Force Initial Passwo
### General
-Oak provides functionality to expire passwords of users as well as force
-users to change their password upon initial (first-time) login.
+Since version 1.1.0 Oak provides functionality to expire passwords of users as
+well as force users to change their password upon initial (first-time) login.
### Password Expiry
@@ -39,18 +39,23 @@ to obtain a session/login and the passwo
to a next attempt. For specifying the new password, the initial password
has to be provided.
-### Configuration of Expiry / Force Initial Password Change
+### Configuration
An administrator may enable password expiry and initial password change
-via the _org.apache.jackrabbit.oak.security.user.UserConfigurationImpl_
-OSGi configuration. By default expiry is disabled.
+via the `org.apache.jackrabbit.oak.security.user.UserConfigurationImpl`
+OSGi configuration. By default both features are disabled.
The following configuration options are supported:
-- Maximum Password Age (_maxPasswordAge_, days): When greater 0 enables password
- expiry and sets the expiration time in days.
-- Change Password On First Login (_initialPasswordChange_, true|false):
- When enabled, forces users to change their password upon first login.
+| Parameter | Type | Default | Description |
+|------------------------------------- |-------- -|------------------------|
+| `PARAM_PASSWORD_MAX_AGE` | int | 0 | Number of days until the password expires. |
+| `PARAM_PASSWORD_INITIAL_CHANGE` | boolean | false | boolean flag to enable initial pw change. |
+
+Note:
+
+- Maximum Password Age (`maxPasswordAge`) will only be enabled when a value greater 0 is set (expiration time in days).
+- Change Password On First Login (`initialPasswordChange`): When enabled, forces users to change their password upon first login.
### How it works
@@ -59,15 +64,17 @@ The following configuration options are
An expired password is defined as follows:
- The current date-time is after or on the date-time + maxPasswordAge
- specified in a _rep:passwordLastModified_ property
+ specified in a `rep:passwordLastModified` property
- OR: Expiry and/or Enforce Password Change is enabled, but no
- _rep:passwordLastModified_ property exists
+ `rep:passwordLastModified` property exists
-For the above, a password node _rep:pw_ and a property _rep:passwordLastModified_,
-governed by a new _rep:Password_ node type and located in the user's home, have
+For the above, a password node `rep:pw` and a property `rep:passwordLastModified`,
+governed by a new `rep:Password` 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):
+#### Representation in the Repository
+
##### Node Type rep:Password
[rep:Password]
@@ -80,94 +87,114 @@ been introduced, leaving open future enh
+ rep:pwd (rep:Password) = rep:Password protected
...
-The _rep:pw_ node and the _rep:passwordLastModified_ property are defined
+The `rep:pw` node and the `rep:passwordLastModified` 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.
-In the future the _rep:password_ property on the user node may be migrated
-to the _rep:pw_ sub-node.
+In the future the `rep:password` property on the user node may be migrated
+to the `rep:pw` sub-node.
-#### User Creation With Default Expired Password
+#### User Creation
-Upon initial creation of a user, the _rep:passwordLastModified_ property is
-omitted. If expiry or _initialPasswordChange_ are enabled, the absence of the
+Upon initial creation of a user, the `rep:passwordLastModified` property is
+omitted. If expiry or `initialPasswordChange` are enabled, the absence of the
property will be interpreted as immediate expiry of the password. When
-subsequently the user changes her password via _User#changePassword_, the
-_rep:passwordLastModified_ property is set and henceforth interpreted.
+subsequently the user changes her password via `User#changePassword`, the
+`rep:passwordLastModified` property is set and henceforth interpreted.
-#### Core Authentication Password Expiry Aware
+#### Authentication
-A login module must throw a _javax.security.auth.login.CredentialExpiredException_
+A login module must throw a `javax.security.auth.login.CredentialExpiredException`
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.
-In Oak, the Authentication (currently _UserAuthentication_) implementation
-compares within its _#authenticate()_ method the system time with the value
-stored in the rep:passwordLastModified_ and throws a _CredentialExpiredException_
+In Oak, the [Authentication] implementation provided by default with the user
+management compares within its `authenticate()` method the system time with the value
+stored in the `rep:passwordLastModified` and throws a [CredentialExpiredException]
if now is after or on the date-time specified by the value.
-In the case of _initialPasswordChange_ a password is considered expired if no
-_rep:passwordLastModified_ property can be found on login.
+In the case of `initialPasswordChange` a password is considered expired if no
+`rep:passwordLastModified` property can be found on login.
Both expiry and force initial password change are checked *after* regular
credentials verification, so as to prevent an attacker identifying valid users
by being redirected to a change password form upon expiry.
-#### Oak JCR XML Import
+##### UserAuthenticationFactory
-When users are imported via the Oak JCR XML importer, the expiry relevant
-nodes and property are supported. If the XML specifies a _rep:pw_ node and
-optionally a _rep:passwordLastModified_ 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.
-
-On the other hand, if the imported user already exists, potentially existing
-_rep:passwordLastModified_ 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.
-
-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.
+As described with section [User Management: The Default Implementation](default.html#pluggability)
+it is possible to change the default implementation of the `UserAuthenticationFactory`
+by pluggin a custom implementation at runtime.
+
+It's important to note that the authentication related part of password expiry is
+handled by the [Authentication] implementation exposed by the default [UserAuthenticationFactory].
+Replacing the factory will ultimately disable the password expiry feature
+unless a custom implementation respects and enforces the constraints explained
+before.
#### Changing an Expired Password
Oak supports changing a user's expired password as part of the normal login
process.
-Consumers of the repository already specify _javax.jcr.SimpleCredentials_ during
+Consumers of the repository already specify `javax.jcr.SimpleCredentials` 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
-_javax.jcr.SimpleCredentials_, while additionally providing the new password
-via a credentials attribute _newPassword_.
+[SimpleCredentials], while additionally providing the new password
+via a credentials attribute `newPassword`.
After verifying the user's credentials, *before* checking expiry, said attribute
-is then used by the _UserAuthentication_ to change the user's password.
+is then used by the `Authentication` implementation to change the user's password.
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.
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 _User#changePassword_ directly instead).
+changes (attribute is ignored, use `User#changePassword` directly instead).
Should the [Password History feature](history.html) be enabled, and - for the
above password change - a password already in the history be used, the change
-will fail and the login still throw a _CredentialExpiredException_. In order
+will fail and the login still throw a [CredentialExpiredException]. In order
for consumers of the exception to become aware that the credentials are
still considered expired, and that the password was not changed due to the
new password having been found in the password history, the credentials object
-is fitted with an additional attribute with name _PasswordHistoryException_.
+is fitted with an additional attribute with name [PasswordHistoryException].
+
This attribute may contain the following two values:
-_"New password was found in password history."_ or
-_""New password is identical to the current password."_
+- _"New password was found in password history."_ or
+- _""New password is identical to the current password."_
+
+#### XML Import
+
+When users are imported via the Oak JCR XML importer, the expiry relevant
+nodes and property are supported. If the XML specifies a `rep:pw` node and
+optionally a `rep:passwordLastModified` 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.
+
+On the other hand, if the imported user already exists, potentially existing
+`rep:passwordLastModified` 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.
+
+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.
+
+<!-- hidden references -->
+[SimpleCredentials]: http://www.day.com/specs/javax.jcr/javadocs/jcr-2.0/javax/jcr/SimpleCredentials.html
+[CredentialExpiredException]: https://docs.oracle.com/javase/7/docs/api/javax/security/auth/login/CredentialExpiredException.html
+[PasswordHistoryException]: /oak/docs/apidocs/org/apache/jackrabbit/oak/security/user/PasswordHistoryException.html
+[UserAuthenticationFactory]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/user/UserAuthenticationFactory.html
+[Authentication]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/Authentication.html
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/history.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/history.md?rev=1729970&r1=1729969&r2=1729970&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/history.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/history.md Fri Feb 12 10:14:09 2016
@@ -20,26 +20,47 @@ Password History
### General
-Oak provides functionality to remember a configurable number of
-passwords after password changes and to prevent a password to
+Since version 1.3.3 Oak provides functionality to remember a configurable number
+of passwords after password changes and to prevent a password to
be set during changing a user's password if found in said history.
### Configuration
An administrator may enable password history via the
-_org.apache.jackrabbit.oak.security.user.UserConfigurationImpl_
-OSGi configuration. By default the history is disabled.
+`org.apache.jackrabbit.oak.security.user.UserConfigurationImpl`
+OSGi configuration. By default the history is disabled (`passwordHistorySize` set to 0).
The following configuration option is supported:
-- Maximum Password History Size (_passwordHistorySize_, number of passwords): When greater 0 enables password
- history and sets feature to remember the specified number of passwords for a user.
+| Parameter | Type | Default | Description |
+|-------------------------------|---------|----------|--------------------|
+| `PARAM_PASSWORD_HISTORY_SIZE` | int | 0 | Number of passwords to be stored in the history |
+| | | | |
+Setting the configuration option to a value greater than 0 enables password
+history and sets feature to remember the specified number of passwords for a user.
Note, that the current implementation has a limit of at most 1000 passwords
remembered in the history.
### How it works
+#### Representation in the Repository
+
+History password hashes are recorded in a multi-value property `rep:pwdHistory` on
+the user's `rep:pwd` node, which mandates the specific node type `rep:Password`
+
+The `rep:pwdHistory` property is defined protected in order to guard against the
+user modifying (overcoming) her password history limitations.
+
+ [rep:User] > rep:Authorizable, rep:Impersonatable
+ + rep:pwd (rep:Password) = rep:Password protected
+ - rep:password (STRING) protected
+ ...
+
+ [rep:Password]
+ - * (UNDEFINED) protected
+ - * (UNDEFINED) protected multiple
+
#### Recording of Passwords
If the feature is enabled, during a user changing her password, the old password
@@ -52,7 +73,7 @@ record, as there is no old password.
The old password hash is copied to the password history *after* the provided new
password has been validated but *before* the new password hash is written to the
-user's _rep:password_ property.
+user's `rep:password` property.
The history operates as a FIFO list. A new password history record exceeding the
configured max history size, results in the oldest recorded password from being
@@ -60,14 +81,7 @@ removed from the history.
Also, if the configuration parameter for the history size is changed to a non-zero
but smaller value than before, upon the next password change the oldest records
-exceeding the new history size are removed.
-
-History password hashes are recorded in a multi-value property _rep:pwdHistory_ on
-the user's _rep:pwd_ node.
-
-The _rep:pwdHistory_ property is defined protected in order to guard against the
-user modifying (overcoming) her password history limitations.
-
+exceeding the new history size are removed.
#### Evaluation of Password History
@@ -76,10 +90,10 @@ Upon a user changing her password and if
password or any of the password hashes recorded in the history matches the new
password.
-If any record is a match, a _ConstraintViolationException_ is thrown and the
+If any record is a match, a `ConstraintViolationException` is thrown and the
user's password is *NOT* changed.
-#### Oak JCR XML Import
+#### XML Import
-When users are imported via the Oak JCR XML importer, password history is imported
+When users are imported via the JCR XML importer, password history is imported
irrespective on whether the password history feature is enabled or not.