Hyland

resplin · ‎06-05-2015

The official documentation is at: http://docs.alfresco.com

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.

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 Removals: 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 disabling or 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 disabling or 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 removals 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 removed from the LDAP directory or query are only identified when synchronization is triggered by the scheduled job in either differerential with removals 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.

When a removed user or group is detected, Alfresco will behave in one of two ways, depending on the value of the synchronization.allowDeletions property. When true, the default, Alfresco will simply delete the user or group from the local repository. When false, the user or group is simply 'untagged' from its zone, thus converting it to an Alfresco local user or group. A removed user also loses their memberships from any of the LDAP groups they were in and a removed group is cleared of all their members. As the user or group is retained in the Alfresco repository, this setting has the advantage that the site memberships for that user or group are remembered, should they later be reactivated.

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 ignored if Z1 is later in the authentication chain than Z2
A is moved to Z1 if Z2 wasn't in the authentication chain at all, or Z1 is earlier in the authentication chain and the synchronization.allowDeletions property is false.
A is deleted from Z2 and recreated in Z1 if Z1 is earlier in the authentication chain and the synchronization.allowDeletions property is true.

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.allowDeletions: Are deletions of local users and groups allowed? See #Deletion Behavior and #Collision Resolution for the circumstances under which this may happen. The default is true. If false, then no sync job will be allowed to delete users or groups during the handling of removals or collision resolution.

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:

set synchronization.synchronizeChangesOnly to false in JMX (or in alfresco-global.properties with a server restart)
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:

set synchronization.synchronizeChangesOnly to false
and set the cron expression to a a time close to you
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.

Note 3:
Lastly, another way of always triggering a full sync is to modify the differential queries themselves. If you set ldap.synchronization.personDifferentialQuery to be the same as ldap.synchronization.personQuery, then all your users will be fully synced, even when Afresco thinks it's doing a differential sync. Groups obey the same behaviour if you set ldap.synchronization.groupDifferentialQuery

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.

More about Zones

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
sync_foogroup0.png

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'
sync_foogroup0_zone.png

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

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