Fork me on GitHub

User and Group Synchronization


The synchronization of users and groups is triggered by the ExternalLoginModule, after a user is successfully authenticated against the IDP or if it's no longer present on the IDP.

Synchronization API

  • SyncManager: factory for all configured SyncHandler implementations.
  • SyncHandler: responsible for synchronizing users/groups from an ExternalIdentityProvider into the repository.
  • SyncContext: executes the synchronization
  • SyncedIdentity: represents a synchronized identity
  • SyncResult: the result of a sync operation
  • SyncException: marker for sync related errors

JMX Synchronization Tool

In addition to the synchronization API Oak 1.0 defines utilities to manage synchronized external identities within JMX (SynchronizationMBean) which allows for the following tasks:

  • syncUsers(String[] userIds, boolean purge)
  • syncAllUsers(boolean purge)
  • syncExternalUsers(String[] externalIds)
  • syncAllExternalUsers()
  • listOrphanedUsers()
  • purgeOrphanedUsers()

Default Implementation

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 and User and Group Synchronization : Dynamic Membership.


There are two ways to replace/change the user synchronization behavior

  1. Write custom SyncManager
  2. Write custom SyncHandler

The following steps are required in order to replace the default SyncManager implementation or plug a new implementation of the SyncHandler:

  • write your custom implementation of the interface
  • make the manager/handler available to the authentication setup or sync manager
    • OSGi setup: making the implementation an OSGi service
    • non-OSGi setup: configure the manager/handler during manual Repository Construction.