The Synchronization Subsystem

From AlfrescoWiki

Jump to: navigation, search


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.

The synchronization subsystem supports two 'modes' of synchronization:

Full
all users and groups are queried, regardless of when they were last modified. All local copies of these users and groups already existing are then updated and new copies are made of new users and groups. Since processing all users and groups in this manner may be fairly time consuming, this mode of synchronization is usually only triggered on the very first sync when the subsystem first starts up. However, synchronization can also be triggered in this mode by the scheduled synchronization job if synchronization.synchronizeChangesOnly is set to false.
Differential
only those users and groups changed since last time are queried and created / updated locally. This 'differential' mode is much faster, and by default is triggered when the subsystem starts up after the first time and when a user is successfully authenticated who doesn't yet have a local person object in Alfresco. This should mean that new users and their group information are pulled over from LDAP servers as and when required with minimal overhead.

Contents

[edit] Deletion Behavior

When synchronization is triggered on server startup or when a new user logs in, user and group deletions are not detected. However, a scheduled job triggers synchronization in a mode that includes detection of deletions. The default scheduling of this job is every 24 hours, but this can be modified using the configuration properties.

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.

[edit] 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

[edit] Configuration

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

synchronization.synchronizeChangesOnly
Should the scheduled sync job run in differential mode? The default is true. Regardless of this setting a differential sync may still be triggered when a user is successfully authenticated who does not yet exist in Alfresco and when the subsystem or server is restarted.
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.


[edit] Debugging

Debugging is done using: 

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

in the log4j file or using a JMX client.


Note that to use the modified since functionality the ldap requests are made asing for the modifyTimestamp, as shown by a network dump: 

No.     Time                       Source                Destination           Protocol Info
      1 2010-01-21 14:26:00.065261 127.0.0.1             127.0.0.1             LDAP     searchRequest(16) "DC=example,DC=foo" wholeSubtree 

Frame 1 (224 bytes on wire, 224 bytes captured)
Ethernet II, Src: 00:00:00_00:00:00 (00:00:00:00:00:00), Dst: 00:00:00_00:00:00 (00:00:00:00:00:00)
Internet Protocol, Src: 127.0.0.1 (127.0.0.1), Dst: 127.0.0.1 (127.0.0.1)
Transmission Control Protocol, Src Port: 41180 (41180), Dst Port: ldap (389), Seq: 1, Ack: 1, Len: 170
Lightweight-Directory-Access-Protocol
    LDAPMessage searchRequest(16) "DC=example,DC=foo" wholeSubtree
        messageID: 16
        protocolOp: searchRequest (3)
            searchRequest
                baseObject: DC=example,DC=foo
                scope: wholeSubtree (2)
                derefAliases: derefAlways (3)
                sizeLimit: 0
                timeLimit: 0
                typesOnly: False
                Filter: (objectclass=groupOfNames)
                    filter: equalityMatch (3)
                        equalityMatch
                attributes: 3 items
                    AttributeDescription: cn
                    AttributeDescription: modifyTimestamp
                    AttributeDescription: member
        [Response In: 2]
        controls: 2 items
            Control
                controlType: 1.2.840.113556.1.4.319 (pagedResultsControl)
                criticality: True
                SearchControlValue
                    size: 1000
                    cookie: <MISSING>
            Control
                controlType: 2.16.840.1.113730.3.4.2 (joint-iso-itu-t.16.840.1.113730.3.4.2)

No.     Time                       Source                Destination           Protocol Info
      2 2010-01-21 14:26:00.065686 127.0.0.1             127.0.0.1             LDAP     searchResEntry(16) "cn=ALFRESCO_ADMINISTRATORS,ou=groups,dc=example,dc=foo" 

Frame 2 (285 bytes on wire, 285 bytes captured)
Ethernet II, Src: 00:00:00_00:00:00 (00:00:00:00:00:00), Dst: 00:00:00_00:00:00 (00:00:00:00:00:00)
Internet Protocol, Src: 127.0.0.1 (127.0.0.1), Dst: 127.0.0.1 (127.0.0.1)
Transmission Control Protocol, Src Port: ldap (389), Dst Port: 41180 (41180), Seq: 1, Ack: 171, Len: 231
Lightweight-Directory-Access-Protocol
    LDAPMessage searchResEntry(16) "cn=ALFRESCO_ADMINISTRATORS,ou=groups,dc=example,dc=foo" [2 results]
        messageID: 16
        protocolOp: searchResEntry (4)
            searchResEntry
                objectName: cn=ALFRESCO_ADMINISTRATORS,ou=groups,dc=example,dc=foo
                attributes: 3 items
                    PartialAttributeList item cn
                        type: cn
                        vals: 1 item
                            ALFRESCO_ADMINISTRATORS
                    PartialAttributeList item member
                        type: member
                        vals: 2 items
                            cn=foouser0,cn=Users,dc=example,dc=foo
                            cn=foouser1,cn=Users,dc=example,dc=foo
                    PartialAttributeList item modifyTimestamp
                        type: modifyTimestamp
                        vals: 1 item
                            20091028124521Z
        [Response To: 1]
        [Time: 0.000425000 seconds]
Retrieved from "http://wiki.alfresco.com/wiki/The_Synchronization_Subsystem"