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 2013/11/12 15:36:38 UTC
svn commit: r1541088 - in /jackrabbit/oak/trunk/oak-doc/src/site/markdown:
differences.md differences_accesscontrol.md differences_authentication.md
differences_permission.md differences_principal.md
differences_privileges.md differences_user.md
Author: angela
Date: Tue Nov 12 14:36:37 2013
New Revision: 1541088
URL: http://svn.apache.org/r1541088
Log:
OAK-14: document changes wrt jackrabbit
Added:
jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_accesscontrol.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_authentication.md
- copied, changed from r1540638, jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_permission.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_principal.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_privileges.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_user.md
Modified:
jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md?rev=1541088&r1=1541087&r2=1541088&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md Tue Nov 12 14:36:37 2013
@@ -146,60 +146,12 @@ there are ideas to implement a feature f
In the meanwhile we have [basic support](https://issues.apache.org/jira/browse/OAK-203) for same
name siblings but that might not cover all cases.
-Authentication
---------------
+Security
+--------
-Please refer to [OAK-793](https://issues.apache.org/jira/browse/OAK-793) for a general overview of
-changes with respect to Jackrabbit 2.
-
-Access Control Management
--------------------------
-
-Refer to [OAK-792](https://issues.apache.org/jira/browse/OAK-792) for a general overview of changes
-with respect to Jackrabbit 2.
-
-The following modification are most likely to have an effect on existing applications:
-
-* `AccessControlManager#hasPrivilege()` and `AccessControlManager#getPrivileges()` will throw a
- `PathNotFoundException` if the node for the specified path is not accessible. The Jackrabbit 2
- implementation is wrong and we fixed that in OAK ([OAK-886](https://issues.apache.org/jira/browse/OAK-886)).
- If the new behaviour turns out to be a problem with existing applications we might consider
- adding backward compatible behaviour.
-
-Permissions
------------
-
-Refer to [OAK-942](https://issues.apache.org/jira/browse/OAK-942) for a general overview of changes
-with respect to Jackrabbit 2.
-
-* As of Oak `Node#remove()` only requires sufficient permissions to remove the target node. In
- contrast to jackrabbit the validation will not traverse the tree and verify remove permission on
- all child nodes/properties. There exists a configuration flag that aims to produce best effort
- backwards compatibility but this flag is currently not enabled by default. Please let us know if
- you suspect this causes wrong behavior in your application.
-
-* By default user management operations require the specific user mgt related
- permission that has been introduced with OAK-1.0. This behavior can be
- turned off by setting the corresponding configuration flag.
-
-* As of OAK reading and writing items in the version store does not follow the
- regular permission evaluation but depends on access rights present on the
- corresponding versionable node [OAK-444](https://issues.apache.org/jira/browse/OAK-444).
-
-Privilege Management
---------------------
-
-Refer to [OAK-910](https://issues.apache.org/jira/browse/OAK-910) for a general overview of changes
-with respect to Jackrabbit 2.
-
-User Management
----------------
-
-Refer to [OAK-791](https://issues.apache.org/jira/browse/OAK-791) for a general overview of changes
-with respect to Jackrabbit 2.
-
-Principal Management
---------------------
-
-Refer to [OAK-909](https://issues.apache.org/jira/browse/OAK-909) for a general overview of changes
-with respect to Jackrabbit 2.
\ No newline at end of file
+* [AccessControl Management](differences_accesscontrol.html)
+* [Authentication](differences_authentication.html)
+* [Permission Evaluation](differences_permission.html)
+* [Principal Management](differences_principal.html)
+* [Privilege Management](differences_privileges.html)
+* [User Management](differences_user.html)
Added: jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_accesscontrol.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_accesscontrol.md?rev=1541088&view=auto
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_accesscontrol.md (added)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_accesscontrol.md Tue Nov 12 14:36:37 2013
@@ -0,0 +1,156 @@
+<!--
+ 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.
+ -->
+### AccessControl Management : Differences wrt Jackrabbit 2.x
+
+#### 1. Characteristics of the Default Implementation
+
+##### General
+In general the authorization related code in OAK clearly separates between access
+control management (such as defined by the JCR and Jackrabbit API) and the internal
+permission evaluation (see also [Permission Evaluation](differences_permissions.html)).
+
+The default implementation of the access control management corresponds to the
+resource-based implementation present with Jackrabbit 2.x. The former principal-base
+access control management is no longer available but it's functionality has been
+incorporated both in the default ac management implementation and the permission evaluation.
+
+##### JCR API
+###### AccessControlManager#hasPrivilege and #getPrivileges
+As of OAK those methods throw `PathNotFoundException` if the corresponding node
+is not accessible by the editing session. This is in accordance with the behavior
+mandated by JSR 283 and a bug in Jackrabbit 2.x.
+
+###### AccessControlManager#getEffectivePolicies
+In contrast to Jackrabbit 2.x the editing session is used to retrieve the effective
+policies and the policies returned by these methods are guarantueed to only return
+information that is otherwise accessible by the session. The corresponding methods
+in Jackrabbit 2.x use to throw an exception in this situation.
+
+###### AccessControlPolicy
+OAK introduces a new type of policy that enforces regular read-access for everyone
+on the trees that hold this new `ReadPolicy` [0]. The main usage of this new policy
+is to ensure backwards compatible behavior of repository level information (node
+types, namespace, privileges) that are now kept within the content repository.
+In Jackrabbit 2.x this information was stored in the file system without the
+ability to apply or enforce regular access control such as present with items in
+the repository.
+
+Currently these special read policies are defined as part of the overall security
+configuration and cannot be managed/edited using regular access control management
+API (see ([OAK-951](https://issues.apache.org/jira/browse/OAK-951))).
+
+###### AccessControlEntry
+Validation: as of OAK the implementation of the `AccessControlEntry` interface is
+no longer in charge of validating the specified privileges. While some validation
+is still performed in the corresponding `AccessControlList` methods, the complete
+validation is delegated to the commit phase and executed by a specific `Validator`
+implementation.
+
+Restrictions: as of OAK the optional restrictions present with a given
+`JackrabbitAccessControlEntry` can be multivalued (see below).
+
+##### Jackrabbit API
+###### Principal-based Access Control
+The principal-based access control management as present in Jackrabbit-core is no
+longer present with OAK. The main benefit of the principal-based approach has been
+incorporated with the changes in the default [permission evaluation](differences_permissions.html)).
+In addition the default access control manager implementation supports all methods
+defined by `JackrabbitAccessControlManager`; i.e. editing access control information
+by principal is possible as long as the editing session has sufficient permission
+on the target node(s). Similarly, the per principal policies exposed to a given
+session will always respect that access rights of that session.
+
+###### Restrictions
+The implementation of the additional restrictions associated with an ACE has been modified/extended as follows:
+
+- Separate restriction management API (see below) on the OAK level that allows to ease plugging custom restrictions.
+- Changed node type definition for storing restrictions in the default implementation.
+ - as of OAK restrictions are collected underneath a separate child node "rep:restrictions"
+ - restrictions can be multi-valued (see [JCR-3637](https://issues.apache.org/jira/browse/JCR-3637), [JCR-3641](https://issues.apache.org/jira/browse/JCR-3641))
+ - backwards compatible behavior for restrictions stored underneath the ACE node directly
+- New restrictions:
+ - "rep:ntNames", which allows to limit the affected ACE to nodes of the specified node type(s)
+ - "rep:prefixes", which allows to limit the effect to item names that have a specific namespace prefix.
+
+#### 2. Node Types
+
+As mentioned above the node type definitions have been extended to match the new functionality related to restrictions.
+The node type definition for access control entries:
+
+ [rep:ACE]
+ - rep:principalName (STRING) protected mandatory
+ - rep:privileges (NAME) protected mandatory multiple
+ - rep:nodePath (PATH) protected /* deprecated in favor of restrictions */
+ - rep:glob (STRING) protected /* deprecated in favor of restrictions */
+ - * (UNDEFINED) protected /* deprecated in favor of restrictions */
+ + rep:restrictions (rep:Restrictions) = rep:Restrictions protected
+
+The new node type definition for restrictions:
+
+ /**
+ * @since oak 1.0
+ */
+ [rep:Restrictions]
+ - * (UNDEFINED) protected
+ - * (UNDEFINED) protected multiple
+
+#### 3. API Extensions and Public Classes
+
+org.apache.jackrabbit.oak.spi.security.authorization.accesscontrol [1]
+
+- `AbstractAccessControlList`
+- `ImmutableACL`
+- `ACE`
+
+org.apache.jackrabbit.oak.spi.security.authorization.restriction [2]
+
+- `RestrictionProvider`:
+- `RestrictionDefinition`
+- `RestrictionPattern`
+- `Restriction`
+
+#### 4. Configuration
+
+The following access control related configuration options are present with the `AuthorizationConfiguration` as of OAK 1.0 [3]
+
+- `getAccessControlManager`
+- `getRestrictionProvider`
+
+Differences to Jackrabbit 2.x:
+
+- The "omit-default-permission" configuration option present with the Jackrabbit's AccessControlProvider implementations is no longer supported with Oak.
+- As of OAK no extra access control content is installed by default which renders that flag superfluous.
+
+#### 5. Important Note
+
+The following modification is most likely to have an effect on existing applications:
+
+- `AccessControlManager#hasPrivilege()` and `AccessControlManager#getPrivileges()` will throw a
+ `PathNotFoundException` if the node for the specified path is not accessible. The Jackrabbit 2
+ implementation is wrong and we fixed that in OAK ([OAK-886](https://issues.apache.org/jira/browse/OAK-886)).
+ If the new behaviour turns out to be a problem with existing applications we might consider
+ adding backward compatible behaviour.
+
+#### 6. References
+
+[0] https://issues.apache.org/jira/browse/OAK-951
+
+[1] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authorization/restriction/
+
+[2] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authorization/accesscontrol/
+
+[3] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authorization/AuthorizationConfiguration.java
Copied: jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_authentication.md (from r1540638, jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md)
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_authentication.md?p2=jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_authentication.md&p1=jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md&r1=1540638&r2=1541088&rev=1541088&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_authentication.md Tue Nov 12 14:36:37 2013
@@ -14,192 +14,215 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
+### Authentication : Differences wrt Jackrabbit 2.x
-Backward compatibility
-======================
+#### 1. Characteristics of the Default Implementation
-Oak implements the JCR API and we expect most applications to work out of the box. However, the Oak
-code base is very young and not yet on par with Jackrabbit 2. Some of the more obscure parts of JCR
-are not (yet) implemented. If you encounter a problem running your application on Oak, please cross
-check against Jackrabbit 2 before reporting an issue against Oak.
-
-Reporting issues
-================
-
-If you encounter a problem where functionality is missing or Oak does not behave as expected please
-check whether this is a [known change in behaviour](https://issues.apache.org/jira/browse/OAK-14) or
-a [known issue](https://issues.apache.org/jira/browse/OAK). If in doubt ask on the [Oak dev list]
-(http://oak.markmail.org/). Otherwise create a [new issue](https://issues.apache.org/jira/browse/OAK).
-
-Notable changes
-===============
-
-This section gives a brief overview of the most notable changes in Oak with respect to Jackrabbit 2.
-These changes are generally caused by overall design decisions carefully considering the benefits
-versus the potential backward compatibility issues.
-
-Session state and refresh behaviour
------------------------------------
-
-In Jackrabbit 2 sessions always reflects the latest state of the repository. With Oak a session
-reflects a stable view of the repository from the time the session was acquired ([MVCC model]
-(http://en.wikipedia.org/wiki/MVCC)). This is a fundamental design aspect for achieving the
-distributed nature of an Oak repository.
-
-This change can cause subtle differences in behavior when two sessions perform modifications
-relying on one session seeing the other session's changes. Oak requires explicit calls to
-`Session.refresh()`in this case.
-
-> *Note*: To ease migration to Oak, sessions being idle for more than one minute will log a warning
-> to the log file. Furthermore sessions are automatically synchronised to reflect the same state
-> across accesses within a single thread. That is, an older session will see the changes done
-> through a newer session given both sessions are accessed from within the same thread.
->
-> Automatic session synchronisation is a transient feature and will most probably be removed in
-> future versions of Oak. See [OAK-803](https://issues.apache.org/jira/browse/OAK-803) for further
-> details regarding session backwards compatibility and
-> [OAK-960](https://issues.apache.org/jira/browse/OAK-960) regarding in thread session
-> synchronisation.
-
-On Oak `Item.refresh()` is deprecated and will always cause an `Session.refresh()`. The former call
-will result in a warning written to the log in order to facilitate locating trouble spots.
-
-On Oak `Item.save()` is deprecated and will per default log a warning and fall back to
-`Session.save()`. This behaviour can be tweaked with `-Ditem-save-does-session-save=false` in which
-case no fall back to `Session#save()` will happen but an `UnsupportedRepositoryException` is thrown
-if the sub-tree rooted at the respective item does not contain all transient changes. See
-[OAK-993](https://issues.apache.org/jira/browse/OAK-993) for details.
-
-Query
------
-
-Oak does not index content by default as does Jackrabbit 2. You need to create custom indexes when
-necessary, much like in traditional RDBMSs. If there is no index for a specific query then the
-repository will be traversed. That is, the query will still work but probably be very slow.
-See the [query overview page](query.html) for how to create a custom index.
-
-There were some smaller bugfixes in the query parser which might lead to incompatibility.
-See the [query overview page](query.html) for details.
-
-
-Observation
------------
-
-* `Event.getUserId()`, `Event.getUserData()`and `Event.getDate()` will only be available for locally
- generated events (i.e. on the same cluster node). To help identifying potential trouble spots,
- calling any of these methods without a previous call to `JackrabbitEvent#isExternal()` will write
- a warning to the log file.
-
-* Push notification mechanisms like JCR observation weight heavy on distributed systems. Therefore,
- if an application requirement is not actually an "eventing problem" consider using different means
- like query and custom indexes.
- [Apache Sling](http://sling.apache.org) identified and classified common [usage patterns]
- (https://cwiki.apache.org/confluence/display/SLING/Observation+usage+patterns) of observation and
- recommendations on alternative solutions where applicable.
-
-* Event generation is done by looking at the difference between two revisions of the persisted
- content trees. Items not present in a previous revision but present in the current revision are
- reported as `Event.NODE_ADDED` and `Event.PROPERTY_ADDED`, respectively. Items present in a
- previous revision but not present in the current revision are reported as `Event.NODE_REMOVED` and
- `Event.PROPERTY_REMOVED`, respectively. Properties that changed in between the previous revision
- and the current revision are reported as `PROPERTY_CHANGED`. As a consequence operations that
- cancelled each others in between the previous revision and the current revision are not reported.
- Furthermore the order of the events depends on the underlying implementation and is not specified.
- In particular there are some interesting consequences:
-
- * Touched properties: Jackrabbit 2 used to generate a `PROPERTY_CHANGED` event when touching a
- property (i.e. setting a property to its current value). Oak keeps closer to the specification
- and [omits such events](https://issues.apache.org/jira/browse/OAK-948). More generally removing
- a subtree and replacing it with the same subtree will not generate any event.
-
- * Removing a referenceable node and adding it again will result in a `PROPERTY_CHANGED` event for
- `jcr:uuid`; the same applies for other built-in protected and mandatory properties
- such as e.g. jcr:versionHistory if the corresponding versionable node
- was removed and a versionable node with the same name is being created.
-
- * Limited support for `Event.NODE_MOVED`:
-
- + `NODE_MOVED` are only reported for nodes whose source location is not transient. A source
- location is transient if it is transiently added or a child node of a transiently moved
- tree.
-
- + Removing a node and adding a node with the same name at the same parent will be reported as
- `NODE_MOVED` event as if it where caused by `Node.orderBefore()`.
-
- + The exact sequence of `Node.orderBefore()` will not be reflected through `NODE_MOVED`
- events: given two child nodes `a` and `b`, ordering `a` after `b` may be reported as
- ordering `b` before `a`.
-
-* The sequence of differences Oak generates observation events from is guaranteed to contain the
- before and after states of all cluster local changes. This guarantee does not hold for cluster
- external changes. That is, cancelling operations from cluster external events might not be
- reported event though they stem from separate commits (`Session.save()`).
-
-
-Same name siblings
-------------------
-
-Same name siblings (SNS) are deprecated in Oak. We figured that the actual benefit supporting same
-name siblings as mandated by JCR is dwarfed by the additional implementation complexity. Instead
-there are ideas to implement a feature for automatic [disambiguation of node names](https://issues.apache.org/jira/browse/OAK-129).
-
-In the meanwhile we have [basic support](https://issues.apache.org/jira/browse/OAK-203) for same
-name siblings but that might not cover all cases.
-
-Authentication
---------------
-
-Please refer to [OAK-793](https://issues.apache.org/jira/browse/OAK-793) for a general overview of
-changes with respect to Jackrabbit 2.
-
-Access Control Management
--------------------------
-
-Refer to [OAK-792](https://issues.apache.org/jira/browse/OAK-792) for a general overview of changes
-with respect to Jackrabbit 2.
-
-The following modification are most likely to have an effect on existing applications:
-
-* `AccessControlManager#hasPrivilege()` and `AccessControlManager#getPrivileges()` will throw a
- `PathNotFoundException` if the node for the specified path is not accessible. The Jackrabbit 2
- implementation is wrong and we fixed that in OAK ([OAK-886](https://issues.apache.org/jira/browse/OAK-886)).
- If the new behaviour turns out to be a problem with existing applications we might consider
- adding backward compatible behaviour.
-
-Permissions
------------
-
-Refer to [OAK-942](https://issues.apache.org/jira/browse/OAK-942) for a general overview of changes
-with respect to Jackrabbit 2.
-
-* As of Oak `Node#remove()` only requires sufficient permissions to remove the target node. In
- contrast to jackrabbit the validation will not traverse the tree and verify remove permission on
- all child nodes/properties. There exists a configuration flag that aims to produce best effort
- backwards compatibility but this flag is currently not enabled by default. Please let us know if
- you suspect this causes wrong behavior in your application.
-
-* By default user management operations require the specific user mgt related
- permission that has been introduced with OAK-1.0. This behavior can be
- turned off by setting the corresponding configuration flag.
-
-* As of OAK reading and writing items in the version store does not follow the
- regular permission evaluation but depends on access rights present on the
- corresponding versionable node [OAK-444](https://issues.apache.org/jira/browse/OAK-444).
-
-Privilege Management
---------------------
-
-Refer to [OAK-910](https://issues.apache.org/jira/browse/OAK-910) for a general overview of changes
-with respect to Jackrabbit 2.
-
-User Management
----------------
+##### Null Login
-Refer to [OAK-791](https://issues.apache.org/jira/browse/OAK-791) for a general overview of changes
-with respect to Jackrabbit 2.
+As of Oak 1.0 `Repository#login()` and `Repository#login(null, wspName)` is no
+longer treated as guest login. This behavior of Jackrabbit-core is violating the
+specification, which defines that null-login should be used for those cases where
+the authentication process is handled outside of the repository (-> see pre-authentication below).
-Principal Management
---------------------
+In order to get a full backwards compatible behavior OAK provides a specific
+`GuestLoginModule` [0] that can be added to the JAAS (or corresponding OSGI) configuration.
-Refer to [OAK-909](https://issues.apache.org/jira/browse/OAK-909) for a general overview of changes
-with respect to Jackrabbit 2.
\ No newline at end of file
+Example JAAS Configuration:
+
+ jackrabbit.oak {
+ org.apache.jackrabbit.oak.spi.security.authentication.GuestLoginModule optional;
+ org.apache.jackrabbit.oak.security.authentication.user.LoginModuleImpl required;
+ };
+
+
+##### Guest Login
+
+With respect to guest login (aka anonymous login) the OAK content repository
+out of the box contains the following modifications:
+
+- null login != guest login
+- no anonymous login with uid/pw
+
+As explained in 1) the null login will not longer fall back to a guest login
+unless explicitly configured (-> `GuestLoginModule`).
+The proper way to obtain an guest session as of OAK is as specified by JSR 283:
+
+ String wspName = null;
+ Session anonymous = repository.login(new GuestCredentials(), wspName);
+
+Similarly, the special treatment that jackrabbit core applied for
+the guest (anonymous) user has been omitted altogether in OAK. In the
+default setup the anonymous user will created without any password. Therefore
+explicitly uid/pw login using the anonymous userId will no longer work.
+This behavior is now consistent with the default login of any other user
+which doesn't have a password set.
+
+
+##### Pre-Authentication in the LoginContextProvider
+
+Like in Jackrabbit-core the repository internal authentication verification can be skipped by calling `Repository#login()` or `Repository#login(null, wspName)`. In this case the repository implementation expects the verification to be performed prior to the login call.
+
+This behavior is provided by the default implementation of the `LoginContextProvider` [1] which expects a `Subject` to be available with the current `java.security.AccessControlContext`. However, in contrast to Jackrabbit-core the current implementation does not try to extend the pre-authenticated subject but skips the internal verification step altogether.
+
+Since the `LoginContextProvider` is a configurable with the authentication setup OAK users also have the following options by providing a custom `LoginContextProvider`:
+
+- Disable pre-authentication by not trying to retrieve a pre-authenticated `Subject`.
+- Add support for extending the pre-authenticated subject by always passing writable subjects to the `JaasLoginContext`
+- Dropping JAAS altogether by providing a custom implementation of the
+ `org.apache.jackrabbit.oak.spi.security.authentication.LoginContext` [2] interface.
+
+Example how to use the pre-auth:
+
+ String userId = "test";
+ /**
+ Retrive valid principals e.g. by calling jackrabbit API
+ - PrincipalManager#getPrincipal and/or #getGroupMembership
+ or from Oak SPI
+ - PrincipalProvider#getPrincipals(String userId)
+ */
+ Set<? extends Principal> principals = getPrincipals(userId);
+ AuthInfo authInfo = new AuthInfoImpl(userId, Collections.<String, Object>emptyMap(), principals);
+ Subject subject = new Subject(true, principals, Collections.singleton(authInfo), Collections.<Object>emptySet());
+ Session session;
+ try {
+ session = Subject.doAsPrivileged(subject, new PrivilegedExceptionAction<Session>() {
+ @Override
+ public Session run() throws Exception {
+ return login(null, null);
+ }
+ }, null);
+ } catch (PrivilegedActionException e) {
+ throw new RepositoryException("failed to retrieve session.", e);
+ }
+
+#### 2. Impersonation
+
+##### Self-Impersonation (aka Cloning a Session)
+
+As of OAK 1.0 the latest changes made to JSR 333 with respect to `Session#impersonate`
+have been adopted [3]: Any attempt to impersonate the same session (self-impersonation)
+will succeed as long as the user is still valid.
+
+##### Impersonation Credentials
+
+The OAK implementation of `Session#impersonate` no longer uses `SimpleCredentials`
+to transport the original `Subject` but rather performs the login with dedicated
+`ImpersonationCredentials` [4].
+
+With this change the impersonation feature no longer relies on `SimpleCredentials`
+being passed to `Session#impersonate` call. Instead the specified credentials are
+passed to a new instance of `ImpersonationCredentials` delegating the evaluation
+and validation of the specified `Credentials` to the configured login module(s).
+
+This modification will not affect applications that used JCR API to impersonate
+a given session. However the following example which 'manually' builds impersonation
+credentials the way jackrabbit core was handling it will no longer work to
+impersonate an existing session:
+
+ SessionImpl sImpl = (SessionImpl) mySession;
+ SimpleCredentials jrImpCreds = new SimpleCredentials("someUserId, new char[0]);
+ creds.setAttribute(SecurityConstants.IMPERSONATOR_ATTRIBUTE, sImpl.getSubject());
+ Session impersonated = sImpl.getRepository().login(jrImpCreds, sImpl.getWorkspace().getName());
+
+#### 3. Token based Authentication
+
+The token based authentication has been completely refactor in OAK.
+
+- Dedicated API for managing login tokens [5]
+- Pluggable configuration of the new token management API
+- Complete separation of token based authentication from regular
+ uid/pw authentication into a separate `LoginModule` [6]
+
+The default implementation differs from jackrabbit as follows
+- token node is referenceable with a dedicated node type (rep:Token)
+- expiration and key properties are mandatory and protected
+- expiration time is obtained from `PARAM_TOKEN_EXPIRATION` specified in the login
+attributes and falls back to the same configuration parameter.
+
+The definition of the new built-in node type "rep:Token":
+ [rep:Token] > mix:referenceable
+ - rep:token.key (STRING) protected mandatory
+ - rep:token.exp (DATE) protected mandatory
+ - * (UNDEFINED) protected
+ - * (UNDEFINED) multiple protected
+
+Please note the following difference with respect to Jackrabbit core:
+- the `TokenLoginModule` is responsible for creating new login tokens. Other login modules should not attempt to do so.
+- token characteristics such as expiration time only need to be configured with the `TokenLoginModule`
+- Other `LoginModule` implementations consequently no longer need to have the same config options set.
+
+
+#### 4. External Authentication
+
+While the default setup in OAK is solely relying on repository functionality to
+ensure proper authentication it quite common to authenticate against different
+systems (e.g. LDAP). For those setups that wish to combine initial authentication
+against a third party system with repository functionality, OAK provides some
+basic implementation and extension points [7] and ship an example setup for LDAP authentication.
+
+This is aimed to become the replacement for `com.day.crx.security.ldap.LDAPLoginModule` [8],
+which relies on jackrabbit internals and will no longer work with OAK.
+
+#### 5. API Extensions
+
+The OAK project introduces the following authenticated related service provider interfaces:
+
+org.apache.jackrabbit.oak.spi.security.authentication:
+
+- `LoginContextProvider`: Configurable provider of the `LoginContext` (see below)
+- `LoginContext`: Interface version of the JAAS LoginContext aimed to ease integration with non-JAAS components
+- `Authentication`: Aimed to validate credentials during the first phase of the (JAAS) login process.
+
+org.apache.jackrabbit.oak.spi.security.authentication.token:
+
+- `TokenProvider`: Interface to manage login tokens.
+- `TokenInfo`: Information related to a login token and token validity.
+
+org.apache.jackrabbit.oak.spi.security.authentication.external:
+
+- interfaces to ease custom implementation of the external authentication with
+ optional user/group synchronization to the repository (see [7]).
+
+#### 6. Configuration
+
+##### AuthenticationConfiguration [9]:
+- `getLoginContextProvider` -> configuration of the login context
+- `getTokenProvider` -> configuration of the token management implementation
+
+##### Utilities
+There also exists a utility class that allows to obtain different
+`javax.security.auth.login.Configuration` for the most common setup [10]:
+
+- `ConfigurationUtil#getDefaultConfiguration`: default OAK configuration supporting uid/pw login configures `LoginModuleImpl` only
+
+- `ConfigurationUtil#getJackrabbit2Configuration`: backwards compatible configuration that provides the functionality covered by jackrabbit-core DefaultLoginModule, namely:
+
+ - `GuestLoginModule`: null login falls back to anonymous
+ - `TokenLoginModule`: covers token base authentication
+ - `LoginModuleImpl`: covering regular uid/pw login
+
+
+#### 7. References
+
+[0] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/GuestLoginModule.java
+
+[1] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/LoginContextProvider.java
+
+[2] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/LoginContext.java
+
+[3] https://java.net/jira/browse/JSR_333-27
+
+[4] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/ImpersonationCredentials.java
+
+[5] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/token/
+
+[6] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/security/authentication/token/TokenLoginModule.java
+
+[7] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/external/
+
+[8] http://dev.day.com/docs/en/crx/current/administering/ldap_authentication.html
+
+[9] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/AuthenticationConfiguration.java
+
+[10] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/authentication/ConfigurationUtil.java
Added: jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_permission.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_permission.md?rev=1541088&view=auto
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_permission.md (added)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_permission.md Tue Nov 12 14:36:37 2013
@@ -0,0 +1,37 @@
+<!--
+ 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.
+ -->
+### Permission Evaluation : Differences wrt Jackrabbit 2.x
+
+*NOTE: Work in Progress*
+
+Refer to [OAK-942](https://issues.apache.org/jira/browse/OAK-942) for a general overview of changes
+with respect to Jackrabbit 2.
+
+* As of Oak `Node#remove()` only requires sufficient permissions to remove the target node. In
+ contrast to jackrabbit the validation will not traverse the tree and verify remove permission on
+ all child nodes/properties. There exists a configuration flag that aims to produce best effort
+ backwards compatibility but this flag is currently not enabled by default. Please let us know if
+ you suspect this causes wrong behavior in your application.
+
+* By default user management operations require the specific user mgt related
+ permission that has been introduced with OAK-1.0. This behavior can be
+ turned off by setting the corresponding configuration flag.
+
+* As of OAK reading and writing items in the version store does not follow the
+ regular permission evaluation but depends on access rights present on the
+ corresponding versionable node [OAK-444](https://issues.apache.org/jira/browse/OAK-444).
+
Added: jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_principal.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_principal.md?rev=1541088&view=auto
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_principal.md (added)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_principal.md Tue Nov 12 14:36:37 2013
@@ -0,0 +1,61 @@
+<!--
+ 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.
+ -->
+### Principal Management : Differences wrt Jackrabbit 2.x
+
+#### 1. Characteristics of the Principal Management Implementation
+
+The default implementation of the principal management API basically corresponds
+to the default in Jackrabbit 2.x and is based on the user management implementation.
+Note however, that as of OAK only a single principal provider is exposed on the
+SPI level (used to be multiple principal providers with the LoginModule configuration
+in Jackrabbit 2.x). See the configuration section below for details.
+
+#### 2. API Extensions
+
+- `PrincipalProvider` [0]: SPI level access to principals known to the repository
+which is also used by the default implementation of the `PrincipalManager` interface.
+This interface replaces the internal PrincipalProvider interface present in
+Jackrabbit 2.x. Note, that principals from different sources can be supported by
+using `CompositePrincipalProvider` [1] or a similar implementation that proxies
+different sources.
+
+##### Special Principals
+- `AdminPrincipal`: Marker interface to identify the principal associated with administrative user(s) [2].
+- `EveryonePrincipal`: built-in group principal implementation that has every other valid principal as member [3].
+- `SystemPrincipal`: built-in principal implementation to mark system internal subjects [4].
+
+#### 3. Configuration
+
+##### PrincipalConfiguration [5]:
+- `getPrincipalManager` -> returns a new instance of o.a.j.api.security.principal.PrincipalManager [6] (see also `JackrabbitSession#getPrincipalManager()`
+- `getPrincipalProvider` -> returns a new instance of principal provider. Note, that in contrast to Jackrabbit 2.x the system may only have one single principal provider implementation configured. In order to combine principals from different sources a implementation that properly handles the different sources is required; the `CompositePrincipalProvider` [1] is an example that combines multiple implementations.
+
+#### 4. References
+
+[0] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/principal/PrincipalProvider.java
+
+[1] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/principal/CompositePrincipalProvider.java
+
+[2] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/principal/AdminPrincipal.java
+
+[3] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/principal/EveryonePrincipal.java
+
+[4] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/principal/SystemPrincipal.java
+
+[5] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/principal/PrincipalConfiguration.java
+
+[6] http://svn.apache.org/repos/asf/jackrabbit/trunk/jackrabbit-api/src/main/java/org/apache/jackrabbit/api/security/principal/PrincipalManager.java
\ No newline at end of file
Added: jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_privileges.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_privileges.md?rev=1541088&view=auto
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_privileges.md (added)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_privileges.md Tue Nov 12 14:36:37 2013
@@ -0,0 +1,117 @@
+<!--
+ 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.
+ -->
+### Privilege Management : Differences wrt Jackrabbit 2.x
+
+#### 1. Characteristics of the Privilege Management Implementation
+
+##### General Notes
+As of OAK the built-in and custom privileges are stored in the repository
+underneath `/jcr:system/rep:privileges`. Similar to other repository level date
+(node types, namespaces and versions) this location is shared by all workspaces
+present in the repository. The nodes and properties storing the privilege
+definitions are protected by their node type definition. In addition a specific
+privilege `Validator` and `CommitHook` implementations assert the consistency of
+the privilege store. The built-in privileges are installed using a dedicated
+implementation of the `RepositoryInitializer` [0].
+
+##### Registration of Custom Privileges
+As far as registration of custom privileges the OAK implementation behaves
+different to Jackrabbit 2.x in the following aspects:
+- Registration of new privileges fails with `IllegalStateException` if the editing session has pending changes.
+- Any validation is performed by CommitHooks in order to make sure that modifications made on the OAK API directly is equally verified. Subsequently any violation (permission, privilege consistency) is only detected at the end of the registration process. The privilege manager itself does not perform any validation.
+
+#### 2. Built-in Privilege Definitions
+
+- All Privileges as defined by JSR 283
+ - jcr:read
+ - jcr:modifyProperties
+ - jcr:addChildNodes
+ - jcr:removeNode
+ - jcr:removeChildNodes
+ - jcr:readAccessControl
+ - jcr:modifyAccessControl
+ - jcr:lockManagement
+ - jcr:versionManagement
+ - jcr:nodeTypeManagement
+ - jcr:retentionManagement (NOTE: retention management not yet implemented)
+ - jcr:lifecycleManagement (NOTE: lifecycle management not yet implemented)
+ - jcr:write
+ - jcr:all
+
+
+- All Privileges defined by JSR 333
+ - jcr:workspaceManagement (NOTE: wsp management not yet implemented)
+ - jcr:nodeTypeDefinitionManagement
+ - jcr:namespaceManagement
+
+
+- All Privileges defined by Jackrabbit 2.x
+ - rep:write
+ - rep:privilegeManagement
+
+
+- New Privileges defined by OAK 1.0:
+ - rep:userManagement
+ - rep:readNodes
+ - rep:readProperties
+ - rep:addProperties
+ - rep:alterProperties
+ - rep:removeProperties
+
+
+Note the following differences with respect to Jackrabbit 2.x definitions:
+- jcr:read is now an aggregation of rep:readNodes and rep:readProperties
+- jcr:modifyProperties is now an aggregation of rep:addProperties, rep:alterProperties and rep:removeProperties
+
+#### 3. Node Type Definitions
+
+The following privilege related built-in node types have been added in OAK 1.0.
+They are used to represent built-in and custom privilege definitions in the repository.
+
+ [rep:Privileges]
+ + * (rep:Privilege) = rep:Privilege protected ABORT
+ - rep:next (LONG) protected multiple mandatory
+
+ [rep:Privilege]
+ - rep:isAbstract (BOOLEAN) protected
+ - rep:aggregates (NAME) protected multiple
+ - rep:bits (LONG) protected multiple mandatory
+
+#### 4. API Extensions
+
+org.apache.jackrabbit.oak.spi.security.privilege
+
+- `PrivilegeBitsProvider` : Provider implementation to read `PrivilegeBits` from the repository content and map names to internal representation (and vice versa) [2].
+- `PrivilegeBits`: Internal representation of JCR privileges [3].
+
+#### 5. Configuration
+
+##### PrivilegeConfiguration [1]:
+- `getPrivilegeManager` -> returns a new instance of the `PrivilegeManager`
+ interface such as exposed by `JackrabbitWorkspace#getPrivilegeManager`.
+ Note that the default implementation is based on OAK API and can equally be
+ used for privilege related tasks in the OAK layer.
+
+#### 6. References
+
+[0] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/security/privilege/PrivilegeInitializer.java
+
+[1] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/privilege/PrivilegeConfiguration.java
+
+[2] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/privilege/PrivilegeBitsProvider.java
+
+[3] http://svn.apache.org/repos/asf/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/spi/security/privilege/PrivilegeBits.java
\ No newline at end of file
Added: jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_user.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_user.md?rev=1541088&view=auto
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_user.md (added)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences_user.md Tue Nov 12 14:36:37 2013
@@ -0,0 +1,22 @@
+<!--
+ 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.
+ -->
+### User Management : Differences wrt Jackrabbit 2.x
+
+*NOTE: Work in Progress*
+
+Refer to [OAK-791](https://issues.apache.org/jira/browse/OAK-791) for a general overview of changes
+with respect to Jackrabbit 2.