The Synchronization Subsystem

From alfrescowiki

In Alfresco version 3.2 onwards, The synchronization subsystem manages the synchronization of Alfresco with all the user registries (LDAP servers) in the authentication chain.

Contents 1 Synchronization Modes 2 Synchronization Triggers 3 Deletion Behavior 4 Collision Resolution 5 Configuration 6 Debugging 7 Triggering a full ldap sync 8 Notes

Synchronization Modes

The synchronization subsystem supports three 'modes' of synchronization:

Differential

only those users and groups changed since last time are queried and created / updated locally. This mode is the fastest and should mean that new users and their group information are pulled over from LDAP servers as and when required with minimal overhead.

Differential With Deletions

the entire set of users and groups is queried from the LDAP server to determine which users and groups no longer exist and are candidates for deleting locally (see Deletion Behaviour). In order to synchronize the attributes of the remaining users and groups a differential sync is then performed, so only those users and groups known to have changed since the last sync are updated or added locally.

Full

the entire set of users and groups is queried from the LDAP server to determine which users and groups no longer exist and are candidates for deleting locally (see Deletion Behaviour). The attributes of each one of these users and groups are also queried in order to update or add a local copy of each and every user and group. This is the most time consuming mode and should only be required when the servers' timestamp information has somehow got out of sync.

Synchronization Triggers

Synchronization can be triggered by each of the following events

Startup

On system startup or restart of the Synchronization subsystem a differential sync is triggered (unless disabled with configuration).

Authentication

On successful authentication of a user who does not yet exist locally a differential sync is triggered (unless disabled with configuration).

Schedule

A scheduled job triggers synchronization in differential with deletions mode every 24 hours. This can instead by scheduled in full mode if you set the synchronization.synchronizeChangesOnly property to false. The scheduling of this job may also be altered. See Configuration.

Deletion Behavior

As noted above users and groups are only deleted when synchronization is triggered by the scheduled job in either differerential with deletions or full mode. Users and groups in Alfresco created as a result of a synchronization operation are tagged with an originating zone ID. This records the ID of the authentication subsystem instance that the user or group was queried from. On synchronization with a zone, only those users and groups tagged with that zone are candidates for deletion from Alfresco. This avoids accidental deletion of 'built-in' groups such as ALFRESCO_ADMINISTRATORS.

The four screen shots below illustrate the 'zone' concept in two different groups. As you can see: The group foogroup0 has a parent of type cm:inZone with node reference:

workspace://SpacesStore/760201ac-6d2e-43ed-a5dc-0c7d42875746

The parent workspace://SpacesStore/760201ac-6d2e-43ed-a5dc-0c7d42875746 has the zone name: AUTH.EXT.ldap; This means that this group was created during a ldap sync on a subsystem called 'ldap'

On the other hand the goup GROUP_site_site1 has a cm:inZone parent with node reference workspace://SpacesStore/e639f9d5-fa55-4f5b-b079-5acfa113629f

and the cm:inZone parent name is: APP.SHARE This means that this group has been created from the 'Share' application.

Collision Resolution

If there are 'overlaps' between the contents of two user registries in the authentication chain (e.g. they both contain a user with the same user name) then the registry that occurs earlier in the authentication chain will be given precedence. This means that exactly the same order of precedence used during authentication will be used during synchronization.

For example, If user A is queried from zone Z1 but already exists in Alfresco in zone Z2

• A is moved to Z1 if it is earlier in the authentication chain
• A is ignored if Z1 is later in the authentication chain

Configuration

The subsystem supports the following properties. See Configuring Subsystems for how to configure these.

synchronization.synchronizeChangesOnly

Should the scheduled sync job be run in differential with deletions mode? The default is true. If false the scheduled sync job is run in full mode and every single user and group is synchronized, regardless of timestamp. Note this setting has no effect on the mode of synchronization on startup on or authentication. This is always differential mode.

synchronization.import.cron

A cron expression defining when the scheduled synchronization job should run, by default at midnight every day.

synchronization.syncOnStartup

Should we trigger a differential sync when the subsystem starts up? The default is true. This ensures that when user registries are first configured, the bulk of the synchronization work is done on server startup, rather than on the first login.

synchronization.syncWhenMissingPeopleLogIn

Should we trigger a differential sync when a user is successfully authenticated who does not yet exist in Alfresco? The default is true.

synchronization.autoCreatePeopleOnLogin

Should we create a user with default properties when a user is successfully authenticated who does not yet exist in Alfresco and was not returned by a differential sync (if enabled with the property above)? The default is true. Setting this to false would allow you to restrict Alfresco to a subset of those users who could be authenticated by LDAP; only those created by synchronization would be allowed to log in. You could control the set of users that would be in this more restricted set by overriding the user query properties of the LDAP authentication subsystem.

Debugging

Debugging is done using:

log4j.logger.org.alfresco.repo.security.sync=debug

in the log4j file or using a JMX client.

Triggering a full ldap sync

One way to trigger a full ldap sync is:

1. set synchronization.synchronizeChangesOnly to false in JMX (or in alfresco-global.properties with a server restart)
2. and do a executeNow() on the sync bean in JMX.

The JMX action executeNow() mentionned above is available in jconsole going to

MBeans -> Alfresco -> Schedule -> *CronTrigger (e.g. MonitoredCronTrigger)-> syncTrigger ->excuteNow()

To see this syncTrigger bean, you may need to have the sync job running i.e have pressed:

MBeans->Alfresco->Configuration->Synchronization->default->Operations->start()

Note 1: Another way to trigger a full lap sync is:

1. set synchronization.synchronizeChangesOnly to false
2. and set the cron expression to a a time close to you
3. restart in JMX the Synchronization subsystem and wait until the time written in the cron expression above is reached.

Note 2: As mentioned in http://issues.alfresco.com/jira/browse/ALF-3575 the scheduled sync job pays attention to the syncChangesOnly flag BUT the startup sync intentionally only does not take it into account and always do a differential sync. You fire the full ldap sync either through executeNow() in JMX or by changing the CRON expression.

Notes

If an admin manually deletes a user in Alfresco they have to understand that this user won't be resynced from LDAP unless they do a full sync, due to the caching of timestamp information. See https://issues.alfresco.com/jira/browse/ALF-5433

It's not recommended to include the same LDAP server in the chain more than once as it could cause acount locking, see https://issues.alfresco.com/jira/browse/ALF-5444. Just leave ldap.authentication.userNameFormat as the empty string to get the subsystem to resolve user IDs using a recursive search.