Mailing-List: contact oak-commits-help@jackrabbit.apache.org; run by ezmlm
Precedence: bulk
Reply-To: oak-dev@jackrabbit.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1593418 - in /jackrabbit/oak/branches/1.0: ./ oak-doc/
 oak-doc/src/site/markdown/security/
 oak-doc/src/site/markdown/security/principal/
 oak-doc/src/site/markdown/security/user/
Date: Thu, 08 May 2014 21:03:31 -0000
To: oak-commits@jackrabbit.apache.org
From: mduerig@apache.org
Message-Id: <20140508210331.D8C5A2388994@eris.apache.org>

Author: mduerig
Date: Thu May  8 21:03:31 2014
New Revision: 1593418

URL: http://svn.apache.org/r1593418
Log:
OAK-301: oak docu
Merged r1593342

Modified:
    jackrabbit/oak/branches/1.0/   (props changed)
    jackrabbit/oak/branches/1.0/oak-doc/   (props changed)
    jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/principal.md
    jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/principal/differences.md
    jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/user/membership.md
    jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/user/query.md

Propchange: jackrabbit/oak/branches/1.0/
------------------------------------------------------------------------------
  Merged /jackrabbit/oak/trunk:r1593342

Propchange: jackrabbit/oak/branches/1.0/oak-doc/
------------------------------------------------------------------------------
  Merged /jackrabbit/oak/trunk/oak-doc:r1593342

Modified: jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/principal.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/principal.md?rev=1593418&r1=1593417&r2=1593418&view=diff
==============================================================================
--- jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/principal.md (original)
+++ jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/principal.md Thu May  8 21:03:31 2014
@@ -38,6 +38,8 @@ This interface replaces the internal `Pr
 Jackrabbit 2.x. Note, that principals from different sources can be supported by
 using [CompositePrincipalProvider] or a similar implementation that proxies
 different sources.
+- [CompositePrincipalProvider]: Implementation that combines different principals
+from different source providers.
 
 ##### Special Principals
 - [AdminPrincipal]: Marker interface to identify the principal associated with administrative user(s).
@@ -51,11 +53,79 @@ The [PrincipalConfiguration] is the Oak 
 options. The default implementation of the [PrincipalManager] interface is based
 on Oak API and can equally be used for privilege related tasks in the Oak layer.
 
-Note, that in contrast to Jackrabbit 2.x the system may only have one single principal
+In contrast to Jackrabbit 2.x the system may only have one single principal
 provider implementation configured. In order to combine principals from different
 sources a implementation that properly handles the different sources is required;
 the [CompositePrincipalProvider] is an example that combines multiple implementations.
 
+### Pluggability
+
+The default security setup as present with Oak 1.0 is able to track custom
+`PrincipalConfiguration` implementations and will automatically combine the different
+principal provider implementations as noted above.
+
+In an OSGi setup the following steps are required in order to add a custom principal
+provider implementation:
+
+- implement `PrincipalProvider` interface
+- create the `PrincipalConfiguration` that exposes the custom provider
+- make the configuration implementation an OSGi service and make it available to the Oak repository.
+
+#### Examples
+
+##### Custom PrincipalConfiguration
+
+     @Component()
+     @Service({PrincipalConfiguration.class, SecurityConfiguration.class})
+     public class MyPrincipalConfiguration extends ConfigurationBase implements PrincipalConfiguration {
+
+         public MyPrincipalConfiguration() {
+             super();
+         }
+
+         public MyPrincipalConfiguration(SecurityProvider securityProvider) {
+             super(securityProvider, securityProvider.getParameters(NAME));
+         }
+
+         @Activate
+         private void activate(Map<String, Object> properties) {
+             setParameters(ConfigurationParameters.of(properties));
+         }
+
+
+         //---------------------------------------------< PrincipalConfiguration >---
+         @Nonnull
+         @Override
+         public PrincipalManager getPrincipalManager(Root root, NamePathMapper namePathMapper) {
+             PrincipalProvider principalProvider = getPrincipalProvider(root, namePathMapper);
+             return new PrincipalManagerImpl(principalProvider);
+         }
+
+         @Nonnull
+         @Override
+         public PrincipalProvider getPrincipalProvider(Root root, NamePathMapper namePathMapper) {
+             return new MyPrincipalProvider(root, namePathMapper);
+         }
+
+         //----------------------------------------------< SecurityConfiguration >---
+         @Nonnull
+         @Override
+         public String getName() {
+             return NAME;
+         }
+     }
+
+##### Custom PrincipalProvider
+
+     final class MyPrincipalProvider implements PrincipalProvider {
+
+         MyPrincipalProvider(Root root, NamePathMapper namePathMapper) {
+              ...
+         }
+
+         ...
+     }
+
 <!-- references -->
 
 [PrincipalManager]: http://svn.apache.org/repos/asf/jackrabbit/trunk/jackrabbit-api/src/main/java/org/apache/jackrabbit/api/security/principal/PrincipalManager.java

Modified: jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/principal/differences.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/principal/differences.md?rev=1593418&r1=1593417&r2=1593418&view=diff
==============================================================================
--- jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/principal/differences.md (original)
+++ jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/principal/differences.md Thu May  8 21:03:31 2014
@@ -33,8 +33,7 @@ order to combine principals from differe
 handles the different sources is required; the [CompositePrincipalProvider] is an
 example that combines multiple implementations.
 
-NOTE: see [OAK-1798] for an improvement to ease pluggability of custom `PrincipalProvider`
-implementations.
+See [Principal Management](../principal.html) for an example.
 
 <!-- references -->
 
@@ -43,4 +42,3 @@ implementations.
 [org.apache.jackrabbit.oak.spi.security.principal.AdminPrincipal]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/principal/AdminPrincipal.html
 [org.apache.jackrabbit.oak.spi.security.principal.EveryonePrincipal]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/principal/EveryonePrincipal.html
 [org.apache.jackrabbit.oak.spi.security.principal.SystemPrincipal]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/principal/SystemPrincipal.html
-[OAK-1798]: https://issues.apache.org/jira/browse/OAK-1798

Modified: jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/user/membership.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/user/membership.md?rev=1593418&r1=1593417&r2=1593418&view=diff
==============================================================================
--- jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/user/membership.md (original)
+++ jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/user/membership.md Thu May  8 21:03:31 2014
@@ -105,7 +105,7 @@ will limit the size of the multi value p
 implementation detail and might even vary depending on the underlying persistence layer.
 In Oak 1.0 the threshold value is set to 100.
 
-#### Upgrading Groups from Jackrabbit 2.x to OAK content structure
+#### Upgrading Groups from Jackrabbit 2.x to Oak content structure
 
 Upon upgrade from a Jackrabbit 2.x repository to OAK the group member lists that
 adjusted to reflect the new content structure as created by the OAK user management

Modified: jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/user/query.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/user/query.md?rev=1593418&r1=1593417&r2=1593418&view=diff
==============================================================================
--- jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/user/query.md (original)
+++ jackrabbit/oak/branches/1.0/oak-doc/src/site/markdown/security/user/query.md Thu May  8 21:03:31 2014
@@ -41,6 +41,7 @@ _todo_
 
 - simple search by property
 - query api
+- examples
 
 
 ### Characteristics of the Default Implementation