Author: angela
Date: Wed Apr 6 07:42:18 2016
New Revision: 1737932
URL: http://svn.apache.org/viewvc?rev=1737932&view=rev
Log:
minor improvement: security documentation
Added:
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission/permissionsandprivileges.md
Modified:
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/editing.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission.md
Modified:
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/editing.md
URL:
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/editing.md?rev=1737932&r1=1737931&r2=1737932&view=diff
==============================================================================
---
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/editing.md
(original)
+++
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/editing.md
Wed Apr 6 07:42:18 2016
@@ -47,6 +47,10 @@ principals is actually allowed to perfor
use `Session.hasPermission(String, String)` and either pass the actions strings
defined by JCR or the names of the Oak permissions.
+See section [Permissions vs
Privileges](../permission/permissionsandprivileges.html) for an
+comprehensive overview on the differences between testing permissions on
`Session`
+and privileges on `AccessControlManager`.
+
#### Reading Policies
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission.md
URL:
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission.md?rev=1737932&r1=1737931&r2=1737932&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission.md
(original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission.md Wed
Apr 6 07:42:18 2016
@@ -44,6 +44,9 @@ The actions are expected to be a comma s
**Note**: As of Oak 1.0 the these methods also handle the names of the
permissions
defined by Oak (see `Permissions#getString(long permissions)`).
+See also section [Permissions vs
Privileges](permission/permissionsandprivileges.html) for
+a comparison of these permission checks and testing privileges on the
`AccessControlManager`.
+
##### Examples
###### Test if session has permission to add a new node
@@ -283,6 +286,7 @@ The supported configuration options of t
<a name="further_reading"/>
### Further Reading
+- [Permissions vs Privileges](permission/permissionsandprivileges.html)
- [Differences wrt Jackrabbit 2.x](permission/differences.html)
- [Permissions : The Default Implementation](permission/default.html)
- [Permission Evaluation in Detail](permission/evaluation.html)
Added:
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission/permissionsandprivileges.md
URL:
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission/permissionsandprivileges.md?rev=1737932&view=auto
==============================================================================
---
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission/permissionsandprivileges.md
(added)
+++
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/permission/permissionsandprivileges.md
Wed Apr 6 07:42:18 2016
@@ -0,0 +1,95 @@
+<!--
+ 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.
+-->
+
+Permissions vs Privileges
+--------------------------------------------------------------------------------
+
+### General Notes
+
+Usually it is not required for a application to check the
privileges/permissions
+of a given session (or set of principals) as this evaluation can be left
+to the repository.
+
+For rare cases where the application needs to understand if a given session is
+actually allowed to perform a given action, it is recommend to use
`Session.hasPermission(String, String)`.
+
+In order to test permissions that are not reflected in the action constants
+defined on `Session` or `JackrabbitSession`, the default implementation also
allows
+to pass the names of the Oak internal permission.
+
+Alternatively, `AccessControlManager.hasPrivileges(String, Privilege[])` can
be used.
+
+The subtle differences between the permission-testing `Session` and the
evaluation
+of privileges on `AccessControlManager` are listed below.
+
+### Testing Permissions
+
+#### Variants
+
+- `Session.hasPermission(String absPath, String actions)`
+- `Session.checkPermission(String absPath, String actions)`
+
+Where
+
+- `absPath` is an absolute path pointing to an existing or non-existing item
(node or property)
+- `actions` defines a comma-separated string of the actions defined on
`Session` and `JackrabbitSession`.
+ With the default implementation also Oak internal permission names are
allowed ( _Note:_ permission names != privilege names)
+
+#### Characteristics
+
+- API call always supported even if access control management is not part of
the feature set (see corresponding repository descriptor).
+- _Note:_ `ACTION_ADD_NODE` is evaluating if the node at the specified absPath
can be added; i.e. the path points to the non-existing node you want to add
+- Not possible to evaluate custom privileges with this method as those are not
respected by the default permission evaluation.
+- Restrictions will be respected as possible with the given (limited)
information
+
+
+### Testing Privileges
+
+#### Variants
+
+- `AccessControlManager.hasPrivileges(String absPath, Privilege[] privileges)`
+- `AccessControlManager.getPrivileges(String absPath)`
+
+Where
+
+- `absPath` must point to an existing Node (i.e. existing and accessible to
the editing session)
+- `privileges` represent an array of supported privileges (see corresponding
API calls)
+
+For testing purpose the Jackrabbit extension further allows to verify the
privileges
+granted to a given combination of principals, which may or may not reflect the
actual
+principal-set assigned to a given `Subject`. These calls (see below) however
+requires the ability to read access control content on the target path.
+
+- `JackrabbitAccessControlManager.hasPrivileges(String absPath, Set<Principal>
principals, Privilege[] privileges)`
+- `JackrabbitAccessControlManager.getPrivileges(String absPath, Set<Principal>
principals)`
+
+#### Characteristics
+
+- Only available if access control management is part of the supported feature
set of the JCR repository.
+- Built-in and/or custom privileges can be tested
+- `jcr:addChildNode` evaluates if any child can be added at the parent node
identify by the specified absPath. The name of child is not known here!
+- Restrictions may or may not be respected
+- Default implementation close to real permission evaluation (not exactly
following the specification)
+
+<a name="further_reading"/>
+### Further Reading
+
+- [Mapping Privileges to Items](../privilege/mappingtoitems.html)
+- [Mapping API Calls to Privileges](../privilege/mappingtoprivileges.html)
+
+
+
