Index: oak-doc/src/site/markdown/security/authentication/defaultusersync.md =================================================================== --- oak-doc/src/site/markdown/security/authentication/defaultusersync.md (revision 1746238) +++ oak-doc/src/site/markdown/security/authentication/external/defaultusersync.md (revision ) @@ -84,81 +84,10 @@ As of Oak 1.5.3 the default sync handler comes with an addition configuration option that allows to enable dynamic group membership resolution for external users. Enabling dynamic membership in the [DefaultSyncConfig] will change the way external -groups are synchronized (see also [OAK-4101]). - +groups are synchronized (see also [OAK-4101]). + -The key benefits of dynamic membership resolution are: - -- avoiding duplicate user management effort wrt to membership handling both in the external IDP and the repository -- ease principal resolution upon repository login - -#### SyncContext with Dynamic Membership - -With the default `SyncHandler` this configuration option will show the following -effects: - -- If enabled the handler will use an alternative [SyncContext] to synchronize external groups. -- Instead of synchronizing groups into the user management, this [DynamicSyncContext] - will additionally set the property `rep:externalPrincipalNames` on the synchronized external user -- `rep:externalPrincipalNames` is a system maintained multivalued property of type - 'STRING' storing the names of the `java.security.acl.Group`-principals a given - external user is member of (both declared and inherited according to the configured - membership nesting depth) -- External groups will no longer be synchronised into the repository's user management - but will only be available as `Principal`s (see section _User Management_ below). - -#### Effect of Dynamic Membership on other Security Modules - -##### Principal Management - -The dynamic (principal) membership features comes with a dedicated `PrincipalConfiguration` -implementation (i.e. [ExternalPrincipalConfiguration]) that is in charge of securing -the `rep:externalPrincipalNames` properties (see also section [Validation](#validation) -and [Configuration](#configuration) below). - -Additionally the [ExternalPrincipalConfiguration] provides a `PrincipalProvider` -implementation which makes external (group) principals available to the repository's -authentication and authorization using the `rep:externalPrincipalNames` as a -persistent cache to avoid expensive lookup on the IDP. -This also makes external `Principal`s retrievable and searchable through the -Jackrabbit principal management API (see section [Principal Management](../principal.html) -for a comprehensive description). - -Please note the following implementation detail wrt accessibility of group principals: -A given external principal will be accessible though the principal management API -if it can be read from any of the `rep:externalPrincipalNames` properties -present using a dedicated query. - -##### User Management - -As described above the dynamic membership option will effectively disable the -synchronization of the complete external group account information into the repository's -user management feature but limit the synchronized information to the principal -names and the membership relation between a given `java.security.acl.Group` principal -and external user accounts. - -The user management API will consequently no longer be knowledgeable of external -group identities (exception: groups that have been synchronized before enabling -the feature will remain untouched and will be synchronized according to the -sync configuration). - -While this behavior does not affect default authentication and authorization modules -(see below) it will have an impact on applications that rely on full synchronization -of external identities. Those application won't be able to benefit from the dynamic -membership feature until dynamic groups can be created with the -Jackrabbit [User Management API](../user.html) (see [OAK-2687]). - -##### Authentication - -The authentication setup provided by Oak is not affected by the dynamic membership -handling as long as the configured `LoginModule` implementations rely on the -`PrincipalProvider` for principal resolution and the [ExternalPrincipalConfiguration] -is properly registered with the `SecurityProvider` (see section [Configuration](#configuration) below). - -##### Authorization - -The authorization modules shipped with Oak only depend on `Principal`s (and not on -user management functionality) and are therefore not affected by the dynamic -membership configuration. +The details and effects on other security related modules are described in +section [Dynamic Membership](dynamic.html). #### XML Import \ No newline at end of file Index: oak-doc/src/site/markdown/security/authentication/externalloginmodule.md IDEA additional info: Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP <+>UTF-8 =================================================================== --- oak-doc/src/site/markdown/security/authentication/externalloginmodule.md (revision 1746238) +++ oak-doc/src/site/markdown/security/authentication/externalloginmodule.md (revision ) @@ -64,7 +64,7 @@ check the credentials with the external system during the `login()` method. The details of the default user/group synchronization mechanism are described in section -[User and Group Synchronization : The Default Implementation](defaultusersync.html) +[User and Group Synchronization : The Default Implementation](external/defaultusersync.html) ##### Supported Credentials Index: oak-doc/src/site/markdown/security/authentication/external/dynamic.md IDEA additional info: Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP <+>UTF-8 =================================================================== --- oak-doc/src/site/markdown/security/authentication/external/dynamic.md (revision ) +++ oak-doc/src/site/markdown/security/authentication/external/dynamic.md (revision ) @@ -0,0 +1,135 @@ + + +User and Group Synchronization : Dynamic Membership +--------------------------------------------------- + +As of Oak 1.5.3 the default sync handler comes with an additional configuration +option (see section [Configuration](defaultusersync.html#configuration) +that allows to enable dynamic group membership resolution for external users. + +Enabling dynamic membership in the [DefaultSyncConfig] will change the way external +groups are synchronized (see [OAK-4101]) and how automatic group membership +is being handled (see [OAK-4087]) + +The key benefits of dynamic membership resolution are: + +- avoiding duplicate user management effort wrt to membership handling both in the external IDP and the repository +- avoid storing/updating auto-membership which is assigned to all external users +- ease principal resolution upon repository login + +#### SyncContext with Dynamic Membership + +With the default `SyncHandler` this configuration option will show the following +effects: + +##### External Groups + +- If enabled the handler will use an alternative [SyncContext] to synchronize external groups ([DynamicSyncContext]). +- Instead of synchronizing groups into the user management, this [DynamicSyncContext] + will additionally set the property `rep:externalPrincipalNames` on the synchronized external user +- `rep:externalPrincipalNames` is a system maintained multivalued property of type + 'STRING' storing the names of the `java.security.acl.Group`-principals a given + external user is member of (both declared and inherited according to the configured + membership nesting depth) +- External groups will no longer be synchronised into the repository's user management + but will only be available as `Principal`s (see section _User Management_ below). + +##### Automatic Membership + +- If enabled automatic membership assignment for existing, local groups will not longer be written to the repository +- Instead the [ExternalPrincipalConfiguration] will keep track of the mapping + between registered [SyncHandler]s (i.e. auto-membership configuration) and [ExternalIdentityProvider]s. + This allows to determine auto-membership based on the `rep:externalId` stored with the user accounts. +- The `PrincipalProvider` associated with this dedicated principal configuration + will expand the collection of `Principal`s generated for the following calls + with the automatically assigned principals: + - `PrincipalProvider.getGroupMembership(Principal)` + - `PrincipalProvider.getPrincipals(String)` +- Configured auto-membership groupIds that cannot be resolved to an existing + `o.a.j.api.security.user.Group` will be ignored in accordance to the default behavior. +- Consequently, the `PrincipalProvider` relies on other `PrincipalProvider` + implementations to _own_ these group principals and will not expose them + upon other calls (e.g. `PrincipalProvider.getPrincipal(String)`. +- Any changes to the auto-membership configuration will be immediately reflected + to new instances of the `PrincipalProvider`. + +#### Effect of Dynamic Membership on other Security Modules + +##### Principal Management + +The dynamic (principal) membership features comes with a dedicated `PrincipalConfiguration` +implementation (i.e. [ExternalPrincipalConfiguration]) that is in charge of securing +the `rep:externalPrincipalNames` properties (see also section [Validation](defaultusersync.html#validation) +and [Configuration](defaultusersync.html#configuration)). + +Additionally the [ExternalPrincipalConfiguration] provides a `PrincipalProvider` +implementation which makes external (group) principals available to the repository's +authentication and authorization using the `rep:externalPrincipalNames` as a +persistent cache to avoid expensive lookup on the IDP. +This also makes external `Principal`s retrievable and searchable through the +Jackrabbit principal management API (see section [Principal Management](../../principal.html) +for a comprehensive description). + +Please note the following implementation detail wrt accessibility of group principals: +A given external principal will be accessible though the principal management API +if it can be read from any of the `rep:externalPrincipalNames` properties +present using a dedicated query. + +##### User Management + +As described above the dynamic membership option will effectively disable the +synchronization of the complete external group account information into the repository's +user management feature but limit the synchronized information to the principal +names and the membership relation between a given `java.security.acl.Group` principal +and external user accounts. + +The user management API will consequently no longer be knowledgeable of external +group identities (exception: groups that have been synchronized before enabling +the feature will remain untouched and will be synchronized according to the +sync configuration). + +While this behavior does not affect default authentication and authorization modules +(see below) it will have an impact on applications that rely on full synchronization +of external identities. Those application won't be able to benefit from the dynamic +membership feature until dynamic groups can be created with the +Jackrabbit [User Management API](../../user.html) (see [OAK-2687]). + +##### Authentication + +The authentication setup provided by Oak is not affected by the dynamic membership +handling as long as the configured `LoginModule` implementations rely on the +`PrincipalProvider` for principal resolution and the [ExternalPrincipalConfiguration] +is properly registered with the `SecurityProvider` (see section [Configuration](defaultusersync.html#configuration)). + +##### Authorization + +The authorization modules shipped with Oak only depend on `Principal`s (and not on +user management functionality) and are therefore not affected by the dynamic +membership configuration. + + +[SyncHandler]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/SyncHandler.html +[SyncContext]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/SyncContext.html +[DefaultSyncContext]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/basic/DefaultSyncContext.html +[DefaultSyncConfig]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/basic/DefaultSyncConfig.html +[ExternalIdentityProvider]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/ExternalIdentityProvider.html +[ExternalPrincipalConfiguration]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/impl/principal/ExternalPrincipalConfiguration.html +[DynamicSyncContext]: /oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authentication/external/impl/principal/DynamicSyncContext.html +[OAK-4101]: https://issues.apache.org/jira/browse/OAK-4101 +[OAK-2687]: https://issues.apache.org/jira/browse/OAK-2687 +[OAK-4087]: https://issues.apache.org/jira/browse/OAK-4087 \ No newline at end of file Index: oak-doc/src/site/markdown/security/authentication/usersync.md IDEA additional info: Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP <+>UTF-8 =================================================================== --- oak-doc/src/site/markdown/security/authentication/usersync.md (revision 1746238) +++ oak-doc/src/site/markdown/security/authentication/usersync.md (revision ) @@ -51,7 +51,7 @@ Oak 1.0 provides a default implementation of the user synchronization API that allow to plug additional `SyncHandler` implementations. -Default implementation is described in section [User and Group Synchronization : The Default Implementation](defaultusersync.html). +Default implementation is described in section [User and Group Synchronization : The Default Implementation](external/defaultusersync.html). ### Pluggability Index: oak-doc/src/site/markdown/security/principal/principalprovider.md IDEA additional info: Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP <+>UTF-8 =================================================================== --- oak-doc/src/site/markdown/security/principal/principalprovider.md (revision 1746238) +++ oak-doc/src/site/markdown/security/principal/principalprovider.md (revision ) @@ -79,7 +79,7 @@ the names of these external principals are synchronized to based on a configurable expiration time. -See section [User and Group Synchronization : The Default Implementation](../authentication/defaultusersync.html) +See section [User and Group Synchronization : The Default Implementation](../authentication/external/defaultusersync.html) for additional details. Since Oak 1.5.3