LDAP Tools

Last modified by Thomas Mortagne on 2023/10/10 16:40

cogLDAP administration section and automatic user synchronization tool
Developed by


1 Votes
LicenseGNU Lesser General Public License 2.1


Starting with XWiki 4.0, this application is superseeded by the officially supported LDAP Application.

This application causes a lots of issues especially with group mapping in its current state. You should avoid using it.

LDAP configuration section

This is simply an UI that exposes the LDAP configuration properties.

You can refer to the LDAP Authentication tutorial and the LDAP Authentication Use Cases for more information about LDAP configuration in XWiki.

The xwiki.authentication.authclass property must be set in xwiki.cfg to use the LDAP authenticator for the authentication to work as expected.


Option xwiki.cfg analog Default Description meaning
Ldap xwiki.authentication.ldapoffTurn LDAP authentication on - otherwise only XWiki authentication
Ldap server adressxwiki.authentication.ldap.server - LDAP Server (Active Directory, eDirectory, OpenLDAP, etc.)
Ldap server portxwiki.authentication.ldap.port - 
Ldap login matchingxwiki.authentication.ldap.bind_DN - 

LDAP login, empty = anonymous access, otherwise specify full dn
{0} is replaced with the user name, {1} with the password.
It may be an explicit username and password to access your LDAP directory.

Ldap password matchingxwiki.authentication.ldap.bind_pass - 
Validate Ldap user/passwordxwiki.authentication.ldap.validate_passwordoff

Bypass standard LDAP bind validation by doing a direct password comparison.
If you don't know what you do, don't use that. It's covering very rare and bad use cases.

Ldap group filterxwiki.authentication.ldap.user_group - 

only members of the following group will be verified in the LDAP
otherwise only users that are found after searching starting from the base_DN

Ldap group to excludexwiki.authentication.ldap.exclude_group - [Since 1.5RC1, XWikiLDAPAuthServiceImpl] only users not member of the following group can authenticate
Ldap base DNxwiki.authentication.ldap.base_DN - base DN for searches
Ldap UID attribute namexwiki.authentication.ldap.UID_attrcnSpecifies the LDAP attribute containing the identifier to be used as the XWiki name
Try local loginxwiki.authentication.ldap.trylocaloff[Since 1.3M2, XWikiLDAPAuthServiceImpl] if ldap authentication fails for any reason, try XWiki DB authentication with the same credentials
Update user from LDAPxwiki.authentication.ldap.update_user[Since 1.3M2, XWikiLDAPAuthServiceImpl] on every login update the mapped attributes from LDAP to XWiki otherwise this happens only once when the XWiki account is created.
Ldap user fiels mappingxwiki.authentication.ldap.fields_mapping - retrieve the following fields from LDAP and store them in the XWiki user object (xwiki-attribute=ldap-attribute)
Ldap groups mappingxwiki.authentication.ldap.group_mapping - 

[Since 1.3M2, XWikiLDAPAuthServiceImpl]
maps XWiki groups to LDAP groups, separator is "|"


When copy/pasting this configuration parameter from xwiki.cfg please make sure to remove '\' line concatenation sign as well as forward and trailing whitespaces. It is acceptable to split different record into multiple lines, but again without extra whitespaces. The reason for removing whitespaces is that if they are present, it will try to create e.g. '+++XWiki.Organisation' group which would be incorrect and prevent proper group mapping and hence authentication.

LDAP groups members cachexwiki.authentication.ldap.groupcache_expiration3600*6[Since 1.3M2, XWikiLDAPAuthServiceImpl] time in seconds after which the list of members in a group is refreshed from LDAP
LDAP groups sync modexwiki.authentication.ldap.mode_group_syncalways

[Since 1.3M2, XWikiLDAPAuthServiceImpl]
    create : synchronize group membership only when the user is first created
    always: synchronize on every login

LDAP synchronization feature

This features allows to have automatic synchronization of users (and mapped groups) between XWiki and the LDAP it is configured for.

  • This feature is only available starting with XWiki 3.0
  • If your version of XWiki is compatible and the extension has been installed according to the installations instructions, you will see a section about the synchronization right under the general LDAP configuration section


Configuring the synchronization frequencies

The LDAP synchronization relies on the Scheduler Application. It bring two scheduler jobs:

  • One is responsible for starting a synchronization cycle. Its name in the scheduler job table is Start LDAP synchronization cycle. Its default cron configuration is 0 0 2 * * ?, which means every night at 2 A.M.
  • The other one is responsible for executing batches of user account synchronization. Its name in the scheduler job table is Execute LDAP synchronization batch. Its default configuration is 0 0/5 * * * ?, meaning every five minutes.

You can change the frequency of execution for each of the two jobs to better fit your needs. Don't forget to unschedule and reschedule the jobs you edit in order for the new settings to take effect. Also, don't forget that LDAP group members are cached, for 6 hours as a default setting (see the parameter xwiki.authentication.ldap.groupcache_expiration). If you have a synchronization frequency higher than the cache purge frequency, you will not see the synchronization effects as expected.

Other configuration options

Option nameDescription
Synchronize groups defined in the LDAP group mappingIf set to true, members from all groups defined in the XWiki <-> LDAP group mapping (parameter group_mapping) will be synchronized.
Other groups to synchronizeYou might want to synchronize more groups than those defined in your group mapping. You can list them here, separated by a new line
Page to use for storing the list of accounts that remains to be synchronizedThis parameter allows to set a custom page used as a marker of accounts that remains to be synchronized. You usually don't have to change this, and can leave it blank.
Page to use for writing the synchronization logsYou can precise which page should be used to log the details about synchronization operations. You usually don't have to change this, and can leave it blank.
Override the synchronization list when non emptyIt is not recommended to activate this option. It allows to force starting a new synchronization cycle when its jobs triggers, but the previous cycle is not finished (some accounts are still listed to be synchronized)
Number of accounts to synchronize per batchDefines how many accounts should be synchronized per batch. It is recommended to have this number relatively low (in combination with the batch frequency) for the initial synchronization since all users will trigger an account creation. It can then be set to a higher value in cruse mode, since most users should not trigger an update anymore : only new users, users with update profile or group memberships will trigger an update

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. You'll also need to install all dependent Extensions that are not already installed in your wiki

For the synchronization feature you need to ensure that:

  • the document XWiki.AdminLdapSyncSheet is saved by an user with programming rights
  • the two scheduler jobs (namely XWiki.LdapFetchUsersToSynchronize and XWiki.SynchronizeLdapUsers) have sufficient rights (they should be saved by an user with programming rights) and are actually scheduled

Release Notes


Initial version


Get Connected