Synchronizing 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 synchronization 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 synchronization 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 synchronization do not occur for the following user directory types:

  • 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 synchronization 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 synchronization task has copied that user's details into the cache.
  • A periodic synchronization task will run to update the database with any changes made to the external directory. The default synchronization interval, or polling interval, is one hour (60 minutes). You can change the synchronization interval on the directory configuration screen.
    • Note for Confluence Data Center: The sync will take place on a single node of the cluster to update the database. This may make it seem like automatic synchronization will not be happening, but the task is assigned to one of the nodes.
  • You can manually synchronize 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 Synchronize

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

Manually Synchronizing the Cache

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

Screen snippet: User directories, showing information about synchronization

Configuring the Synchronization Interval

Note: The option to configure the synchronization 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 'Synchronization Interval' on the directory configuration screen. The synchronization interval is the period of time to wait between requests for updates from the directory server.

The length you choose for your synchronization 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 synchronize more frequently, then your data will be more up to date. The downside of synchronizing 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.

Unsynced users

To view users who have previously been synchronized with Confluence, but were not present in the last directory sync, go to Administration  > User management > Unsynced from Directory

Users may appear in the Unsynced from Directory tab be due to a problem with your last sync, or because the user has been intentionally removed from the external directory (for example because they've left your organisation). 

If a user who has created content is removed from an external directory, and a new account is created with the same username, that username will be associated with the original user's content. This is intentional, to ensure that if a directory sync problem occurs, users are correctly re-associated with their own content.

If the user was intentionally unsynced, administrators can choose to:

  • Leave the unsynced account as it is. The person's username will appear on any content or comments they've created. 
  • Delete the account from the Unsynced from Directory tab, which then replaces the username with an anonymous alias. This final deletion step is usually only required if you've received a formal erasure request. 

See Delete or Disable Users for more information. Don't assume that because a user appears in the unsynced users list, that they are to be deleted from Confluence. 

You may see a user in the Unsynced from Directory tab with the username 'exporter'.  This account is used when creating the demonstration space when you first install Confluence, and can be included when importing a Cloud site. You can safely ignore this unsynced account. 

Last modified on Mar 31, 2023

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.