Author: angela
Date: Thu Apr 21 08:21:03 2016
New Revision: 1740250
URL: http://svn.apache.org/viewvc?rev=1740250&view=rev
Log:
OAK-3211 : Document External Identity Management (WIP)
Added:
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/defaultusersync.md
Modified:
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/externalloginmodule.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/usersync.md
Added:
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/defaultusersync.md
URL:
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/defaultusersync.md?rev=1740250&view=auto
==============================================================================
---
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/defaultusersync.md
(added)
+++
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/defaultusersync.md
Thu Apr 21 08:21:03 2016
@@ -0,0 +1,59 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+User and Group Synchronization : The Default Implementation
+--------------------------------------------------------------------------------
+
+### DefaultSyncHandler
+
+The [DefaultSyncHandler] comes with a set of configuration options that
+allow to specify the synchronization behavior (see below). All users/groups
+synchronized by this handler will get the following properties set.
+
+These properties allow to run separate task for periodical update and make sure
+the authorizables can later on be identified as external users.
+
+- `rep:externalId` : This allows to identify the external users, know the
associated IDP and distinguish them from others.
+- `rep:lastSynced` : Sync timestamp to mark the external user/group valid for
the configurable time (to reduce expensive syncing). Once expired, they will be
validated against the 3rd party system again.
+
+
+<a name="configuration"/>
+### Configuration
+
+#### Configuration of the DefaultSyncHandler
+
+The default `SyncHandler` implementation is configured via [DefaultSyncConfig]:
+
+| Name | Property | Description
|
+|-------------------------------|-------------------------------|------------------------------------------|
+| Sync Handler Name | `handler.name` | Name of this
sync configuration. This is used to reference this handler by the login
modules. |
+| User auto membership | `user.autoMembership` | List of
groups that a synced user is added to automatically |
+| User Expiration Time | `user.expirationTime` | Duration
until a synced user gets expired (eg. '1h 30m' or '1d'). |
+| User Membership Expiration | `user.membershipExpTime` | Time after
which membership expires (eg. '1h 30m' or '1d'). |
+| User membership nesting depth | `user.membershipNestingDepth` | Returns the
maximum depth of group nesting when membership relations are synced. A value of
0 effectively disables group membership lookup. A value of 1 only adds the
direct groups of a user. This value has no effect when syncing individual
groups only when syncing a users membership ancestry. |
+| User Path Prefix | `user.pathPrefix` | The path
prefix used when creating new users. |
+| User property mapping | `user.propertyMapping` | List mapping
definition of local properties from external ones. eg: 'profile/email=mail'.Use
double quotes for fixed values. eg: 'profile/nt:primaryType="nt:unstructured" |
+| Group auto membership | `group.autoMembership` | List of
groups that a synced group is added to automatically |
+| Group Expiration Time | `group.expirationTime` | Duration
until a synced group expires (eg. '1h 30m' or '1d'). |
+| Group Path Prefix | `group.pathPrefix` | The path
prefix used when creating new groups. |
+| Group property mapping | `group.propertyMapping` | List mapping
definition of local properties from external ones. |
+| | | |
+
+
+<!-- references -->
+[DefaultSyncHandler]:
/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/impl/DefaultSyncHandler.html
+[DefaultSyncConfig]:
/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/impl/DefaultSyncConfig.html
Modified:
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/externalloginmodule.md
URL:
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/externalloginmodule.md?rev=1740250&r1=1740249&r2=1740250&view=diff
==============================================================================
---
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/externalloginmodule.md
(original)
+++
jackrabbit/oak/trunk/oak-doc/src/site/markdown/security/authentication/externalloginmodule.md
Thu Apr 21 08:21:03 2016
@@ -63,10 +63,8 @@ If a user needs re-authentication (for e
if the user is not yet present in the local system at all), the login module
must
check the credentials with the external system during the `login()` method.
-Note:
-
-* users (and groups) that are synced from the 3rd party system contain a
`rep:externalId` property. This allows to identify the external users and
distinguish them from others.
-* to reduce expensive syncing, the synced users and groups have sync timestamp
`rep:lastSynced` and are considered valid for a configurable time. if they
expire, they need to be validated against the 3rd party system again.
+The details of the default user/group synchronization mechanism are described
in section
+[User and Group Synchronization : The Default
Implementation](defaultusersync.html)
##### Supported Credentials
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=1740250&r1=1740249&r2=1740250&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
Thu Apr 21 08:21:03 2016
@@ -24,9 +24,6 @@ The synchronization of users and groups
after a user is successfully authenticated against the IDP or if it's no longer
present on the IDP.
-Oak comes with a default implementation of the `SyncHandler` interface:
-[org.apache.jackrabbit.oak.spi.security.authentication.external.impl.DefaultSyncHandler].
-
### Synchronization API
- [SyncManager]: factory for all configured `SyncHandler` implementations.
@@ -52,39 +49,9 @@ for the following tasks:
### Default Implementation
Oak 1.0 provides a default implementation of the user synchronization API that
allow
-to plug additional `SyncHandler` implementations.
-
-The [DefaultSyncHandler] itself comes with a set of configuration options that
-allow to specify the synchronization behavior (see below). All users/groups
-synchronized by this handler will get the following properties set:
-
-- `rep:externalId`
-- `rep:lastSynced`
-
-These properties allow to run separat task for periodical update and make sure
-the authorizables can later on be identitied as external users.
-
-### Configuration
-
-#### Configuration of the DefaultSyncHandler
-
-The default sync handler implementation is configured via [DefaultSyncConfig]:
-
-| Name | Property | Description
|
-|-------------------------------|-------------------------------|------------------------------------------|
-| Sync Handler Name | `handler.name` | Name of this
sync configuration. This is used to reference this handler by the login
modules. |
-| User auto membership | `user.autoMembership` | List of
groups that a synced user is added to automatically |
-| User Expiration Time | `user.expirationTime` | Duration
until a synced user gets expired (eg. '1h 30m' or '1d'). |
-| User Membership Expiration | `user.membershipExpTime` | Time after
which membership expires (eg. '1h 30m' or '1d'). |
-| User membership nesting depth | `user.membershipNestingDepth` | Returns the
maximum depth of group nesting when membership relations are synced. A value of
0 effectively disables group membership lookup. A value of 1 only adds the
direct groups of a user. This value has no effect when syncing individual
groups only when syncing a users membership ancestry. |
-| User Path Prefix | `user.pathPrefix` | The path
prefix used when creating new users. |
-| User property mapping | `user.propertyMapping` | List mapping
definition of local properties from external ones. eg: 'profile/email=mail'.Use
double quotes for fixed values. eg: 'profile/nt:primaryType="nt:unstructured" |
-| Group auto membership | `group.autoMembership` | List of
groups that a synced group is added to automatically |
-| Group Expiration Time | `group.expirationTime` | Duration
until a synced group expires (eg. '1h 30m' or '1d'). |
-| Group Path Prefix | `group.pathPrefix` | The path
prefix used when creating new groups. |
-| Group property mapping | `group.propertyMapping` | List mapping
definition of local properties from external ones. |
-| | | |
+to plug additional `SyncHandler` implementations.
+Default implementation is described in section [User and Group Synchronization
: The Default Implementation](defaultusersync.html).
### Pluggability
@@ -110,5 +77,3 @@ or plug a new implementation of the `Syn
[SyncedIdentity]:
/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/SyncedIdentity.html
[SyncResult]:
/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/SyncResult.html
[SyncException]:
/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/SyncException.html
-[DefaultSyncHandler]:
/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/impl/DefaultSyncHandler.html
-[DefaultSyncConfig]:
/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/impl/DefaultSyncConfig.html
