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 Principals (see section User Management below).

Note: as a further improvement the PrincipalNameResolver interface was introduced in Oak 1.6.1 to allow for optimized resolution of a principal names from a given ExternalIdentityRef. In order to benefit from that shortcut a given implementation of ExternalIdentityProvider needs to also implement PrincipalNameResolver. See also OAK-5210.

Automatic Membership

• If enabled automatic membership assignment for existing, local groups will not longer be written to the repository
• Instead the ExternalPrincipalConfiguration (“Apache Jackrabbit Oak External PrincipalConfiguration”) will keep track of the mapping between registered SyncHandlers (i.e. auto-membership configuration) and ExternalIdentityProviders. 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 Principals 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.
• Note, that in the initial version (Oak 1.6) only the user.autoMembership configuration is respected (see also OAK-5194 and OAK-5195)

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 and 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 Principals retrievable and searchable through the Jackrabbit principal management API (see section Principal Management 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 (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 (“Apache Jackrabbit Oak External PrincipalConfiguration”) is properly registered with the SecurityProvider (see section Configuration).

Authorization

The authorization modules shipped with Oak only depend on Principals (and not on user management functionality) and are therefore not affected by the dynamic membership configuration.