User Management Limitations and Recommendations

This page describes the optimal configurations and limitations that apply to user management in Confluence.

General Recommendations

Avoid duplicate usernames across directories. If you are connecting to more than one user directory, we recommend that you ensure the usernames are unique to one directory. For example, we do not recommend that you have a user jsmith in both 'Directory1' and 'Directory2'. The reason is the potential for confusion, especially if you swap the order of the directories. Changing the directory order can change the user that a given username refers to.

Be careful when deleting users in remote directories.

If you are connecting to an LDAP directory, a Crowd directory or a Jira directory, please take care when deleting users from the remote directory. If you delete a user that is associated with data in Confluence, this will cause problems in Confluence.

If a user who has created content is deleted from an external directory, and an account is then re-created with the same username, it will automatically be re-associated with that content. This is intentional, so that if a directory sync problem occurs, users are correctly re-associated with their content.

Avoid hash, slash and question characters in usernames 

There is a known issue where users with #, ? or / in their username cannot create spaces. See  CONF-43494 - Getting issue details... STATUS  and  CONF-13479 - Getting issue details... STATUS  for more information.

Recommendations for Connecting to LDAP

Please consider the following limitations and recommendations when connecting to an LDAP user directory.

Optimal Number of Users and Groups in your LDAP Directory

The connection to your LDAP directory provides powerful and flexible support for connecting to, configuring and managing LDAP directory servers. To achieve optimal performance, a background synchronization task loads the required users and groups from the LDAP server into the application's database, and periodically fetches updates from the LDAP server to keep the data in step. The amount of time needed to copy the users and groups rises with the number of users, groups, and group memberships. For that reason, we recommended a maximum number of users and groups as described below.

This recommendation affects connections to LDAP directories:

  • Microsoft Active Directory
  • All other LDAP directory servers

The following LDAP configurations are not affected:

  • Internal directories with LDAP authentication
  • LDAP directories configured for 'Authentication Only, Copy User On First Login'

Please choose one of the following solutions, depending on the number of users, groups and memberships in your LDAP directory.

Your environment


Up to 10 000 (ten thousand) users, 1000 (one thousand) groups, and 20 (twenty) groups per user

Choose the 'LDAP' or 'Microsoft Active Directory' directory type. You can make use of the full synchronization option. Your application's database will contain all the users and groups that are in your LDAP server.

More than the above

Use LDAP filters to reduce the number of users and groups visible to the synchronization task.

Our Test Results

We performed internal testing of synchronization with an AD server on our local network consisting of 10 000 users, 1000 groups and 200 000 memberships.

We found that the initial synchronization took about 5 minutes. Subsequent synchronizations with 100 modifications on the AD server took a couple of seconds to complete.

Please keep in mind that a number of factors come into play when trying to tune the performance of the synchronization process, including:

  • Size of userbase. Use LDAP filters to keep this to the minimum that suits your requirements.
  • Type of LDAP server. We currently support change detection in AD, so subsequent synchronizations are much faster for AD than for other LDAP servers.
  • Network topology. The further away your LDAP server is from your application server, the more latent LDAP queries will be.
  • Database performance. As the synchronization process caches data in the database, the performance of your database will affect the performance of the synchronization.
  • JVM heap size. If your heap size is too small for your userbase, you may experience heavy garbage collection during the synchronization process which could in turn slow down the synchronization.

Redundant LDAP is Not Supported

The LDAP connections do not support the configuration of two or more LDAP servers for redundancy (automated failover if one of the servers goes down).

Specific Notes for Connecting to Active Directory

When the application synchronizes with Active Directory (AD), the synchronization task requests only the changes from the LDAP server rather than the entire user base. This optimizes the synchronization process and gives much faster performance on the second and subsequent requests.

On the other hand, this synchronization method results in a few limitations:

  1. Externally moving objects out of scope or renaming objects causes problems in AD. If you move objects out of scope in AD, this will result in an inconsistent cache. We recommend that you do not use the external LDAP directory interface to move objects out of the scope of the sub-tree, as defined on the application's directory configuration screen. If you do need to make structural changes to your LDAP directory, manually synchronize the directory cache after you have made the changes to ensure cache consistency.
  2. Synchronizing between AD servers is not supported. Microsoft Active Directory does not replicate the uSNChanged attribute across instances. For that reason, we do not support connecting to different AD servers for synchronization. (You can of course define multiple different directories, each pointing to its own respective AD server.)
  3. You must restart the application after restoring AD from backup. On restoring from backup of an AD server, the uSNChanged timestamps are reverted to the backup time. To avoid the resulting confusion, you will need to flush the directory cache after a Active Directory restore operation.
  4. Obtaining AD object deletions requires administrator access. Active Directory stores deleted objects in a special container called cn=Deleted Objects. By default, to access this container you need to connect as an administrator and so, for the synchronization task to be aware of deletions, you must use administrator credentials. Alternatively, it is possible to change the permissions on the cn=Deleted Objects container. If you wish to do so, please see this Microsoft KB article.
  5. The User DN used to connect to AD must be able to see the uSNChanged attribute. The synchronization task relies on the uSNChanged attribute to detect changes, and so must be in the appropriate AD security groups to see this attribute for all LDAP objects in the subtree.

Recommendations for Connecting to Jira for User Management

Please consider the following limitations and recommendations when connecting to a JIRA server for user management.

Single Sign-On Across Multiple Applications is Not Supported

When you connect to a JIRA application for user management, you will not have single sign-on across the applications connected in this way. JIRA, when acting as a directory manager, does not support SSO.

Custom Application Connectors are Not Supported

JIRA applications, Confluence, FishEye, Crucible and Bamboo can connect to a JIRA server for user management. Custom application connectors will need to use the new REST API.

Custom Directories are Not Supported

Earlier versions of JIRA supported OSUser Providers. It was therefore possible write a special provider to obtain user information from any external user directory. This is no longer the case.

Load on your JIRA instance

If your JIRA instance is already under high load, then using it as a User Server will increase that load.

JIRA Cloud applications not supported

You cannot use JIRA Cloud applications to manage standalone users. Cloud users and users within your self-hosted Atlassian applications need to be managed separately.


Your environment


If all the following are true:

  • Your JIRA application is not under high load.
  • You want to share user and group management across just a few applications, such as one JIRA Software server and one Confluence server, or two JIRA servers.
  • You do not need single sign-on (SSO) between your JIRA application and Confluence, or between two JIRA servers.
  • You do not have custom application connectors. Or, if you do have them, you are happy to convert them to use the new REST API.
  • You are happy to shut down all your servers when you need to upgrade your JIRA application.

Your environment meets the optimal requirements for using a JIRA application for user management.

If one or more of the following are true:

  • If your JIRA application is already under high load.
  • You want to share user and group management across more than 5 applications.
  • You need single sign-on (SSO) across multiple applications.
  • You have custom applications integrated via the Crowd SOAP API, and you cannot convert them to use the new REST API.
  • You are not happy to shut down all your servers when you need to upgrade JIRA.

We recommend that you install Atlassian Crowd for user management and SSO.

If you are considering creating a custom directory connector to define your own storage for users and groups...

Please see if one of the following solutions will work for you:

  • If you have written a custom provider to support a specific LDAP schema, please check the supported LDAP schemas to see if you can use one of them instead.
  • If you have written a custom provider to support nested groups, please consider enabling nested groups in the supported directory connectors instead.
  • If you have written a custom provider to connect to your own database, please consider loading the data into the application's database instead.
  • If you need to keep the custom directory connection, please consider whether Atlassian Crowd meets your requirements. See the documentation on Creating a Custom Directory Connector.

Last modified on Oct 11, 2021

Was this helpful?

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