Connecting to an LDAP server

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:

Navigate to Administration>Server>Users and Roles>User and group providers.
To create a new LDAP connection, click Add LDAP Provider. The Add LDAP Provider page opens.
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:

Navigate to Administration>Server>Users and Roles>User and group providers. From this screen you can suspend or resume and delete an LDAP connection.
Click the Edit button to edit or add properties.
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.