You are viewing a plain text version of this content. The canonical link for it is here.
Posted to oak-commits@jackrabbit.apache.org by an...@apache.org on 2016/02/10 18:12:27 UTC
svn commit: r1729662 [1/3] - in
/jackrabbit/oak/trunk/oak-doc/src/site/markdown: ./ oak_api/ security/
security/accesscontrol/ security/authentication/ security/authorization/
security/permission/ security/principal/ security/privilege/ security/user/
Author: angela
Date: Wed Feb 10 17:12:26 2016
New Revision: 1729662
URL: http://svn.apache.org/viewvc?rev=1729662&view=rev
Log:
OAK-3946 : Document oak-authorization-cug
minor improvement: documenting oak security (improve structure and readibility)
Added:
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/default.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/default.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/composite.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/cug.md
- copied, changed from r1728531, jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/cug.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/restriction.md
- copied, changed from r1728531, jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/restriction.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/introduction.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission/default.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/privilege/default.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/default.md
Removed:
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/cug.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/restriction.md
Modified:
jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/oak_api/error_codes.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/differences.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/identitymanagement.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/tokenmanagement.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/usersync.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/overview.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission/evaluation.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/principal.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/principal/differences.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/principal/principalprovider.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/privilege.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/privilege/mappingtoitems.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/authorizableaction.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/user/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=1729662&r1=1729661&r2=1729662&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/differences.md Wed Feb 10 17:12:26 2016
@@ -289,7 +289,7 @@ Security
--------
* [Authentication](security/authentication/differences.html)
-* [AccessControl Management](security/accesscontrol/differences.html)
+* [Access Control Management](security/accesscontrol/differences.html)
* [Permission Evaluation](security/permission/differences.html)
* [Privilege Management](security/privilege/differences.html)
* [Principal Management](security/principal/differences.html)
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/oak_api/error_codes.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/oak_api/error_codes.md?rev=1729662&r1=1729661&r2=1729662&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/oak_api/error_codes.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/oak_api/error_codes.md Wed Feb 10 17:12:26 2016
@@ -45,11 +45,11 @@ information about the issue. This page i
#### User Validation
-see section [User Management](../security/user.html#validation)
+see section [User Management](../security/user/default.html#validation)
#### Privilege Validation
-see section [Privilege Management](../security/privilege.html#validation)
+see section [Privilege Management](../security/privilege/default.html#validation)
#### Token Validation
@@ -60,17 +60,17 @@ see section [Token Management](../securi
#### Permission Validation
-see section [Permissions](../security/permission.html#validation)
+see section [Permissions](../security/permission/default.html#validation)
### Type Access Control
#### Default Access Control Validation
-see section [Access Control Management](../security/accesscontrol.html#validation)
+see section [Access Control Management](../security/accesscontrol/default.html#validation)
#### CUG Validation
-see section [Closed User Groups](../security/accesscontrol/cug.html#validation)
+see section [Closed User Groups](../security/authorization/cug.html#validation)
<!-- hidden references -->
[OAK-764]: https://issues.apache.org/jira/browse/OAK-764
\ No newline at end of file
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol.md?rev=1729662&r1=1729661&r2=1729662&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol.md Wed Feb 10 17:12:26 2016
@@ -15,9 +15,20 @@
limitations under the License.
-->
-Access Control
+Access Control Management
--------------------------------------------------------------------------------
+### General
+
+This section covers fundamental concepts of the access control related APIs provided
+by JCR and Jackrabbit as well as the extensions points defined by Oak.
+
+If you are already familiar with the API and looking for examples you may directly
+read [Using the Access Control Management API](accesscontrol/editing.html) for
+a comprehensive list of method calls as well as examples that may be used to
+edit the access control content of the repository.
+
+<a href="jcr_api"/>
### JCR API
Access Control Management is an optional feature defined by [JSR 283] consisting of
@@ -47,6 +58,7 @@ The JCR access control management has th
- *effect*: policies bound to a given node only take effect upon `Session.save()`. Access to properties is defined by the their parent node.
- *scope*: a given policy may not only affect the node it is bound to but may have an effect on accessibility of items elsewhere in the workspace.
+<a name="jackrabbit_api"/>
### Jackrabbit API
The Jackrabbit API defines various access control related extensions to the
@@ -68,244 +80,7 @@ The following interfaces and extensions
- `JackrabbitAccessControlList`
- `JackrabbitAccessControlEntry`
-### Edit Access Control
-
-see section [Using the Access Control Management API](accesscontrol/editing.html) for
-a comprehensive list of method calls as well as examples that may be used to
-edit the access control content of the repository.
-
-### 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](permission/differences.html)).
-
-#### Differences wrt Jackrabbit 2.x
-
-see the corresponding [documentation](accesscontrol/differences.html).
-
-#### Resource vs Principal Based Access Control
-
-The default implementation present with Oak 1.0 is natively resource-based which
-corresponds to the way JCR defines access control. Nevertheless the principal
-based approach as defined by the Jackrabbit API is supported using a best-effort
-approach: principal-based policies are created using the Oak query API and
-fully respect the access rights imposed on the different policies that contain
-entries for a given principal. These principal-based policies can also be modified
-using the corresponding methods provided by the access control, except for
-`JackrabbitAccessControlList.orderBefore`.
-
-Thus the default implementation corresponds to the default implementation present
-with Jackrabbit 2.x. Note however, that the former principal-base approach that
-stored policies per principal in a dedicated tree is no longer available.
-
-#### Access Control Policies
-
-The Oak access control management exposes two types of policies that cover all
-use case defined by the specification and required by the default setup:
-
-| Name | Policy | Description |
-|-----------------|-------------------------------|----------------------------|
-| Default ACL | `JackrabbitAccessControlList` | access control on individual nodes |
-| Repo-Level ACL | `JackrabbitAccessControlList` | repo-level access control for the `null` path |
-| Read Policy | `NamedAccessControlPolicy` | trees that are configured to be readable to everyone |
-| | | |
-
-##### Default ACL
-
-The default access control lists are bound to individual nodes.
-They may be used to grant/deny access for all operations that are in some way
-related to JCR items: regular read/write, access control management, versioning,
-locking and as of Oak 1.0 user management and writing index definitions.
-
-These policies are designed to take effect on the complete subtree spanned by
-the node they are bound to. The individual access control entries are evaluated
-in strict order (first entries in a given list, second entries inherited from
-list bound to parent nodes) with one notable exception: access control entries
-created for non-group principals always take precedence irrespective of their
-inheritance status.
-
-Further details are described in section [Permissions](permission.html).
-
-##### Repo-Level ACL
-
-The access control lists bound to the `null` path can be used to grant/deny privileges
-associated with operations on repository-level such as namespace, node type, privilege
-and workspace management.
-
-The effect of these entries is limited to the repository operations and is
-no inherited to any items inside the repository.
-
-##### Read Policy
-
-These immutable policy has been introduced in Oak 1.0 in order to allow for opening
-up trees that need to be readable to all sessions irrespective of other effective
-policies.
-
-By default these policies are bound to the following trees:
-
-- `/jcr:system/rep:namespaces`: stores all registered namespaces
-- `/jcr:system/jcr:nodeTypes`: stores all registered node types
-- `/jcr:system/rep:privileges`: stores all registered privileges
-
-The default set can be changed or extended by setting the corresponding configuration
-option. However, it is important to note that many JCR API calls rely on the
-accessibility of the namespace, nodetype and privilege information. Removing the
-corresponding paths from the configuration will most probably have undesired effects.
-
-
-#### Access Control Entries
-
-The access control entries present in a given list are subject to the following
-rules applied upon editing but not enforced by `CommitHook`s:
-
-- *uniqueness*: a given entry may only appear onces in a list
-- *merging*: if an entry exists for a given principal with the same allow-status and restrictions, the existing entry will be updated without being moved in the list.
-- *redundancy*: if an new entry makes an existing entry (partially) redundant the existing entry will be updated or removed altogether.
-
-
-#### Restrictions
-
-Access control entries may be created by limiting their effect by adding
-restrictions as mentioned by JSR 283. Details about the restriction management
-in Oak 1.0 as well as a list of built-in restrictions and extensibility can be
-found in section [Restriction Management](accesscontrol/restriction.html).
-
-
-#### Representation in the Repository
-
-All access control policies defined with an Oak repository are stores child of
-the node they are bound to. The node type definition used to represent access control content:
-
- [rep:AccessControllable]
- mixin
- + rep:policy (rep:Policy) protected IGNORE
-
- [rep:RepoAccessControllable]
- mixin
- + rep:repoPolicy (rep:Policy) protected IGNORE
-
- [rep:Policy]
- abstract
-
- [rep:ACL] > rep:Policy
- orderable
- + * (rep:ACE) = rep:GrantACE protected IGNORE
-
- [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 /* since oak 1.0 */
-
- [rep:GrantACE] > rep:ACE
-
- [rep:DenyACE] > rep:ACE
-
- /**
- * @since oak 1.0
- */
- [rep:Restrictions]
- - * (UNDEFINED) protected
- - * (UNDEFINED) protected multiple
-
-##### Examples
-
-###### Regular ACL at /content
-
- "": {
- "jcr:primaryType": "rep:root",
- "content": {
- "jcr:primaryType": "oak:Unstructured",
- "jcr:mixinTypes": "rep:AccessControllable",
- "rep:policy": {
- "jcr:primaryType": "rep:ACL",
- "allow": {
- "jcr:primaryType": "rep:GrantACE",
- "rep:principalName": "jackrabbit",
- "rep:privileges": ["jcr:read", "rep:write"]
- },
- "deny": {
- "jcr:primaryType": "rep:DenyACE",
- "rep:principalName": "jackrabbit",
- "rep:privileges": ["jcr:addNodes", "rep:addProperties"],
- "rep:restrictions" {
- "jcr:primaryType": "rep:Restrictions",
- "rep:ntNames": ["nt:hierarchyNode", "nt:resource"]
- }
- }
- }
- }
- }
-
-###### Repo-Level Policy
-
- "": {
- "jcr:primaryType": "rep:root",
- "jcr:mixinTypes": "rep:RepoAccessControllable",
- "rep:repoPolicy": {
- "jcr:primaryType": "rep:ACL",
- "allow": {
- "jcr:primaryType": "rep:GrantACE",
- "rep:principalName": "elefant",
- "rep:privileges": ["rep:privilegeManagement"]
- }
- }
- }
-
-<a name="validation"/>
-##### Validation
-
-The consistency of this content structure is asserted by a dedicated `AccessControlValidator`.
-The corresponding errors are all of type `AccessControl` with the following codes:
-
-| Code | Message |
-|-------------------|----------------------------------------------------------|
-| 0001 | Generic access control violation |
-| 0002 | Access control entry node expected |
-| 0003 | Invalid policy name |
-| 0004 | Invalid policy node: Order of children is not stable |
-| 0005 | Access control policy within access control content |
-| 0006 | Isolated policy node |
-| 0007 | Isolated access control entry |
-| 0008 | ACE without principal name |
-| 0009 | ACE without privileges |
-| 0010 | ACE contains invalid privilege name |
-| 0011 | ACE uses abstract privilege |
-| 0012 | Repository level policies defined with non-root node |
-| 0013 | Duplicate ACE found in policy |
-
-#### XML Import
-
-As of OAK 1.0 access control content can be imported both with Session and
-Workspace import.
-
-In addition the JCR XML import behavior has been extended to respect the
-`o.a.j.oak.spi.xml.ImportBehavior` flags instead of just performing a best effort import.
-
-Currently the `ImportBehavior` is only used to switch between different ways of
-handling principals unknown to the repository. For consistency and in order to
-match the validation requirements as specified by `AccessControlList#addAccessControlEntry`
-the default behavior is ABORT (while in Jackrabbit 2.x the behavior always was BESTEFFORT).
-
-The different `ImportBehavior` flags are implemented as follows:
-- `ABORT`: throws an `AccessControlException` if the principal is unknown
-- `IGNORE`: ignore the entry defining the unknown principal
-- `BESTEFFORT`: import the access control entry with an unknown principal.
-
-In order to get the same best effort behavior as present with Jackrabbit 2.x
-the configuration parameters of the `AuthorizationConfiguration` must contain
-the following entry:
-
- importBehavior = "besteffort"
-
-See also ([OAK-1350](https://issues.apache.org/jira/browse/OAK-1350)))
-
-
+<a name="api_extensions"/>
### API Extensions
Oak defines the following interfaces extending the access control management API:
@@ -324,9 +99,10 @@ that may be used for a custom implementa
#### Restriction Management
Oak 1.0 defines a dedicated restriction management API. See
-[Restriction Management](accesscontrol/restriction.html) for details and further
+[Restriction Management](authorization/restriction.html) for details and further
information regarding extensibility and pluggability.
+<a href="utilities"/>
### Utilities
The jcr-commons module present with Jackrabbit provide some access control related
@@ -348,6 +124,13 @@ the complete list of methods.
acMgr.setPolicy(path, acl);
session.save();
+### Characteristics of the Default Implementation
+
+The behavior of the default access control implementation is described in sections
+[Access Control Management: The Default Implementation](accesscontrol/default.html)
+and [Restriction Management](authorization/restriction.html).
+
+<a name="configuration"/>
### Configuration
The configuration of the access control management implementation is handled
@@ -360,36 +143,14 @@ methods:
#### Configuration Parameters
-The default implementation supports the following configuration parameters:
-
-| Parameter | Type | Default |
-|------------------------------|---------------------|--------------------------|
-| `PARAM_RESTRICTION_PROVIDER` | RestrictionProvider | RestrictionProviderImpl |
-| `PARAM_READ_PATHS` | Set\<String\> | paths to namespace, nodetype and privilege root nodes |
-| `PARAM_IMPORT_BEHAVIOR` | String ("abort", "ignore", "besteffort") | "abort" |
-| | | |
-
-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.
-
-### Pluggability
-
-There are multiple levels for plugging access control related custom implementations:
-
-1. replace `AuthorizationConfiguration`: if you want to completely replace the way
- authorization is handled in the repository. In OSGi-base setup this is achieved
- by making the configuration implementation a service. In a non-OSGi-base setup the
- custom configuration must be exposed by the `SecurityProvider` implementation.
-2. extend `AuthorizationConfiguration`: it is planned to provide a `CompositeAuthorizationConfiguration`
- that allows to aggregate different authorization implementations (see [OAK-1268]).
-3. extend the existing implementation by providing custom restrictions (see [RestrictionManagement](authorization/restriction.html).
+The supported configuration options of the default implementation are described in the corresponding [section](accesscontrol/default.html#configuration).
### Further Reading
- [Differences wrt Jackrabbit 2.x](accesscontrol/differences.html)
+- [Access Control Management: The Default Implementation](accesscontrol/default.html)
- [Restriction Management](accesscontrol/restriction.html)
+- [Using the Access Control Management API](accesscontrol/editing.html)
<!-- hidden references -->
[JSR 283]: http://www.day.com/specs/jcr/2.0/16_Access_Control_Management.html
Added: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/default.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/default.md?rev=1729662&view=auto
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/default.md (added)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/default.md Wed Feb 10 17:12:26 2016
@@ -0,0 +1,273 @@
+<!--
+ 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.
+-->
+
+Access Control Management : 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](../permission/differences.html)).
+
+### Differences wrt Jackrabbit 2.x
+
+see the corresponding [documentation](differences.html).
+
+### Resource vs Principal Based Access Control
+
+The default implementation present with Oak 1.0 is natively resource-based which
+corresponds to the way JCR defines access control. Nevertheless the principal
+based approach as defined by the Jackrabbit API is supported using a best-effort
+approach: principal-based policies are created using the Oak query API and
+fully respect the access rights imposed on the different policies that contain
+entries for a given principal. These principal-based policies can also be modified
+using the corresponding methods provided by the access control, except for
+`JackrabbitAccessControlList.orderBefore`.
+
+Thus the default implementation corresponds to the default implementation present
+with Jackrabbit 2.x. Note however, that the former principal-base approach that
+stored policies per principal in a dedicated tree is no longer available.
+
+### The Elements of Access Control Management
+
+#### Access Control Policies
+
+The Oak access control management exposes two types of policies that cover all
+use case defined by the specification and required by the default setup:
+
+| Name | Policy | Description |
+|-----------------|-------------------------------|----------------------------|
+| Default ACL | `JackrabbitAccessControlList` | access control on individual nodes |
+| Repo-Level ACL | `JackrabbitAccessControlList` | repo-level access control for the `null` path |
+| Read Policy | `NamedAccessControlPolicy` | trees that are configured to be readable to everyone |
+| | | |
+
+##### Default ACL
+
+The default access control lists are bound to individual nodes.
+They may be used to grant/deny access for all operations that are in some way
+related to JCR items: regular read/write, access control management, versioning,
+locking and as of Oak 1.0 user management and writing index definitions.
+
+These policies are designed to take effect on the complete subtree spanned by
+the node they are bound to. The individual access control entries are evaluated
+in strict order (first entries in a given list, second entries inherited from
+list bound to parent nodes) with one notable exception: access control entries
+created for non-group principals always take precedence irrespective of their
+inheritance status.
+
+Further details are described in section [Permissions](../permission.html).
+
+##### Repo-Level ACL
+
+The access control lists bound to the `null` path can be used to grant/deny privileges
+associated with operations on repository-level such as namespace, node type, privilege
+and workspace management.
+
+The effect of these entries is limited to the repository operations and is
+no inherited to any items inside the repository.
+
+##### Read Policy
+
+These immutable policy has been introduced in Oak 1.0 in order to allow for opening
+up trees that need to be readable to all sessions irrespective of other effective
+policies.
+
+By default these policies are bound to the following trees:
+
+- `/jcr:system/rep:namespaces`: stores all registered namespaces
+- `/jcr:system/jcr:nodeTypes`: stores all registered node types
+- `/jcr:system/rep:privileges`: stores all registered privileges
+
+The default set can be changed or extended by setting the corresponding configuration
+option. However, it is important to note that many JCR API calls rely on the
+accessibility of the namespace, nodetype and privilege information. Removing the
+corresponding paths from the configuration will most probably have undesired effects.
+
+
+#### Access Control Entries
+
+The access control entries present in a given list are subject to the following
+rules applied upon editing but not enforced by `CommitHook`s:
+
+- *uniqueness*: a given entry may only appear onces in a list
+- *merging*: if an entry exists for a given principal with the same allow-status and restrictions, the existing entry will be updated without being moved in the list.
+- *redundancy*: if an new entry makes an existing entry (partially) redundant the existing entry will be updated or removed altogether.
+
+
+#### Restrictions
+
+Access control entries may be created by limiting their effect by adding
+restrictions as mentioned by JSR 283. Details about the restriction management
+in Oak 1.0 as well as a list of built-in restrictions and extensibility can be
+found in section [Restriction Management](../authorization/restriction.html).
+
+
+### Representation in the Repository
+
+All access control policies defined with an Oak repository are stores child of
+the node they are bound to. The node type definition used to represent access control content:
+
+ [rep:AccessControllable]
+ mixin
+ + rep:policy (rep:Policy) protected IGNORE
+
+ [rep:RepoAccessControllable]
+ mixin
+ + rep:repoPolicy (rep:Policy) protected IGNORE
+
+ [rep:Policy]
+ abstract
+
+ [rep:ACL] > rep:Policy
+ orderable
+ + * (rep:ACE) = rep:GrantACE protected IGNORE
+
+ [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 /* since oak 1.0 */
+
+ [rep:GrantACE] > rep:ACE
+
+ [rep:DenyACE] > rep:ACE
+
+ /**
+ * @since oak 1.0
+ */
+ [rep:Restrictions]
+ - * (UNDEFINED) protected
+ - * (UNDEFINED) protected multiple
+
+##### Examples
+
+###### Regular ACL at /content
+
+ "": {
+ "jcr:primaryType": "rep:root",
+ "content": {
+ "jcr:primaryType": "oak:Unstructured",
+ "jcr:mixinTypes": "rep:AccessControllable",
+ "rep:policy": {
+ "jcr:primaryType": "rep:ACL",
+ "allow": {
+ "jcr:primaryType": "rep:GrantACE",
+ "rep:principalName": "jackrabbit",
+ "rep:privileges": ["jcr:read", "rep:write"]
+ },
+ "deny": {
+ "jcr:primaryType": "rep:DenyACE",
+ "rep:principalName": "jackrabbit",
+ "rep:privileges": ["jcr:addNodes", "rep:addProperties"],
+ "rep:restrictions" {
+ "jcr:primaryType": "rep:Restrictions",
+ "rep:ntNames": ["nt:hierarchyNode", "nt:resource"]
+ }
+ }
+ }
+ }
+ }
+
+###### Repo-Level Policy
+
+ "": {
+ "jcr:primaryType": "rep:root",
+ "jcr:mixinTypes": "rep:RepoAccessControllable",
+ "rep:repoPolicy": {
+ "jcr:primaryType": "rep:ACL",
+ "allow": {
+ "jcr:primaryType": "rep:GrantACE",
+ "rep:principalName": "elefant",
+ "rep:privileges": ["rep:privilegeManagement"]
+ }
+ }
+ }
+
+### XML Import
+
+As of OAK 1.0 access control content can be imported both with Session and
+Workspace import.
+
+In addition the JCR XML import behavior has been extended to respect the
+`o.a.j.oak.spi.xml.ImportBehavior` flags instead of just performing a best effort import.
+
+Currently the `ImportBehavior` is only used to switch between different ways of
+handling principals unknown to the repository. For consistency and in order to
+match the validation requirements as specified by `AccessControlList#addAccessControlEntry`
+the default behavior is ABORT (while in Jackrabbit 2.x the behavior always was BESTEFFORT).
+
+The different `ImportBehavior` flags are implemented as follows:
+- `ABORT`: throws an `AccessControlException` if the principal is unknown
+- `IGNORE`: ignore the entry defining the unknown principal
+- `BESTEFFORT`: import the access control entry with an unknown principal.
+
+In order to get the same best effort behavior as present with Jackrabbit 2.x
+the configuration parameters of the `AuthorizationConfiguration` must contain
+the following entry:
+
+ importBehavior = "besteffort"
+
+See also ([OAK-1350](https://issues.apache.org/jira/browse/OAK-1350)))
+
+<a name="validation"/>
+### Validation
+
+The consistency of this content structure is asserted by a dedicated `AccessControlValidator`.
+The corresponding errors are all of type `AccessControl` with the following codes:
+
+| Code | Message |
+|-------------------|----------------------------------------------------------|
+| 0001 | Generic access control violation |
+| 0002 | Access control entry node expected |
+| 0003 | Invalid policy name |
+| 0004 | Invalid policy node: Order of children is not stable |
+| 0005 | Access control policy within access control content |
+| 0006 | Isolated policy node |
+| 0007 | Isolated access control entry |
+| 0008 | ACE without principal name |
+| 0009 | ACE without privileges |
+| 0010 | ACE contains invalid privilege name |
+| 0011 | ACE uses abstract privilege |
+| 0012 | Repository level policies defined with non-root node |
+| 0013 | Duplicate ACE found in policy |
+
+
+<a name="configuration"/>
+### Configuration
+
+#### Configuration Parameters
+
+The default implementation supports the following configuration parameters:
+
+| Parameter | Type | Default |
+|------------------------------|---------------------|--------------------------|
+| `PARAM_RESTRICTION_PROVIDER` | RestrictionProvider | RestrictionProviderImpl |
+| `PARAM_READ_PATHS` | Set\<String\> | paths to namespace, nodetype and privilege root nodes |
+| `PARAM_IMPORT_BEHAVIOR` | String ("abort", "ignore", "besteffort") | "abort" |
+| | | |
+
+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.
+
+<!-- hidden references -->
+[AuthorizationConfiguration]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/AuthorizationConfiguration.html
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/differences.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/differences.md?rev=1729662&r1=1729661&r2=1729662&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/differences.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/differences.md Wed Feb 10 17:12:26 2016
@@ -14,7 +14,7 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-### AccessControl Management : Differences wrt Jackrabbit 2.x
+### Access Control Management : Differences wrt Jackrabbit 2.x
#### Characteristics of the Default Implementation
@@ -73,16 +73,10 @@ on the target node(s). Similarly, the pe
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:
+The implementation of the additional restrictions associated with an ACE has been
+slighly modified/extended.
-- 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.
+See section [Restriction Management](../authorization/restriction.html) for details.
##### Import
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication.md?rev=1729662&r1=1729661&r2=1729662&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication.md Wed Feb 10 17:12:26 2016
@@ -76,7 +76,8 @@ LoginModule is configured and succeeds,
LoginModule need to have succeeded for the overall authentication to succeed. If no Required or Requisite LoginModules
are configured for an application, then at least one Sufficient or Optional LoginModule must succeed.
-### JCR Authentication
+<a href="jcr_api"/>
+### JCR API
Within the scope of JCR `Repository.login` is used to authenticate a given user.
This method either takes a `Credentials` argument if the validation is performed
@@ -103,10 +104,8 @@ for further details.
In addition JCR defines `Session.impersonate(Credentials)` to impersonate another
user or - as of JSR 333 - clone an existing session.
-
-### Oak Authentication
-
-#### Oak API
+<a href="oak_api"/>
+### Oak API
The Oak API contains the following authentication related methods and interfaces
@@ -114,211 +113,14 @@ The Oak API contains the following authe
- `ContentRepository.login(Credentials, String)`: The Oak counterpart of the JCR login.
- `ContentSession.getAuthInfo()`: exposes the `AuthInfo` associated with the `ContentSession`.
+### Oak Authentication Implementation
-#### Differences wrt Jackrabbit 2.x
-
-See section [differences](authentication/differences.html) for complete list of
-differences wrt authentication between Jackrabbit 2.x and Oak.
-
-#### Guest Login
-
-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);
-
-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](authentication/preauthentication.html)).
-
-Similarly, any special treatment that Jackrabbit core applied for the guest (anonymous)
-user has been omitted altogether from the default [LoginModuleImpl]. In the default
-setup the built-in anonymous user will be 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.
-
-##### Guest Login Module
-
-The aim of the [GuestLoginModule] implementation is to provide backwards compatibility
-with Jackrabbit 2.x with respect to the guest (anonymous) login: the `GuestLoginModule`
-can be added as _optional_ entry to the chain of login modules in the JAAS (or
-corresponding OSGi) configuration.
-
-Example JAAS Configuration:
-
- jackrabbit.oak {
- org.apache.jackrabbit.oak.spi.security.authentication.GuestLoginModule optional;
- org.apache.jackrabbit.oak.security.authentication.user.LoginModuleImpl required;
- };
-
-
-The behavior of the `GuestLoginModule` is as follows:
-
-*Phase 1: Login*
-
-- tries to retrieve JCR credentials from the [CallbackHandler] using the [CredentialsCallback]
-- in case no credentials could be obtained it pushes a new instance of [GuestCredentials] to the shared stated
- and **returns** `true`
-- otherwise it **returns** `false`
-
-*Phase 2: Commit*
-
-- if the phase 1 succeeded it will add the `GuestCredentials` created above and
- `EveryonePrincipal` the `Subject` in phase 2 of the login process and **returns** `true`
-- otherwise it **returns** `false`
-
-#### UserId/Password Login
-
-Oak 1.0 comes with 2 different login module implementations that can handle
-`SimpleCredentials`:
-
-- Default (`LoginModuleImpl`) as described below
-- `ExternalLoginModule` as described in section [External Authentication](authentication/externalloginmodule.html)
-
-##### Default Login Module
-
-The [LoginModuleImpl] defines a regular userId/password login and requires a
-repository setup that supports [User Management](user.html) and is designed to
-supports the following `Credentials`:
-
-- `SimpleCredentials`
-- `GuestCredentials` (see above)
-- `ImpersonationCredentials` (see below)
-
-This login module implementations behaves as follows:
-
-*Phase 1: Login*
-
-* if a user does not exist in the repository (i.e. cannot be provided by the user manager) it **returns `false`**.
-* if an authorizable with the respective userId exists but is a group or a disabled users, it **throws `LoginException`**
-* if a user exists in the repository and the credentials don't match, it **throws `LoginException`**
-* if a user exists in the repository and the credentials match, it **returns `true`**
- * also, it adds the credentials to the shared state
- * also, it adds the login name to the shared state
- * also, it calculates the principals and adds them to the private state
- * also, it adds the credentials to the private state
-
-*Phase 2: Commit*
-
-* if the private state contains the credentials and principals, it adds them (both) to the subject and **returns `true`**
-* if the private state does not contain credentials and principals, it clears the state and **returns `false`**
-
-#### Impersonation
-
-Another flavor of the Oak authentication implementation is covered by
-`javax.jcr.Session#impersonate(Credentials)`, which allows to obtain an new
-`Session` for user identified by the specified credentials. As of JSR 333
-this method can also be used in order to clone the existing session (i.e.
-self-impersonation of the user that holds the session.
-
-With Oak 1.0 impersonation is implemented as follows:
-
-1. `Session#impersonate` takes any kind of `Credentials`
-2. the specified credentials are wrapped in a new instance of [ImpersonationCredentials]
- along with the current `AuthInfo` object.
-3. these `ImpersonationCredentials` are passed to `Repository.login`
-
-Whether or not impersonation succeeds consequently both depends on the authentication
-setup and on some implementation specific validation that make sure the
-editing session is allowed to impersonate the user identified by the credentials
-passed to the impersonate call.
-
-With Oak 1.0 only the default login module ([LoginModuleImpl]) is able to deal
-with `ImpersonationCredentials` and applies the following logic:
-
-- **Self-Impersonation**: Any attempt to impersonate the same session will succeed
- as long as the user is still valid (i.e. exists and has not been disabled).
-- **Regular Impersonation**: Impersonation another user will only succeed if
- the impersonated user is valid (i.e. exists and is not disabled) _and_ the
- the user associated with the editing session is allowed to impersonate this
- user. The latter depends on the [User Management](user.html) implementation
- specifically on the return value of `User.getImpersonation().allows(Subject subject)`.
-
-##### ImpersonationCredentials
-
-Since the implementation of `Session.impersonate` no longer uses `SimpleCredentials`
-to transport the original `Subject` but rather performs the login with dedicated
-[ImpersonationCredentials], impersonation is no longer restricted to `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. Note however that applications relying on the Jackrabbit
-implementation and manually creating `SimpleCredentials` with a
-`SecurityConstants.IMPERSONATOR_ATTRIBUTE`, would need to be refactor after
-migration to Oak.
-
-##### Impersonation with Custom Authentication Setup
-
-Applications that wish to use a custom authentication setup need to ensure the
-following steps in order to get JCR impersonation working:
-
-- Respect `ImpersonationCredentials` in the authentication setup.
-- Identify the impersonated from `ImpersonationCredentials.getBaseCredentials`
- and verify if it can be authenticated.
-- Validate that the editing session is allowed to impersonate: The user associated
- with the editing session can be identified by the [AuthInfo] obtained from
- from `ImpersonationCredentials.getImpersonatorInfo()`.
-
-
-#### Token Login
-
-See section [Token Authentication](authentication/tokenmanagement.html) for details
-regarding token based authentication.
-
-##### Token Login Module
-
-The `TokenLoginModule` is in charge of creating new login tokens and validate
-repository logins with `TokenCredentials`. The exact behavior of this login module is
-described in section [Token Authentication](authentication/tokenmanagement.html).
-
-
-#### Pre-Authenticated Login
-
-Oak provides two different mechanisms to create pre-authentication that doesn't
-involve the repositories internal authentication mechanism for credentials
-validation.
-
-- Pre-Authentication combined with Login Module Chain
-- Pre-Authentication without Repository Involvement (aka `null` login)
-
-See section [Pre-Authentication Login](authentication/preauthentication.html) for
-further details and examples.
-
-#### External Login
-
-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 a default
-implementation with extension points:
-
-- [External Authentication](authentication/externalloginmodule.html): Summary of
- the external authentication and details about the `ExternalLoginModule`.
-- [User and Group Synchronization](authentication/usersync.html): Details regarding
- user and group synchronization as well as a list of configuration options provided
- by the the default implementations present with Oak.
-- [Identity Management](authentication/identitymanagement.html): Further information regarding extenal identity management.
-- [LDAP Integration](authentication/ldap.html): How to make use of the `ExternalLoginModule`
- with the LDAP identity provider implementation. This combination is aimed to replace
- [com.day.crx.security.ldap.LDAPLoginModule], which relies on Jackrabbit internals
- and will no longer work with Oak.
-
-##### External Login Module
-
-The external login module is a base implementation that allows easy integration
-of 3rd party authentication and identity systems, such as [LDAP](ldap.html). The
-general mode of the external login module is to use the external system as authentication
-source and as a provider for users and groups that may also be synchronized into
-the repository.
-
-This login module implementation requires an valid `SyncHandler` and `IdentityProvider`
-to be present. The detailed behavior of the `ExternalLoginModule` is described in
-section [External Authentication](authentication/externalloginmodule.html).
+A description of the various requirements covered by Oak by default as well
+as the characteristics of the corresponding implementations can be found in
+section [Authentication: Implementation Details].
+See section [differences](authentication/differences.html) for comprehensive list
+of differences wrt authentication between Jackrabbit 2.x and Oak.
### API Extension
@@ -344,7 +146,7 @@ security related interfaces (e.g. `Princ
Subclasses are required to implement the following methods:
-- `getSupportedCredentials(): return a set of supported credential classes.
+- `getSupportedCredentials()`: return a set of supported credential classes.
- `login()`: The login method defined by `LoginModule`
- `commit()`: The commit method defined by `LoginModule`
@@ -391,40 +193,6 @@ Subclasses are required to implement the
}
}
-
-
-
-#### Token Management
-
-See section [token management](authentication/tokenmanagement.html) for details.
-
-- `TokenConfiguration`: Interface to obtain a `TokenProvider` instance.
-- `TokenProvider`: Interface to manage login tokens.
-- `TokenInfo`: Information related to a login token and token validity.
-
-#### User and Group Synchronization
-
-See section [Synchronization](authentication/usersync.html) for details.
-
-- `SyncManager`: factory for the `SyncHandler`
-- `SyncHandler`: responsible for synchronizing users/groups from an `ExternalIdentityProvider` into the repository.
-- `SyncContext`: executes the synchronization
-- `SyncedIdentity`: represents a synchronized identity
-- `SyncResult`: the result of a sync operation
-
-#### External Identity Management
-
-Oak in addition provides interfaces to ease custom implementation of the external
-authentication with optional user/group synchronization to the repository.
-See section [identity management](authentication/identitymanagement.html) for details.
-
-- `ExternalIdentityProviderManager`: factory for the `ExternalIdentityProvider`
-- `ExternalIdentityProvider`: provides user/group information from a third party system.
-- `ExternalIdentity`: base interface for an external user/group
- - `ExternalUser`
- - `ExternalGroup`
-- `ExternalIdentityRef`: reference to an external user/group
-
### Configuration
The configuration of the authentication setup is defined by the [AuthenticationConfiguration].
@@ -439,7 +207,7 @@ There also exists a utility class that a
- `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
+ - `TokenLoginModule`: covers token based authentication
- `LoginModuleImpl`: covering regular uid/pw login
### Pluggability
@@ -455,16 +223,10 @@ implementation on various levels:
login modules and their individual settings. In an OSGi-base setup is achieved
by making the modules accessible to the framework and setting their execution
order accordingly. In a Non-OSGi setup this is specified in the [JAAS config].
-3. The `LoginModuleImpl` uses `UserAuthentication`-implementations for performing
- the authentication process. Which user-authentication implementation to use is
- determined by the available `UserAuthenticationFactory`s which provide user-
- authentication implementations if a given `UserConfiguration` is accepted.
- Which user-authentication-factory is chosen depends on its OSGi service
- ranking property. The default factory has a ranking of 0 (OSGi default). Services with
- the highest ranking take precedence.
### Further Reading
+- [Authentication: Implementation Details](authentication/default.html)
- [Differences wrt Jackrabbit 2.x](authentication/differences.html)
- [Token Authentication and Token Management](authentication/tokenmanagement.html)
- [External Authentication](authentication/externalloginmodule.html)
@@ -480,12 +242,8 @@ implementation on various levels:
[javax.jcr.SimpleCredentials]: http://www.day.com/specs/javax.jcr/javadocs/jcr-2.0/javax/jcr/SimpleCredentials.html
[javax.jcr.Repository]: http://www.day.com/specs/javax.jcr/javadocs/jcr-2.0/javax/jcr/Repository.html
[org.apache.jackrabbit.api.JackrabbitRepository]: http://svn.apache.org/repos/asf/jackrabbit/trunk/jackrabbit-api/src/main/java/org/apache/jackrabbit/api/JackrabbitRepository.java
-[ImpersonationCredentials]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/ImpersonationCredentials.html
[AuthInfoImpl]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/AuthInfoImpl.html
[AuthInfo]: /oak/docs/apidocs/org/apache/jackrabbit/oak/api/AuthInfo.html
-[GuestLoginModule]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/GuestLoginModule.html
-[LoginModuleImpl]: /oak/docs/apidocs/org/apache/jackrabbit/oak/security/authentication/user/LoginModuleImpl.html
-[com.day.crx.security.ldap.LDAPLoginModule]: http://dev.day.com/docs/en/crx/current/administering/ldap_authentication.html
+[AbstractLoginModule]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/AbstractLoginModule.html
[AuthenticationConfiguration]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/AuthenticationConfiguration.html
-[AbstractLoginModoule]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/AbstractLoginModule.html
[JAAS config]: http://docs.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html
\ No newline at end of file
Added: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/default.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/default.md?rev=1729662&view=auto
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/default.md (added)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/default.md Wed Feb 10 17:12:26 2016
@@ -0,0 +1,270 @@
+<!--
+ 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.
+-->
+
+Authentication : Implementation Details
+--------------------------------------------------------------------------------
+
+### General
+
+Jackrabbit Oak covers different authentication requirements by providing default
+implementations and extension points for different setup scenarios.
+
+### Differences wrt Jackrabbit 2.x
+
+See the corresponding [documentation](differences.html).
+
+### Authentication Requirements
+
+Jackrabbit Oak covers the following login requirements and provides
+dedicated `LoginModule` implementation(s) for each scenario:
+
+- [Guest Login](#guest)
+- [UserId/Password Login](#uid_pw)
+- [Impersonation Login](#impersonation)
+- [Token Login](#token)
+- [Pre-Authenticated Login](#pre_authenticated)
+- [External Login](#external)
+
+<a name="guest"/>
+#### Guest Login
+
+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);
+
+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](authentication/preauthentication.html)).
+
+Similarly, any special treatment that Jackrabbit core applied for the guest (anonymous)
+user has been omitted altogether from the default [LoginModuleImpl]. In the default
+setup the built-in anonymous user will be 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.
+
+##### GuestLoginModule
+
+The aim of the [GuestLoginModule] implementation is to provide backwards compatibility
+with Jackrabbit 2.x with respect to the guest (anonymous) login: the `GuestLoginModule`
+can be added as _optional_ entry to the chain of login modules in the JAAS (or
+corresponding OSGi) configuration.
+
+Example JAAS Configuration:
+
+ jackrabbit.oak {
+ org.apache.jackrabbit.oak.spi.security.authentication.GuestLoginModule optional;
+ org.apache.jackrabbit.oak.security.authentication.user.LoginModuleImpl required;
+ };
+
+
+The behavior of the `GuestLoginModule` is as follows:
+
+*Phase 1: Login*
+
+- tries to retrieve JCR credentials from the [CallbackHandler] using the [CredentialsCallback]
+- in case no credentials could be obtained it pushes a new instance of [GuestCredentials] to the shared stated
+ and **returns** `true`
+- otherwise it **returns** `false`
+
+*Phase 2: Commit*
+
+- if the phase 1 succeeded it will add the `GuestCredentials` created above and
+ `EveryonePrincipal` the `Subject` in phase 2 of the login process and **returns** `true`
+- otherwise it **returns** `false`
+
+<a name="uid_pw"/>
+#### UserId/Password Login
+
+Oak 1.0 comes with 2 different login module implementations that can handle
+[SimpleCredentials]:
+
+- Default (`LoginModuleImpl`) as described below
+- `ExternalLoginModule` as described in section [External Authentication](authentication/externalloginmodule.html)
+
+##### LoginModuleImpl
+
+The [LoginModuleImpl] defines a regular userId/password login and requires a
+repository setup that supports [User Management](user.html) and is designed to
+supports the following `Credentials`:
+
+- `SimpleCredentials`
+- `GuestCredentials` (see above)
+- `ImpersonationCredentials` (see below)
+
+This login module implementations behaves as follows:
+
+*Phase 1: Login*
+
+* if a user does not exist in the repository (i.e. cannot be provided by the user manager) it **returns `false`**.
+* if an authorizable with the respective userId exists but is a group or a disabled users, it **throws `LoginException`**
+* if a user exists in the repository and the credentials don't match, it **throws `LoginException`**
+* if a user exists in the repository and the credentials match, it **returns `true`**
+ * also, it adds the credentials to the shared state
+ * also, it adds the login name to the shared state
+ * also, it calculates the principals and adds them to the private state
+ * also, it adds the credentials to the private state
+
+*Phase 2: Commit*
+
+* if the private state contains the credentials and principals, it adds them (both) to the subject and **returns `true`**
+* if the private state does not contain credentials and principals, it clears the state and **returns `false`**
+
+<a name="user_authentication"/>
+###### User Authentication
+
+The `LoginModuleImpl` uses a configured `Authentication`-implementation for
+performing the login step. Which implementation to use is determined by the
+[UserAuthenticationFactory] obtained by the given `UserConfiguration`. It is
+expected to provides an `Authentication` implementation if the given
+`UserConfiguration` is accepted.
+
+In case multiple implementations of the `UserAuthenticationFactory` are available,
+the precendece depends on its OSGi service ranking property. The default factory
+implementation has a ranking of 0 (OSGi default). Services with the highest ranking
+will take precedence.
+
+See also section [user management](../user/default.html#pluggability).
+
+<a name="impersonation"/>
+#### Impersonation Login
+
+Another flavor of the Oak authentication implementation is covered by
+`javax.jcr.Session#impersonate(Credentials)`, which allows to obtain an new
+`Session` for a user identified by the specified credentials. As of JSR 333
+this method can also be used in order to clone the existing session (i.e.
+self-impersonation of the user that holds the session.
+
+With Oak 1.0 impersonation is implemented as follows:
+
+1. `Session#impersonate` takes any kind of `Credentials`
+2. the specified credentials are wrapped in a new instance of [ImpersonationCredentials]
+ along with the current `AuthInfo` object.
+3. these `ImpersonationCredentials` are passed to `Repository.login`
+
+Whether or not impersonation succeeds consequently both depends on the authentication
+setup and on some implementation specific validation that make sure the
+editing session is allowed to impersonate the user identified by the credentials
+passed to the impersonate call.
+
+With Oak 1.0 only the default login module ([LoginModuleImpl]) is able to deal
+with `ImpersonationCredentials` and applies the following logic:
+
+- **Self-Impersonation**: Any attempt to impersonate the same session will succeed
+ as long as the user is still valid (i.e. exists and has not been disabled).
+- **Regular Impersonation**: Impersonation another user will only succeed if
+ the impersonated user is valid (i.e. exists and is not disabled) _and_ the
+ the user associated with the editing session is allowed to impersonate this
+ user. The latter depends on the [User Management](user.html) implementation
+ specifically on the return value of `User.getImpersonation().allows(Subject subject)`.
+
+##### ImpersonationCredentials
+
+Since the implementation of `Session.impersonate` no longer uses `SimpleCredentials`
+to transport the original `Subject` but rather performs the login with dedicated
+[ImpersonationCredentials], impersonation is no longer restricted to `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. Note however that applications relying on the Jackrabbit
+implementation and manually creating `SimpleCredentials` with a
+`SecurityConstants.IMPERSONATOR_ATTRIBUTE`, would need to be refactor after
+migration to Oak.
+
+##### Impersonation with Custom Authentication Setup
+
+Applications that wish to use a custom authentication setup need to ensure the
+following steps in order to get JCR impersonation working:
+
+- Respect `ImpersonationCredentials` in the authentication setup.
+- Identify the impersonated from `ImpersonationCredentials.getBaseCredentials`
+ and verify if it can be authenticated.
+- Validate that the editing session is allowed to impersonate: The user associated
+ with the editing session can be identified by the [AuthInfo] obtained from
+ from `ImpersonationCredentials.getImpersonatorInfo()`.
+
+<a name="token"/>
+#### Token Login
+
+See section [Token Authentication](authentication/tokenmanagement.html) for details
+regarding token based authentication.
+
+##### TokenLoginModule
+
+The `TokenLoginModule` is in charge of creating new login tokens and validate
+repository logins with `TokenCredentials`. The exact behavior of this login module is
+described in section [Token Authentication](authentication/tokenmanagement.html).
+
+<a name="pre_authenticated"/>
+#### Pre-Authenticated Login
+
+Oak provides two different mechanisms to create pre-authentication that doesn't
+involve the repositories internal authentication mechanism for credentials
+validation.
+
+- Pre-Authentication combined with Login Module Chain
+- Pre-Authentication without Repository Involvement (aka `null` login)
+
+See section [Pre-Authentication Login](authentication/preauthentication.html) for
+further details and examples.
+
+<a name="external"/>
+#### External Login
+
+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 a default
+implementation with extension points:
+
+- [External Authentication](authentication/externalloginmodule.html): Summary of
+ the external authentication and details about the `ExternalLoginModule`.
+- [User and Group Synchronization](authentication/usersync.html): Details regarding
+ user and group synchronization as well as a list of configuration options provided
+ by the the default implementations present with Oak.
+- [Identity Management](authentication/identitymanagement.html): Further information regarding extenal identity management.
+- [LDAP Integration](authentication/ldap.html): How to make use of the `ExternalLoginModule`
+ with the LDAP identity provider implementation. This combination is aimed to replace
+ [com.day.crx.security.ldap.LDAPLoginModule], which relies on Jackrabbit internals
+ and will no longer work with Oak.
+
+##### ExternalLoginModule
+
+The [ExternalLoginModule] is a base implementation that allows easy integration
+of 3rd party authentication and identity systems, such as [LDAP](ldap.html). The
+general mode of the external login module is to use the external system as authentication
+source and as a provider for users and groups that may also be synchronized into
+the repository.
+
+This login module implementation requires an valid `SyncHandler` and `IdentityProvider`
+to be present. The detailed behavior of the `ExternalLoginModule` is described in
+section [External Authentication](authentication/externalloginmodule.html).
+
+<!-- hidden references -->
+[GuestCredentials]: http://www.day.com/specs/javax.jcr/javadocs/jcr-2.0/javax/jcr/GuestCredentials.html
+[SimpleCredentials]: http://www.day.com/specs/javax.jcr/javadocs/jcr-2.0/javax/jcr/SimpleCredentials.html
+[ImpersonationCredentials]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/ImpersonationCredentials.html
+[AuthInfo]: /oak/docs/apidocs/org/apache/jackrabbit/oak/api/AuthInfo.html
+[GuestLoginModule]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/GuestLoginModule.html
+[LoginModuleImpl]: /oak/docs/apidocs/org/apache/jackrabbit/oak/security/authentication/user/LoginModuleImpl.html
+[com.day.crx.security.ldap.LDAPLoginModule]: http://dev.day.com/docs/en/crx/current/administering/ldap_authentication.html
+[AbstractLoginModule]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/AbstractLoginModule.html
+[UserAuthenticationFactory]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/user/UserAuthenticationFactory.html
\ No newline at end of file
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/identitymanagement.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/identitymanagement.md?rev=1729662&r1=1729661&r2=1729662&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/identitymanagement.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/identitymanagement.md Wed Feb 10 17:12:26 2016
@@ -20,7 +20,8 @@ External Identity Management
### General
-_todo_
+Jackrabbit Oak provides interfaces and some base classes to ease custom implementation
+of the external authentication with optional user/group synchronization to the repository.
### Identity Management API
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/tokenmanagement.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/tokenmanagement.md?rev=1729662&r1=1729661&r2=1729662&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/tokenmanagement.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/tokenmanagement.md Wed Feb 10 17:12:26 2016
@@ -64,8 +64,9 @@ authentication phases behave as follows:
Oak 1.0 defines the following interfaces used to manage login tokens:
+- [TokenConfiguration]: Interface to obtain a `TokenProvider` instance (see section [configuration](#configuration) below).
- [TokenProvider]: Interface to read and manage login tokens.
-- [TokenInfo]: Information associated with a given login token.
+- [TokenInfo]: Information associated with a given login token and token validity.
In addition Oak comes with a default implementation of the provider interface
that is able to aggregate multiple `TokenProvider`s:
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/usersync.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/usersync.md?rev=1729662&r1=1729661&r2=1729662&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/usersync.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/usersync.md Wed Feb 10 17:12:26 2016
@@ -34,7 +34,7 @@ Oak comes with a default implementation
- [SyncContext]: executes the synchronization
- [SyncedIdentity]: represents a synchronized identity
- [SyncResult]: the result of a sync operation
-- [SyncException]
+- [SyncException]: marker for sync related errors
#### JMX Synchronization Tool
Added: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization.md?rev=1729662&view=auto
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization.md (added)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization.md Wed Feb 10 17:12:26 2016
@@ -0,0 +1,104 @@
+<!--
+ 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.
+-->
+
+Authorization
+--------------------------------------------------------------------------------
+
+### General Notes
+
+One of main goals for Oak security, was to clearly separates between access control
+management (such as defined by the JCR and Jackrabbit API) and the internal
+permission evaluation.
+
+While access control management is defined to be an optional feature added in JCR 2.0,
+permission evaluation was mandated since the very first version of JCR even though
+it remained an implementation detail.
+
+The documentation follows this separations and handles access control and permission
+evaluation separately:
+
+- [Access Control Management](accesscontrol.html)
+- [Permissions](permission.html)
+
+Despite the fact that there is a distinction between the public facing access
+control management and the internal permission evaluation, these two topics remain
+connected to one another and a given authorization model is expected to define and
+handle both in a consistent manner. Consequently the main entry point for
+authorization related operations is a single `AuthorizationConfiguration` (see
+section [configuration](#configuration) below).
+
+<a name="api_extensions"/>
+### API Extensions
+
+The API extensions provided by Oak are covered in the following sections:
+
+- [Access Control Management](accesscontrol.html#api_extensions)
+- [Permissions](permission.html#api_extensions)
+- [Restriction Management](authorization/restriction.html#api_extensions)
+
+<a name="configuration"/>
+### Configuration
+
+The configuration of the authorization related parts is handled by the [AuthorizationConfiguration].
+This class provides the following methods:
+
+- `getAccessControlManager`: get a new ac manager instance (see [Access Control Management](accesscontrol.html)).
+- `getPermissionProvider`: get a new permission provider instance (see [Permissions](permission.html)).
+- `getRestrictionProvider`: get a new instance of the restriction provider (see [Restriction Management](authorization/restriction.html).
+
+#### Configuration Parameters
+
+The supported configuration options of the default implementation are described
+separately for [access control management](accesscontrol/default.html#configuration)
+and [permission evalution](permission/default.html#configuration) .
+
+<a name="pluggability"/>
+### Pluggability
+
+There are multiple options for plugging authorization related custom implementations:
+
+#### Aggregation of Different Authorization Models
+
+##### Since Oak 1.4
+
+As of Oak 1.4 the built-in `SecurityProvider` implementations allow for the
+aggregation of multiple `AuthorizationConfiguration`s.
+
+The behaviour of the `CompositeAuthorizationConfiguration` is described in
+the corresponding [section](authorization/composite.html) (see also [OAK-1268]).
+
+##### Previous Versions
+
+In previous versions of Oak aggregation of multiple authorization models was
+not supported and it was only possible to replace the existing `AuthorizationConfiguration`.
+This would completely replace the default way of handling authorization in the repository.
+
+In OSGi-base setup this is achieved by making the configuration implementation a service
+such that it takes precendece over the default.
+
+In a non-OSGi-base setup the custom configuration must be exposed by the `SecurityProvider` implementation.
+
+#### Extending the Restriction Provider
+
+In all versions of Oak it is possible to plug custom implementation(s) for the
+restriction management that allows to narrow the effect of permissions to
+items matching a given, defined behavior. Details can be found in section
+[RestrictionManagement](authorization/restriction.html#pluggability).
+
+<!-- hidden references -->
+[AuthorizationConfiguration]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/AuthorizationConfiguration.html
+[OAK-1268]: https://issues.apache.org/jira/browse/OAK-1268
\ No newline at end of file
Added: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/composite.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/composite.md?rev=1729662&view=auto
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/composite.md (added)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/composite.md Wed Feb 10 17:12:26 2016
@@ -0,0 +1,35 @@
+<!--
+ 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.
+-->
+
+Combining Multiple Authorization Models
+--------------------------------------------------------------------------------
+
+### General Notes
+
+_TODO_
+
+### API Extensions
+
+_TODO_
+
+### Configuration
+
+_TODO_
+
+
+<!-- hidden references -->
+[OAK-1268]: https://issues.apache.org/jira/browse/OAK-1268
\ No newline at end of file
Copied: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/cug.md (from r1728531, jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/cug.md)
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/cug.md?p2=jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/cug.md&p1=jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/cug.md&r1=1728531&r2=1729662&rev=1729662&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/cug.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/cug.md Wed Feb 10 17:12:26 2016
@@ -22,25 +22,41 @@ Managing Access with Closed User Groups
_todo_
-### CUG API
+<a name="jackrabbit_api"/>
+### Jackrabbit API
-_todo_
+_todo: PrincipalSetPolicy_
+
+<a name="api_extensions"/>
+### API Extensions
+
+_todo: CugPolicy_
+_todo: CugExclude_
-### Characteristics of the CUG Implementation
+### Characteristics of the default CUG Implementation
_todo_
#### CUG Representation in the Repository
-##### Content Structure
-
-_todo_
+CUG policies defined by this module in a dedicate node name `rep:cugPolicy` of
+type `rep:CugPolicy`. This node is defined by a dedicate mixin type
+`rep:CugMixin` (similar to `rep:AccessControllable`) and has a single mandatory,
+protected property which stores the name of principals that are granted read
+access in the restricted area:
+
+ [rep:CugMixin]
+ mixin
+ + rep:cugPolicy (rep:CugPolicy) protected IGNORE
+
+ [rep:CugPolicy] > rep:Policy
+ - rep:principalNames (STRING) multiple protected mandatory IGNORE
<a name="validation"/>
##### Validation
The consistency of this content structure both on creation and modification is
-asserted by a dedicated `TokenValidator`. The corresponding error are
+asserted by a dedicated `CugValidatorProvider`. The corresponding error are
all of type `AccessControl` with the following codes:
| Code | Message |
@@ -50,22 +66,25 @@ all of type `AccessControl` with the fol
| 0022 | Access controlled not not of mixin 'rep:CugMixin' |
| 0023 | Wrong name of node with primary type 'rep:CugPolicy' |
+<a name="configuration"/>
### Configuration
-_todo_
-
#### Configuration Parameters
-_todo_
-
+The implementation supports the following configuration parameters:
-#### Examples
-
-_todo_
+| Parameter | Type | Default | Description |
+|-----------------------------|----------------|----------|-------------|
+| `PARAM_CUG_ENABLED` | boolean | false | Flag to enable evaluation of CUG policies upon read-access. |
+| `PARAM_CUG_SUPPORTED_PATHS` | Set\<String\> | \- | Paths under which CUGs can be created and will be evaluated. |
+| `PARAM_RANKING` | int | 200 | Ranking within the composite authorization setup. |
+| | | | |
+<a name="pluggability"/>
### Pluggability
-_todo_
+_todo: deploying cug-authorization in an oak repository_
+_todo: customize cug-authorization by providing custom CugExclude implementation_
##### Examples
Copied: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/restriction.md (from r1728531, jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/restriction.md)
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/restriction.md?p2=jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/restriction.md&p1=jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/restriction.md&r1=1728531&r2=1729662&rev=1729662&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/restriction.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/restriction.md Wed Feb 10 17:12:26 2016
@@ -66,7 +66,7 @@ to read and create entries with restrict
- `getRestriction(String restrictionName)`: returns the restriction as JCR value.
- `getRestrictions(String restrictionName)`: returns the restriction as array of JCR values (since Oak 1.0, Jackrabbit API 2.8).
-
+<a name="api_extensions"/>
### Oak Restriction API
The following public interfaces are provided by Oak in the package `org.apache.jackrabbit.oak.spi.security.authorization.restriction`:
@@ -83,7 +83,7 @@ Oak 1.0 provides the following base impl
- `AbstractRestrictionProvider`: abstract base implementation of the provider interface.
- `RestrictionDefinitionImpl`: default implementation of the `RestrictionDefinition` interface.
- `RestrictionImpl`: default implementation of the `Restriction` interface.
-- `CompositeRestrictionProvider`: Allows to aggregate multiple provider implementations.
+- `CompositeRestrictionProvider`: Allows to aggregate multiple provider implementations (see [Pluggability](#pluggability) below).
- `CompositePattern`: Allows to aggregate multiple restriction patterns.
#### Changes wrt Jackrabbit 2.x
@@ -92,19 +92,23 @@ Apart from the fact that the internal Ja
a public API, the restriction implementation in Oak differs from Jackrabbit 2.x
as follows:
-- supports multi-valued restrictions
-- validation of the restrictions is delegated to a dedicated commit hook
-- restriction `rep:glob` limits the number of wildcard characters to 20
-- new restrictions `rep:ntNames`, `rep:prefixes` and `rep:itemNames`
-
+- 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"
+ - backwards compatible behavior for restrictions stored underneath the ACE node directly
+- Support for multi-valued restrictions (see [JCR-3637](https://issues.apache.org/jira/browse/JCR-3637), [JCR-3641](https://issues.apache.org/jira/browse/JCR-3641))
+- Validation of the restrictions is delegated to a dedicated commit hook
+- Restriction `rep:glob` limits the number of wildcard characters to 20
+- New restrictions `rep:ntNames`, `rep:prefixes` and `rep:itemNames`
+
#### Built-in Restrictions
The default implementations of the `Restriction` interface are present with
Oak 1.0 access control management:
* `rep:glob`: single name, path or path pattern with '*' wildcard(s).
-* `rep:ntNames`: multivalued restriction for primary node type names (no inheritence, since Oak 1.0)
-* `rep:prefixes`: multivalued restriction for namespace prefixes (session level remapping not respected, since Oak 1.0)
+* `rep:ntNames`: multivalued restriction to limit the affected ACE to nodes of the specified primary node type(s) (no nt inheritence, since Oak 1.0)
+* `rep:prefixes`: multivalued restriction to limit the effect to item names that match the specified namespace prefixes (session level remapping not respected, since Oak 1.0)
* `rep:itemNames`: multivalued restriction for property or node names (since Oak 1.3.8)
##### Examples
@@ -132,6 +136,30 @@ values of `rep:glob`.
| \*cat/\* | all descendants of /foo that have an intermediate segment ending with 'cat' |
+### Representation in the Repository
+
+All restrictions defined by default in a Oak repository are stored as properties
+in a dedicated `rep:restriction` child node of the target access control entry node.
+Similarly, they are represented with the corresponding permission entry.
+The node type definition used to represent restriction content is as follows:
+
+ [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 /* since oak 1.0 */
+
+ /**
+ * @since oak 1.0
+ */
+ [rep:Restrictions]
+ - * (UNDEFINED) protected
+ - * (UNDEFINED) protected multiple
+
+
+<a name="pluggability"/>
### Pluggability
The default security setup as present with Oak 1.0 is able to provide custom