Synchronising Data from External Directories

For certain directory types, Confluence stores a cache of directory information (users and groups) in the application database, to ensure fast recurrent access to user and group data. A synchronisation task runs periodically to update the internal cache with changes from the external directory.

On this page:

Related pages:

Affected Directory Types

Data caching and synchronisation apply to the following user directory types:

  • LDAP (Microsoft Active Directory and all supported LDAP directories) where permissions are set to read only.
  • LDAP (Microsoft Active Directory and all supported LDAP directories) where permissions are set to read only, with local groups.
  • LDAP (Microsoft Active Directory and all supported LDAP directories) where permissions are set to read/write.
  • Atlassian Crowd.
  • Atlassian JIRA.

Data caching and synchronisation do not occur for the following user directory types:

  • LDAP (Microsoft Active Directory and all supported LDAP directories) where permissions are set to authentication only, with local groups.
  • Internal Directory with LDAP Authentication.
  • Internal Directory.

How it Works

Here is a summary of the caching functionality:

  • The caches are held in the application database.
  • When you connect a new external user directory to the application, a synchronisation task will start running in the background to copy all the required users, groups and membership information from the external directory to the application database. This task may take a while to complete, depending on the size and complexity of your user base.
  • Note that a user will not be able to log in until the synchronisation task has copied that user's details into the cache.
  • A periodic synchronisation task will run to update the database with any changes made to the external directory. The default synchronisation interval, or polling interval, is one hour (60 minutes). You can change the synchronisation interval on the directory configuration screen.
  • You can manually synchronise the cache if necessary.
  • If the external directory permissions are set to read/write: Whenever an update is made to the users, groups or membership information via the application, the update will also be applied to the cache and the external directory immediately.
  • All authentication happens via calls to the external directory. When caching information from an external directory, the application database does not store user passwords.
  • All other queries run against the internal cache.

Finding the Time Taken to Synchronise

The 'User Directories' screen shows information about the last synchronisation operation, including the length of time it took.

Manually Synchronising the Cache

You can manually synchronise the cache by clicking 'Synchronise' on the 'User Directories' screen. If a synchronisation operation is already in progress, you cannot start another until the first has finished.

Screen snippet: User directories, showing information about synchronisation

Configuring the Synchronisation Interval

Note: The option to configure the synchronisation interval for Crowd and JIRA directories is available in Confluence 3.5.3 and later. Earlier versions of Confluence allow you to configure the interval for LDAP directories only.

You can set the 'Synchronisation Interval' on the directory configuration screen. The synchronisation interval is the period of time to wait between requests for updates from the directory server.

The length you choose for your synchronisation interval depends on:

  • The length of time you can tolerate stale data.
  • The amount of load you want to put on the application and the directory server.
  • The size of your user base.

If you synchronise more frequently, then your data will be more up to date. The downside of synchronising more frequently is that you may overload your server with requests.

If you are not sure what to do, we recommend that you start with an interval of 60 minutes (this is the default setting) and reduce the value incrementally. You will need to experiment with your setup.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

4 Archived comments

  1. User avatar

    Peter Binney

    So how do you "experiment with your setup" please?

    Specifically, I want to alter the Synchronisation Interval used when a Directory was created. But there is no way to do this.

    13 Feb 2013
  2. User avatar

    Bill Boulden

    How do I force a full refresh synchronization, if the incremental synchronization has fallen out of touch with the real thing? (Some changes to some users didn't make it in while the system was down and now seem to be not making it in at all)

    05 Feb 2014
    1. User avatar

      Rachel Robins [Atlassian Tech Writer]

      HI Bill, sorry for the late reply. I checked with our support engineers and falling out of synch shouldn't really happen. You can force a full sync by restarting Confluence, or by going to Admin > User Directories, and unticking 'enable incremental synchronisation', then syncing again.  If this continues to happen, you should contact Support for assistance, as something else might be going wrong.  

      17 Feb 2014
  3. User avatar

    Sorin Sbarnea (Citrix)

    It would be important to remark that if accounts are renamed (sAMAccount) syncronization will fail in confluence. Read  CONF-35047 - Confluence user synchronisation create duplicated user account after user rename in the remote repository Resolved

    04 Feb 2015
Powered by Confluence and Scroll Viewport