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/16 18:08:45 UTC
svn commit: r1730718 - in
/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security:
accesscontrol/editing.md authorization.md authorization/composite.md
overview.md
Author: angela
Date: Tue Feb 16 17:08:45 2016
New Revision: 1730718
URL: http://svn.apache.org/viewvc?rev=1730718&view=rev
Log:
OAK-4016 : Document composite authorization setup
minor improvement: security doc, ac editing section
Modified:
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/accesscontrol/editing.md
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/overview.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=1730718&r1=1730717&r2=1730718&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 Tue Feb 16 17:08:45 2016
@@ -81,7 +81,9 @@ defined by JCR or the names of the Oak p
- `getRestrictionType(String)`
- `isEmpty()`
- `size()`
-
+
+- `PrincipalSetPolicy`
+ - `getPrincipals()`
#### Reading Effective Policies
@@ -92,7 +94,6 @@ defined by JCR or the names of the Oak p
- `JackrabbitAccessControlManager`
- `getEffectivePolicies(Set<Principal>)`
-
### Writing
#### Adding Policies
@@ -123,14 +124,16 @@ the access control implementation there
- `addAccessControlEntry(Principal, Privilege[])`
- `removeAccessControlEntry(AccessControlEntry)`
-
- `JackrabbitAccessControlList`
- `addAccessControlEntry(Principal, Privilege[], boolean)`
- `addAccessControlEntry(Principal, Privilege[], boolean, Map<String, Value>)`
- `addAccessControlEntry(Principal, Privilege[], boolean, Map<String, Value>, Map<String, Value[]>)`
- `orderBefore(AccessControlEntry, AccessControlEntry)`
-
+- `PrincipalSetPolicy`
+ - `addPrincipals(Principal...)`
+ - `removePrincipals(Principal...)`
+
- `AccessControlUtils`
- `getAccessControlList(Session, String)`
- `getAccessControlList(AccessControlManager, String)`
@@ -141,31 +144,39 @@ the access control implementation there
##### Retrieve Principals
+The default and recommended ways to obtain `Principal`s for access control management
+is through the principal management API:
+
- `PrincipalManager` (see section [Principal Management](../principal.html))
- `getPrincipal(String)`
- `getPrivilege(String)`
+One way of representing principals in the repository is by the means of user management:
+If user management is supported in a given Oak repository (see [OPTION_USER_MANAGEMENT_SUPPORTED]
+repository descriptor), principals associated with a given user/group can be obtained
+by calling:
- `Authorizable` (see section [User Management](../user.html))
- `getPrincipal()`
-
+
+Note however, that this will only work for principals backed by a user/group.
+Principals provided by a different principal management implementation won't be
+accessible through user management.
+
##### Retrieve Privileges
- `PrivilegeManager` (see section [Privilege Management](../privilege.html))
- `getRegisteredPrivileges()`
- `getPrivilege(String)`
-
- `AccessControlManager`
- `getSupportedPrivileges(String)`
- `privilegeFromName(String)`
-
- `AccessControlUtils`
- `privilegesFromNames(Session session, String... privilegeNames)`
- `privilegesFromNames(AccessControlManager accessControlManager, String... privilegeNames)`
-
- `Privilege`: defines name constants for the privileges defined by JCR
##### Examples
@@ -235,8 +246,6 @@ or alternatively use `AccessControlUtils
session.save();
}
-
-
#### Removing Policies
- `AccessControlManager`
@@ -270,3 +279,5 @@ or alternatively use `AccessControlUtils
session.save();
}
+<!-- hidden references -->
+[OPTION_USER_MANAGEMENT_SUPPORTED]: http://svn.apache.org/repos/asf/jackrabbit/trunk/jackrabbit-api/src/main/java/org/apache/jackrabbit/api/JackrabbitRepository.java
Modified: 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=1730718&r1=1730717&r2=1730718&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization.md Tue Feb 16 17:08:45 2016
@@ -99,6 +99,13 @@ restriction management that allows to na
items matching a given, defined behavior. Details can be found in section
[RestrictionManagement](authorization/restriction.html#pluggability).
+<a name="further_reading"/>
+### Further Reading
+
+- [Access Control Management](accesscontrol.html)
+- [Permission Evalution](permission.html)
+- [Combining Multiple Authorization Models](authorization/composite.html)
+
<!-- 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
Modified: 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=1730718&r1=1730717&r2=1730718&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/composite.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authorization/composite.md Tue Feb 16 17:08:45 2016
@@ -26,8 +26,7 @@ default security setup.
The main entry point for the aggregation of multiple authorization models is the
[CompositeAuthorizationConfiguration], which is in charge of generating composite
variants of the `AccessControlManager`, `PermissionProvider` and `RestrictionProvider`
-if multiple authorization modules have been configured (see section
-[Implementation Details](#details) below.
+if multiple authorization modules have been configured (see section [Implementation Details](#details) below.
_Please note:_
Despite the fact that Oak supports the aggregation of multiple authorization
@@ -56,7 +55,7 @@ can be found for the given type of polic
#### AggregatedPermissionProvider
Extension of the `PermissionProvider` interface that allows a given provider to
-be deployed in a composite authorization setup. The additional methods allow the
+be deployed in a composite authorization setup. The additional methods allow the
aggregating provider to identify if a given `PermissionProvider` can handle permission
evaluation for a given set of permissions at a given path.
@@ -74,13 +73,61 @@ permissions and move on to other provide
<a name="details"/>
### Implementation Details
+As soon as multiple authorization models are configured with the security setup,
+the `CompositeAuthorizationConfiguration` will return a dedicated `JackrabbitAccessControlManager`
+and `PermissionProvider` that are wrapping the objects provided by the aggregated
+implementations.
+
+Note: as long as a single authorization model is configured (default setup) the
+`CompositeAuthorizationConfiguration` will omit any extra wrapping.
+
#### Access Control
-_TODO_
+Once multiple modules are deployed a [CompositeAccessControlManager] with the following
+characteristics will be returned:
+
+- API calls reading information will return the combined result of the wrapped implementations.
+- Methods defined solely by `JackrabbitAccessControlManager` additionally test for the delegatees to implement that extentions.
+- API calls writing back policies will look for the responsible `PolicyOwner` and specifically delegate the call. If no owner can be found an `AccessControlException` is thrown.
+
+Hence, a given authorization model is free to implement JCR `AccessControlManager`
+or the Jackrabbit extension.
+
+If a given model allows for writing access control policies, the access control manager
+implementation must additionally implement the `PolicyOwner` interface as explained in
+section [API Extensions](#api_extensions) above.
#### Permission Evaluation
-_TODO_
+Only models implementing the `AggregatedPermissionProvider` extensions will be
+respected for aggregation into the [CompositePermissionProvider]. This allows
+individual models to cover only a subset of permissions and|or a subset of paths
+within the repository.
+
+The composite wrapper subsequently applies the following logic to evaluate the
+effective permissions:
+
+- each delegatee is in ask to evaluate the subset of supported permissions if it
+ claims responsible for the given item/path,
+- a delegatee that doesn't handle any of the permissions in question it is ignored,
+- a delegatee that doesn't claim responsible for the item/path is ignored,
+- a given set of permissions is ultimately granted for a given item/path, if _all_
+ permissions have been successfully processed and none of the delegatees involved
+ denied access.
+
+This implies that evalution of permissions across multiple implementations is
+strictly additive: as soon as one provider denies access (either by an explicit
+deny or by a missing explicit allow) permissions are denied.
+
+Similarly, if a given combination of permission providers fails to process the
+complete set of permissions (e.g. one permission is not covered by any of the modules)
+the access will be denied as none of the provider was in charge of proper evaluation.
+
+For a given permission provider this means: Calling the same method outside of
+the context of the aggregation (i.e. single model setup), a 'limited' provider must
+never grant access for permissions or items it isn't able to handle properly.
+In other words: permissions that have not been explicitly granted within the scope
+of an implemenation must be denied.
#### Restriction Management
@@ -94,10 +141,9 @@ set of restrictions in order to meet the
Nevertheless, each authorization model is responsible for exposing, validating and
evaluating the subset of restrictions it can handle through the access control API
-extensions and the permission evaluation, respectively. Similarly, a given module
-may decide to provide no support for restrictions. Examples include modules that
-provide different types of `AccessControlPolicy` where restrictions cannot be applied
-(see for example [oak-authorization-cug](cug.html#details)).
+extensions and the permission evaluation, respectively. A given model may decide to
+provide no support for restrictions. Examples include modules that deal with different
+types of `AccessControlPolicy` where restriction management doesn't apply (see for example [oak-authorization-cug](cug.html#details)).
<a name="configuration"/>
### Configuration
@@ -108,9 +154,28 @@ the `CompositeAuthorizationConfiguration
<a name="pluggability"/>
### Pluggability
-_TODO_
+The following steps are required to plug an additional authorization model into
+the Oak repository:
+- Implement your custom `AuthorizationConfiguration`
+- Deploy the bundle containing the implemenation
+- Bind your `AuthorizationConfiguration` to the `SecurityProvider`:
+ - in an OSGi setup this is achieved by adding the configuration to the
+ `requiredServicePids` property of the `SecurityProviderRegistration` _("Apache Jackrabbit Oak SecurityProvider")_
+ i.e. forcing the recreation of the `SecurityProvider`.
+ - in a non-OSGi setup this requires adding the configuration
+ to the `SecurityProvider` (e.g. _SecurityProviderImpl.bindAuthorizationConfiguration_)
+ and subsequently creating the JCR/Oak repository object.
+
+**Important Note**
+Despite the fact that Oak supports the aggregation of multiple authorization
+models, this extension is only recommended for experts that have in-depth
+knowledge and understanding of Jackrabbit/Oak authorization concepts. Doing so
+might otherwise result in severe security issues and heavily impact overall performance.
+
<!-- hidden references -->
[PolicyOwner]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/accesscontrol/PolicyOwner.html
[AggregatedPermissionProvider]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/permission/AggregatedPermissionProvider.html
-[CompositeAuthorizationConfiguration]: /oak/docs/apidocs/org/apache/jackrabbit/oak/security/authorization/composite/CompositeAuthorizationConfiguration.html
\ No newline at end of file
+[CompositeAuthorizationConfiguration]: /oak/docs/apidocs/org/apache/jackrabbit/oak/security/authorization/composite/CompositeAuthorizationConfiguration.html
+[CompositeAccessControlManager]: /oak/docs/apidocs/org/apache/jackrabbit/oak/security/authorization/composite/CompositeAccessControlManager.html
+[CompositePermissionProvider]: /oak/docs/apidocs/org/apache/jackrabbit/oak/security/authorization/composite/CompositePermissionProvider.html
\ No newline at end of file
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/overview.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/overview.md?rev=1730718&r1=1730717&r2=1730718&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/overview.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/overview.md Tue Feb 16 17:08:45 2016
@@ -40,6 +40,9 @@ The Oak Security Layer
### Authorization
* [Overview](authorization.html)
+ * [Access Control Management](accesscontrol.html)
+ * [Permission Evalution](permission.html)
+ * [Combining Multiple Authorization Models](authorization/composite.html)
#### Access Control Management