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.
