Configuring LDAP Settings

Last Modified: 07-March-2014

This document covers the installation of optional LDAP add-ons and the configuration of LDAP in Joomla.

Jump to:
  1. Installation
  2. Configuring LDAP
  3. Debugging LDAP
  4. Example Setup

Installation

Before proceeding, ensure the platform and modules are configured - refer to the Getting Started with Version 2.

  1. The following extensions are optional add-ons for LDAP. These can be downloaded from the downloads page:
    • pkg_ldap_plugins
    • mod_shldap_login
  2. Log into the back-end / administrator of the Joomla site and go to the Extension Manager.
  3. Click 'Browse...' then select the downloaded packages from step 1.
  4. Click 'Upload & Install'. Repeat until all packages listed in step 1 are installed.

If an error is presented, check the Joomla installation is correctly configured (i.e. correct file permissions).

Back to Top

Configuring LDAP

This section demonstrates configuring the LDAP hosts and settings.

  1. Enable the following plug-ins in the Plug-in Manager:

    • Authentication - User Adapter
    • SHLog - LDAP

    Its a good idea to enable debugging options located inside the 'SHLog - LDAP' plug-in during configuration.

  2. Open the Shmanic LDAP component (com_shldap).

  3. Within the Shmanic LDAP component, click the 'LDAP Host Configurations'. This is where the LDAP server settings are held. Click on 'New'.

    Use the following table as a reference for completing host configuration:

    Key Description Examples / Usage
    Name The name of this LDAP host record. This value is used as the domain name when dealing with multiple LDAP host configurations. Suitable examples:
    • openldap
    • students
    • staff
    LDAP V3 Latest versions of OpenLDAP and Active Directory require version 3 of the LDAP protocol. Older LDAP servers may use version 2. Set to Yes for modern LDAP servers.
    Negotiate TLS Negotiate TLS is currently an undocumented feature of PHP that allows an encrypted channel to be used when communicating with an LDAP server. This is not the same as using ldaps:// on port 636. Refer to the PHP manual page for more information on this feature. Set to No in most cases.
    Follow Referrals This option sets the value of the LDAP_OPT_REFERRALS flag which specifies whether to automatically follow referrals returned by the LDAP server. Set to No in most cases.
    Host Specify the host name for the LDAP servers(s) with either a IP, DNS or URL pointing at one or more LDAP server(s). Multiple entries can be used by separating each entry by a space.

    When using SSL, the host may have to take the form ldaps://<host>. Though consult with the LDAP servers' documentation for correct configuration.    		 Valid examples:
    • 10.4.55.100 10.4.55.101
    • ldap.domain.local
    • ldaps://ldap.domain.local
    Port Specify the port for the LDAP server. By default this is 389. Some Windows based servers also use the Global Catalog port 3268. The default port for SSL connections is 636. Set to 389 for default setups.
    Proxy User Leave this blank to connect anonymously (the LDAP server must allow anonymous logins for this to work). Alternatively, specify the RDN or DN of the user to use for connecting. This is used when either searching for a user, fail-over group mapping or the single sign on plug-ins. This user may require administrator rights depending on whether plug-ins require LDAP write access. Examples for OpenLDAP and eDir:
    • cn=proxyuser,dc=shmanic,dc=net
    • cn=proxyuser,o=company
    Examples for Active Directory:
    • DOMAIN\proxyuser
    • proxyuser@DOMAIN.LOCAL
    Proxy Password Leave blank for anonymous, otherwise enter password for proxy user.
    Password Encryption Encrypts the proxy password.

    IMPORTANT: The default encryption method is based on the secret found in Joomla's configuration and therefore is weak. If an unauthorised persons gained access to the encrypted string, it is highly recommended to change the password as soon as possible. Furthermore, the proxy user should be blacklisted in the LDAP settings to disable site logins using it.    		 Set to Yes to avoid a cleartext password.
    Base DN Specify the base DN of the LDAP server or organisational unit that should used as a base for all LDAP searches. Valid examples:
    • o=company
    • dc=domain,dc=local
    • ou=People,dc=shmanic,dc=net
    User DN / Filter Specify the LDAP DN or Filter to be used for binding to the authenticating user. The [username] keyword is dynamically replaced by the attempting user's username.

    If users are in multiple OU's: this value must be a LDAP filter (sometimes referred to as a LDAP query) searching for a specific attribute that can distinguish a user from the username entered. This filter can also be used to exclude organisational units, groups and/or users from a search. See this reference for more on LDAP filters.

    WARNING: do NOT use a filter without a [username] replacement like (&(objectCategory=person)(objectClass=user)) - this is BAD and can lead to lockouts!


    If all users are in the same OU: a LDAP DN must be specified. Multiple DN's can be separated by a semi-colon and each is attempted a bind in order.

    If multiple users are found that satisfy the condition, then the first to authenticate successfully is used. This value must be populated.
    IF using filter
    For Active Directory:
    • (sAMAccountName=[username])
    Use for eDir:
    • (cn=[username])
    Example for OpenLDAP:
    • (uid=[username])
    IF using DN
    Example:
    • cn=[username],ou=users,o=comp
    Map User ID Specify the LDAP attribute that contains the user's ID for mapping to the Joomla login name field. For Active Directory:
    • sAMAccountName
    Most LDAP systems:
    • uid
    Map Full Name Specify the LDAP attribute that contains the user's full name for mapping to the Joomla name field. For Active Directory:
    • name
    • displayName
    Examples:
    • cn
    • fullName
    Map Email Specify the LDAP attribute that contains the user's email for mapping to the Joomla email field. The attribute mail is used as a default for most LDAP systems.

    If the LDAP directory doesn't contain email values, then a 'fake' email can be implemented. These can be implemented by using the [username] keyword which is dynamically replaced by the username. For example [username]@ACME.LOCAL.    		 Example:
    • mail
    Fake Email Example:
    • [username]@domain.com
    Password Attribute Specify the password attribute for setting the password to the user object. For Active Directory:
    • unicodePwd
    Example:
    • userPassword
    Password Hash The type of password hash that should be used when setting a password in LDAP. For Active Directory:
    • unicode
    Password Prefix Prefix the password hash to the hashed password.
    All User Filter Specify a filter to retrieve all users that should be registered on the site. This is used by the LDAP Cron script to synchronise users. See this reference for more on LDAP filters. Examples:
    • (&(objectClass=person)(mail=*))
    • (objectClass=person)
    • (objectClass=inetOrgPerson)
  4. Once the configuration is completed, click on 'Save'. The inbuilt Debugger should be used to ensure correct settings, refer to Debugging LDAP.
  5. A default LDAP host configuration should be selected. This can be set in the 'LDAP Settings' found in the Shmanic Config component (com_shconfig). Select a LDAP host configuration from the 'Default Config' dropdown.
  6. Refer to other documents for setting up the specific LDAP plug-ins such as Group Mapping, Profile, Password, Creation and Deletion.

Back to Top

Debugging LDAP

Once the initial LDAP configuration is completed, the inbuilt debugger should be used to check the LDAP host settings. This section demonstrates how to use the inbuilt debugger.

  1. Go to a LDAP host configuration.
  2. Populate the 'Test Username' and 'Test Password' fields with test users from the LDAP server.
  3. Click on 'Test/Debug' to show the debug output.
  4. Evaluate the results:
    • If errors are detected within the configuration, they are highlighted with a pink background.
      Limitation Note: if a failed to bind with proxy user is encountered, and password encryption is enabled and the proxy password was changed, the configuration must be saved first before debugging.
    • Ensure the 'User ID', 'Full Name' and 'Email' are correctly populated for the test user within the output.
    • Check the attributes are listed for the test user. This can also be useful for determining correct attribute values.
    • If the LDAP Cron script shall be used, check the total number of users found near the bottom of the output. Adjust the 'All User Filter' if required.

Back to Top

Example Setup

The following screen shots show the LDAP host configuration and debug for an Active Directory setup.

Active Directory Host Record
Active Directory Debug Record