LDAP administration section and automatic user synchronization tool

Description

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.

Option	xwiki.cfg analog	Default	Description meaning
Ldap	xwiki.authentication.ldap	off	Turn LDAP authentication on - otherwise only XWiki authentication
Ldap server adress	xwiki.authentication.ldap.server	-	LDAP Server (Active Directory, eDirectory, OpenLDAP, etc.)
Ldap server port	xwiki.authentication.ldap.port	-
Ldap login matching	xwiki.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 matching	xwiki.authentication.ldap.bind_pass	-
Validate Ldap user/password	xwiki.authentication.ldap.validate_password	off	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 filter	xwiki.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 exclude	xwiki.authentication.ldap.exclude_group	-	[Since 1.5RC1, XWikiLDAPAuthServiceImpl] only users not member of the following group can authenticate
Ldap base DN	xwiki.authentication.ldap.base_DN	-	base DN for searches
Ldap UID attribute name	xwiki.authentication.ldap.UID_attr	cn	Specifies the LDAP attribute containing the identifier to be used as the XWiki name
Try local login	xwiki.authentication.ldap.trylocal	off	[Since 1.3M2, XWikiLDAPAuthServiceImpl] if ldap authentication fails for any reason, try XWiki DB authentication with the same credentials
Update user from LDAP	xwiki.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 mapping	xwiki.authentication.ldap.fields_mapping	-	retrieve the following fields from LDAP and store them in the XWiki user object (xwiki-attribute=ldap-attribute)
Ldap groups mapping	xwiki.authentication.ldap.group_mapping	-	[Since 1.3M2, XWikiLDAPAuthServiceImpl] maps XWiki groups to LDAP groups, separator is "|" XWiki.XWikiAdminGroup=cn=AdminRole,ou=groups,o=MegaNova,c=US| XWiki.Organisation=cn=testers,ou=groups,o=MegaNova,c=US 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 cache	xwiki.authentication.ldap.groupcache_expiration	3600*6	[Since 1.3M2, XWikiLDAPAuthServiceImpl] time in seconds after which the list of members in a group is refreshed from LDAP
LDAP groups sync mode	xwiki.authentication.ldap.mode_group_sync	always	[Since 1.3M2, XWikiLDAPAuthServiceImpl]     create : synchronize group membership only when the user is first created     always: synchronize on every login

LDAP synchronization feature

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 name	Description
Synchronize groups defined in the LDAP group mapping	If set to true, members from all groups defined in the XWiki <-> LDAP group mapping (parameter group_mapping) will be synchronized.
Other groups to synchronize	You 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 synchronized	This 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 logs	You 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 empty	It 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 batch	Defines 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

v1.0

Initial version