Connecting to an LDAP server

November 14, 2023

The Jahia LDAP Connector module can be downloaded from the Jahia store. The module provides an LDAP provider implementation for users and user groups. Jahia supports using multiple LDAP providers simultaneously to achieve better flexibility and data aggregation.

Registering LDAP providers

You can register LDAP providers either through the administration UI or configuration files. Synchronization is performed between the two, allowing you to deploy a configuration file and then update it from the administration UI.

By default, LDAP configurations are shared across cluster nodes. You can disable cluster synchronization using this procedure.

Using the administration

LDAP user and group providers can be configured using the administration UI in Administration>Server>Users and Roles>User and group providers. The UI provides a convenient way to add, remove, start or suspend providers and also adjust their configuration.

To create an LDAP connection:

  1. Navigate to Administration>Server>Users and Roles>User and group providers.
  2. To create a new LDAP connection, click Add LDAP Provider. The Add LDAP Provider page opens.
    AddLDAPServer.png
  3. Default properties display. You can add new properties by clicking the add + button. Refer to the property reference for more details.

To edit an LDAP connection:

  1. Navigate to Administration>Server>Users and Roles>User and group providers. From this screen you can suspend or resume and delete an LDAP connection.
    LDAPServers.png
  2. Click the Edit button to edit or add properties.
    EditLDAPServer.png
  3. Click Save.

Using a configuration file

You can use a configuration  (.cfg) file to declare an LDAP provider. Prefix the file name with org.jahia.services.usermanager.ldap- and then the name of your connection, for example, org.jahia.services.usermanager.ldap-intranet-directory.cfg. You must provide the same information in this file as you would in the administration interface. For example, the content of such file could contain:

user.uid.search.name=dc\=acme,dc=com
group.search.name=dc\=acme,dc\=com
public.bind.password=adminpassord
public.bind.dn=cn\=admin,dc\=acme,dc\=com
url=ldap\://ldap.acme.com\:389/

Then drop this file in the digital-factory-data/karaf/etc folder.

You will then see the LDAP configuration in the administration UI. It will be available on other cluster nodes as well, unless cluster synchronization has been disabled.

User provider properties reference

The section describes LDAP properties that you can specify to customize the user provider configuration.

The following table lists and describes connection and authentication parameters.

Key Default value Description
url <none> The LDAP connection URL, for example ldap://127.0.0.1:389/
public.bind.dn <none> The user on the LDAP server permitted to search the LDAP directory within the defined search base
public.bind.password <none> The password used to authenticate searches in LDAP directory
target.site <none> [Optional] Sets a site key to mount the provider on a site
authentification.mode simple LDAP directory authentication type
context.factory com.sun.jndi.ldap.LdapCtxFactory The implementation class for context factory to use
ldap.connect.pool apache-commons Type of pool to use: ldap, apache-commons, or none. See next sections for pool type-specific parameters.

The following table lists and describes connection parameters for native Java LDAP pool.

Key Default value Description
ldap.connect.pool.debug <none> The level of debug output to produce. Valid values are "fine" (trace connection creation and removal) and "all" (all debugging information)
ldap.connect.pool.initSize 1 The number of connections per connection identity to create when initially creating a connection for the identity
ldap.connect.pool.maxSize <none> The maximum number of connections per connection identity that can be maintained concurrently
ldap.connect.pool.prefSize <none> The preferred number of connections per connection identity that should be maintained concurrently
ldap.connect.pool.timeout <none> The number of milliseconds that an idle connection may remain in the pool without being closed and removed from the pool

The following table lists and describes connection parameters for apache-commons pool.

Key Default value Description
ldap.connect.pool.maxActive 8 The maximum number of active connections of each type (read-only|read-write) that can be allocated from this pool at the same time, or non-positive for no limit
ldap.connect.pool.maxTotal -1 The overall maximum number of active connections (for all types) that can be allocated from this pool at the same time, or non-positive for no limit
ldap.connect.pool.maxIdle 8 The maximum number of active connections of each type (read-only|read-write) that can remain idle in the pool, without extra ones being released, or non-positive for no limit
ldap.connect.pool.minIdle 0 The minimum number of active connections of each type (read-only|read-write) that can remain idle in the pool, without extra ones being created, or zero to create none
ldap.connect.pool.maxWait -1 The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception, or non-positive to wait indefinitely
ldap.connect.pool.whenExhaustedAction BLOCK

Specifies the behavior when the pool is exhausted.
- The FAIL option will throw aNoSuchElementException when the pool is exhausted.
- The BLOCK option will wait until a new object is available. If max-wait is positive a NoSuchElementException is thrown if no new object is available after the max-wait time expires.
- The GROW option will create and return a new object (essentially makingmax-active meaningless).

ldap.connect.pool.testOnBorrow false Whether objects will be validated before being borrowed from the pool. If the object fails to validate, it will be dropped from the pool, and an attempt to borrow another will be made
ldap.connect.pool.testOnReturn false Whether objects will be validated before being returned to the pool
ldap.connect.pool.testWhileIdle false Whether objects will be validated by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool.
ldap.connect.pool.timeBetweenEvictionRunsMillis -1 The number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.
ldap.connect.pool.numTestsPerEvictionRun 3 The number of objects to examine during each run of the idle object evictor thread (if any)
ldap.connect.pool.minEvictableIdleTimeMillis 1000 * 60 * 30 The minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any)

The following table lists and describes search parameters.

Key Default value Description
uid.search.name <none> The search base that defines which part of the LDAP directory tree to search, e.g. dc=jahia,dc=com
To improve performance when retrieving the members of groups it is advisable to have a different base between user and group search.
uid.search.attribute cn The name of the attribute that will be used as a user key
search.objectclass person The objectClass value for a user object
search.wildcards.attributes ou, cn, o, c, mail, uid, uniqueIdentifier, givenName, sn, dn A list of attributes to use for wildcard searches such as *=*test*
search.countlimit 100 The number of entries to limit search results to. If the LDAP user search returns more matching entries than specified with this parameter, the first search.countlimit will be returned only.
search.attribute.inDn false If set to true, signals that the users and groups IDs are contained in the dn. Useful to improve the performance when lookup the members.
user.search.filter <none> A predefined filter which is applied additionally to all user searches and lookups, effectively filtering non-matching users out. This option is available since LDAP module version 3.0.6 (DX 7.1.2.3) and 3.1.1 (DX 7.2.0.2).

The following table lists and describes attribute mapping parameters which define a mapping between Jahia's jnt:user node properties and the corresponding LDAP object attributes.

Key Default value Description
user.j:firstName.attribute.map givenName First name
user.j:lastName.attribute.map sn Second name
user.j:email.attribute.map mail User's e-mail address
user.j:organization.attribute.map ou The name of the organization

Additional attribute mappings can be specified using the following pattern for the entry key: user.<jahia-user-property-name>.attribute.map and the name of the corresponding LDAP object attribute as the value.

User group provider properties reference

This section describes LDAP properties that you can specify to customize the group provider configuration.

The following table lists and describes connection and authentication parameters.

Key Default value Description
url <none> The LDAP connection URL, e.g. ldap://127.0.0.1:389/
public.bind.dn <none> This is the user on the LDAP server permitted to search the LDAP directory within the defined search base.
public.bind.password <none> The password used to authenticate searches in LDAP directory
target.site <none> [Optional] Set a site key to mount the provider on a site
authentification.mode simple LDAP directory authentication type
context.factory com.sun.jndi.ldap.LdapCtxFactory The implementation class for context factory to use
ldap.connect.pool apache-commons Type of pool to use: LDAP, apache-commons, or none. See above sections for pool type-specific parameters.

The following table lists and describes search and membership parameters.

Key Default value Description
preload false If set to true forces the reading of all group members when a group is retrieved. Otherwise, group members will be read when the first request for user membership will be made
search.countlimit 100 The number of entries to limit search results too. If the LDAP user search returns more matching entries than specified with this parameter, the first search.countlimit will be returned only.
refferal ignore Specifies how referrals encountered by the service provider are to be processed. Possible values are follow - follow referrals automatically, ignore - ignore referrals, throw - throw ReferralException when a referral is encountered
ad.range.step 0 Handle Active Directory range searches when retrieving group members. If set to 0 all members are retrieved with a single search. If set e.g. to 100, searches like range=0-100, range=101-200, range=201-300 etc. are used to retrieve all members iteratively.
search.name <none> The search base that defines which part of the LDAP directory tree to search, e.g. dc=jahia,dc=com
To improve performance when retrieving the members of groups it is advisable to have a different base between user and group search.
search.attribute cn The name of the attribute that will be used as a user key
search.objectclass groupOfUniqueNames The objectClass value for a group object
search.wildcards.attributes cn,description,uniqueMember A list of attributes to use for wildcard searches such as *=*test*
members.attribute uniqueMember The name of the LDAP group object attribute to retrieve membership from
dynamic.enabled false Set to true if you want to use the dynamic groups
dynamic.search.objectclass groupOfURLs The name of the LDAP group object attribute to retrieve dynamic membership from
dynamic.members.attribute memberurl The name of the LDAP group object attribute to retrieve dynamic membership from
canGroupContainSubGroups false Set to true to enable support for nested (hierarchical) groups, i.e. where a group could have other groups as members.
group.search.filter <none> A pre-defined filter which will be applied additionally to all group searches and lookups, effectively filtering non-matching groups out. This option is available since LDAP module version 3.0.6 (DX 7.1.2.3) and 3.1.1 (DX 7.2.0.2).

The following table lists and describes attribute mapping parameters which define a mapping between Jahia's jnt:group node properties and the corresponding LDAP object attributes.

Key Default value Description
group.groupname.attribute.map cn Group name
group.description.attribute.map description Description

Additional attribute mappings can be specified, using the following pattern for the entry key: "group.<jahia-group-property-name>.attribute.map" and the name of the corresponding LDAP object attribute as the value.