search

backdrop-contrib / ldap

The Lightweight Directory Access Protocol (LDAP) project provides integration with LDAP.
GNU General Public License v2.0
0 stars 2 forks source link

readme

Lightweight Directory Access Protocol (LDAP) module

The Lightweight Directory Access Protocol (LDAP) project provides integration with LDAP for authentication, user provisioning, authorization, queries, feeds, and views. It also provides API and building blocks (query and server configuration storage) for other modules. It allows you to integrate your organization's existing LDAP-enabled identity management service (such as Active Directory) into Backdrop CMS.

Content

Modules

Testing

Further information

LDAP guides

Many problems in setting up LDAP for Backdrop stem from issues outside of Backdrop CMS and are much easier to debug outside of it, you might find these guides helpful:

Example documentation:

Prerequisites

The following requirements need to be met for you to work with any of the LDAP modules:

Verify the following:

Getting the relevant information

To set up LDAP efficiently, you need to get the relevant information of your environment from your directory administrator before you can continue. This should include:

We have prepared the following sample letter you can send to the responsible party to receive the relevant data:

Dear [LDAP|Active Directory] Administrator,

We would like to leverage the [Campus|Corporate|etc] [LDAP|Active Directory] for authentication and authorization on our Backdrop CMS website. It will be used in the following way:

  • Users will enter their credentials in the Backdrop interface and Backdrop will test them against the LDAP by binding with them.
  • A mirrored Backdrop Account will also be created with their email and a long random password; no LDAP credentials will be stored in Backdrop.

  • LDAP Groups will be mirrored with Backdrop roles and Backdrop role memberships will be derived for LDAP Groups and OUs.

    We have the following questions about configuration and best practices. Whatever you can tell us will be helpful. Once we get connected to the LDAP server, we can hopefully figure out any missing pieces. LDAP Server Connection Properties:

    • What type of LDAP is it (Active Directory, Open LDAP, Open Directory, eDirectory, etc)?
    • Should we bind with a service account for querying user attributes and group memberships? Or use an anonymous bind? If so do we create the service account or can you? If you create it, what is the Distinguished Name (eg. cn=jdoe,ou=...) for it and password?
    • What is the base distinguished name that we should bind to? We suspect it's the top-level DN, but anything above the users and group OUs should work.
    • What is the LDAP server host name and port (e.g. ad.mycompany.com:386)?
    • Should we connect with StartTLS, or ldaps, or neither?
    • Are there any firewall issues we need to resolve to connect from our web server to the LDAP server?

    LDAP User Entries:

    • What attribute contains the users email address (e.g. mail)?
    • Is there a unique attribute such as uid, guid, etc. that does not change over time?
    • What attribute would make a good logon/username (e.g. "cn")?

    Group Entries:

    • Does the user's LDAP entry have an attribute such as memberOf that contains the user's group memberships?
    • What attribute in the group ldap entries holds the users (e.g. uniquemember, memberUid)? And what is held in this attribute (DN, CN, uid, ..)?
    • What is the object class of the group entries (e.g. groupOfNames, groupOfUniqueNames, group)?

    Thanks ...

Installation

Note: The Simple LDAP module also provides integration with LDAP with less functionality: https://backdropcms.org/project/simple_ldap

Configuration overrides

If you need to selectively disable LDAP functionality and cannot disable the modules, use configuration overrides, such as the following in settings.php and clearing your cache afterwards.

IMPORTANT: These overrides will change the data in your admin forms, saving them will save them permanently in the database.

The project consists of 11 modules:

LDAP Servers module

The base module for communicating with a directory. Required by all other LDAP modules. Implements two configuration pages:

Export the configuration of a server:

Import the configuration of a server:

LDAP User module

The core functionality of this module is provisioning and storage of an LDAP identified Backdrop user based on LDAP attributes. The LDAP User module is used to relate, provision (create), and synchronize attributes of LDAP user entries and Backdrop users. Provisioning and synching can go from LDAP to Backdrop and from Backdrop to LDAP. LDAP User module leverages LDAP Server module which configures LDAP server connections and other LDAP server specific data. (provisioning: creating or synching to Backdrop or to LDAP)

Dependencies:

Configuration page:

(LDAP User module configuration depends on LDAP Servers configuration and other modules such as LDAP Authentication for some use cases.)

Provisioning Backdrop Users from LDAP User Entries

Use cases:

Events to Provisioning Backdrop Users from LDAP User Entries

The actual creation of the Backdrop account can happen:

Provisioning LDAP Entries from Backdrop Users

Use cases:

Diagrams

Sequence Diagram of $ldapUserConf->provisionBackdropAccount() method. (Sequence Diagram on gliffy.com)

LDAP Authentication module

This module provides an overall authentication functionality closely tied to ldap_user and ties in with several other modules, such as LDAP SSO (ldap_sso).

Dependencies:

Configuration page:

LDAP Authorization module

LDAP Authorization module to grant roles to users based on directory criteria. It is simply an API for "authorization consumers" such as Backdrop roles or Organic Groups groups. Backdrop roles is most commonly used. You must enable LDAP Authorization and one or more "authorization consumer" modules. Each "authorization consumer" will have a single configuration entry at: admin/config/people/ldap/authorization that will need to be created, configured and enabled for authorization to work.

After configuring an "authorization consumer", use the "test" link to see the authorizations a given test user would be granted.

Dependencies:

Configuration page:

Export the configuration of an "authorization consumer":

Import the configuration of an "authorization consumer":

Vocabulary of LDAP Authorization and its Code:

Use cases are many and varied so the user interface that accommodates them can be complex.

Detailed explanations of the three LDAP group mapping strategies are described in below.

Active Directory + Groups Example

Goal: Have users log in to your Backdrop website based on their credentials from ActiveDirectory, ensure that their 'group' in ActiveDirectory puts them in the correct Backdrop 'role'.

In this example we created groups in ActiveDirectory and added users to those role(s), the base DN for the AD/LDAP Server is "dc=drupal,dc=local". I now have a OrganisationalUnit (ou) called "webadmin" and a Group called "drupal".

AD layout

Using the 'Active Directory Explorer' application my new user 'joe' looks like the following (once he has been assigned to the new group).

Joe config

Backdrop basics
Go to admin/config/people/ldap/servers

Important parts here:

Go to admin/config/people/ldap/user
Go to admin/config/people/ldap/authorization/edit/backdrop_role

This is where we do the actual mapping between LDAP/AD 'Groups' and Backdrop 'Roles':

Now for the fun part..

Mapping of LDAP to Backdrop role (one per line)

There is a Backdrop Role called 'editor', and I want anyone in the LDAP group 'drupal' of the organisational unit webadmin to be assigned to this group when they authenticate, my example config is just: CN=drupal,OU=webadmin,DC=drupal,DC=local|editor

roles mapping configuration

Taddaa, now the user logs in with the role automatically assigned:

Joe user logged in

Derivation strategies of the authorizations

Set the derivation at the server's configuration page: Administration > Configuration > User accounts > LDAP Configuration > Servers > edit

Strategies:

Derivation strategies

Derive Authorizations from User DN

How "Derive from user DN" Works:
  1. Query for user's ldap entry. e.g. cn=verykool, ou=sysadmins, ou=it,dc=ad,dc=myuniversity,dc=edu
  2. Whichever attribute (e.g. ou) listed in "Attribute of the User's LDAP Entry DN which contains the group" (options C.), will have its value added to the list of authorizations. E.g. sysadmins and it
  3. "Derive from user DN" does not support nested groups. Nested has no meaning in this approach.
What an LDAP looks like that can use the "Derive from user DN" approach.

This can be useful in any LDAP and is typically used with one of the other two approaches at the same time. While options B. and C. are designed for two different LDAP group models, "Derive from user DN" simply leverages user DN attributes such as "ou" which may map to authorizations.

Derive Authorizations from User Attribute

How "Derive by Attribute" Works:
Which LDAPs should use the "Derive by Attribute" approach?

Microsoft's Active Directory has this structure. The user's attribute "memberOf" will have a list of all the groups the user is a member of.

What nested groups mean in "Derive by Attribute" approach.

In this approach, nested groups means taking all the groups in memberOf and adding the groups they belong to, recursively. That is if jdoe belongs to the bakers group and the bakers group is member of the "food workers" group, jdoe's authorizations will include bakers and "food workers"

Step by Step walkthrough

Configuration and Sample Data (for further understanding):

Step through for example above:
  1. LDAP Authorization finds the user entry and checks if any "memberOf" attributes exist.
  2. It loops through all of the memberOf attributes and adds each to the authorizations/groups list. e.g. cn=sysadmins,ou=it,dc=ad,dc=myuniveristy,dc=edu, CN=NETadmins,ou=it,dc=ad,dc=myuniveristy,dc=edu, cn=phone operators,ou=it,dc=ad,dc=myuniveristy,dc=edu,

  3. If "Nested groups are used in my LDAP" is checked, a search is performed for all groups that have these groups as members (their parents).

    (&
  (objectClass=group)
  (|
   (memberOf=cn=sysadmins,ou=it,dc=ad,dc=myuniveristy,dc=edu)
   (memberOf=CN=NETadmins,ou=it,dc=ad,dc=myuniveristy,dc=edu)
   (memberOf=cn=phone operators,ou=it,dc=ad,dc=myuniveristy,dc=edu)
  )
)

    The memberOf attributes from the resulting groups are added to the authorizations. This continues on recursively until no results are found or a limit of 10 nests is reached. Because of the number of queries involved, it is best to use 1 high level basedn instead of several lower ones.

  4. If "Convert full dn to value of first attribute" is checked at admin/config/people/ldap/authorization/edit/backdrop_role, the entire array of dns is converted to first attribute. e.g. cn=sysadmins,ou=it,dc=ad,dc=myuniveristy,dc=edu becomes sysadmins. This option is problematic when many groups are involved and name collisions may occur.

Derive Authorizations from LDAP Group Entry

How "Derive from Entry" Works:
  1. Options B: The user attribute and the group entry attribute holding user's attribute are configured.
  2. Each of the groups that has the user attribute in question as a member is added to authorizations.
  3. If nested is selected keep finding child groups recursively. If user is a member of a child group, the ancestor is added to authorizations.
Which LDAPs should use the "Derive from Entry" approach?

This scenario is most applicable to UNIX LDAP environments. In this scenario, the LDAP groups are stored as objects with their members represented by a mulitvalued attribute. That attribute's name might be: member, members, memberUid, uniquemember, etc. That attribute's value might be the DN or CN of another group or user. (LDAPs that use the memberOf overlay, should use options A.)

What nested groups mean in "Derive from Entry" approach.

If user is a member of a child group, the ancestor in is added to authorizations. That is if jdoe belongs to the bakers group and the bakers group is member of the "food workers" group, jdoe's authorization will be "food workers".

Step by Step walkthrough

Sample data and configuration (for further understanding):

LDAP Authorization - Backdrop Roles module

Implements LDAP authorization for Backdrop roles. It provides an "authorization consumer" for Backdrop roles.

Dependency:

Configuration page: It has a single configuration entry at admin/config/people/ldap/authorization That will need to be configured and enabled for authorization to work. Administration > Configuration > User accounts > LDAP Configuration > Authorization > edit

After configuring an "authorization consumer", use the "test" link to see the authorizations a given test user would be granted.

LDAP Authorization - OG (Organic Groups) module

Implements LDAP authorization for Organic Groups. It provides an "authorization consumer" for Organic Groups groups.

Dependencies:

Configuration page: It has a single configuration entry at admin/config/people/ldap/authorization That will need to be configured and enabled for authorization to work. Administration > Configuration > User accounts > LDAP Configuration > Authorization > edit

After configuring an "authorization consumer", use the "test" link to see the authorizations a given test user would be granted.

Use case:

Automate membership and roles in Organic Groups based on LDAP data such as user attributes or group memberships. Requirements:

Setup

These notes are brief, deferring to more complete instructions are in the configuration forms.

  1. Create the Organic Groups and roles you need. If the default OG roles work (member and admin) you do not need to worry about creating roles.
  2. Download LDAP project at https://backdropcms.org/project/ldap
  3. Enable LDAP Servers and configure an LDAP Server. Only one server can be used with LDAP Authorization OG at a time.
  4. At admin/config/people/ldap/authorization/add/og_group, create OG Group Configuration. After configuring this, a test page will be available.
  5. Go to the test page: admin/config/people/ldap/authorization/test/og_group and try some usernames to see what OG roles the user would be granted.
  6. When you are satisfied with this test with actual users logging in.
Tips and Gotchas
LDAP Authorization OG Storage:

OG authorizations are stored in form gid-rid from the tables og (og.gid) and og_roles (og_roles.rid). E.G. 1-2, 2-3, 3-4. OG in Backdrop does not use machine names so numeric ids are the only way to store such identifiers.

such as:

$user->data = array(
  'ldap_authorizations' => array(
    'og_group' => array (
      '3-2' => array (
        'date_granted' => 1329105152,
      ),
      '2-3' => array (
        'date_granted' => 1329105152,
      ),
    ),
    'backdrop_role' => array (
      '7' => array (
        'date_granted' => 1329105152,
      ),
      '5' => array (
        'date_granted' => 1329105152,
      ),
    ),
  );

LDAP Query module

A module to allow you to execute custom queries, which can be display in Views or used in custom solutions. LDAP query builder and storage for queries used by other ldap modules such as LDAP Feeds module etc.

Dependencies:

Configuration page:

You can create and store queries what include these settings:

Export the configuration of a query:

Import the configuration of a query:

LDAP Views module

It provides Views integration for LDAP data. It adds new, LDAP-related filter/sort criteria and fields to those available by views.

Dependencies:

Recommended:

How to use

  1. Create a new LDAP query: admin/config/people/ldap/query/add ( Administration > Configuration > User accounts > LDAP Configuration > Queries > Add LDAP Query ) It is the data source of the view.
  2. Add a new view: admin/structure/views/add ( Administration > Structure > Views > Add view )
  3. Set "Show: LDAP Query"
  4. "Continue & configure" button
  5. Other > Query settings > Settings > Set the related LDAP query (step 1.)
  6. Set fields: Fields > Add > LDAP ...
  7. You can set filter criteria: Filter criteria > Add > LDAP ...
  8. You can set sort criteria: Sort criteria > Add > LDAP ...
  9. You can set a menu entry. Example:
    • Use "No menu" link.
    • Select "Normal menu entry".
    • Title: title of the menu entry
    • Menu: Primary navigation
    • "Apply" button
  10. "Save" button

Available LDAP-related fields, filter/sort criteria:

LDAP Feeds module

Feeds module integration: Included feeds fetcher for a generic ldap query and ldap entry parser to turn fetcher data into feeds compatible parser result. Used to automate content creation based on ldap queries or to automatically sync users.

Feeds is a general architecture for moving data where an importer consists of a fetcher, parser, and processor. Ldap Feeds supplies the fetcher and parser such that any processor can be used (node, user, taxonomy term, etc).

Dependencies:

Recommended:

Example use-cases:

Detailed example 1.

Sync LDAP data to existing Backdrop user: step by step example of using LDAP Feeds "Backdrop User LDAP Entry Fetcher" to bring in profile data of existing users.

  1. Configure an LDAP server. Make sure fields related to LDAP and Backdrop users are filled out.
  2. Enable the following modules: job_scheduler, feeds, feeds_ui, ldap_query, ldap_feeds, field_ui (core module)
  3. Add a user account field: ( admin/config/people/manage/fields )
    • Surname Field: 
      [Example]
 Label : Surname
 Field type : Text (short)
 Widget : Text field
[/Example]
    • Press the "Save" button.
    • Press the "Save field settings" button.
    • Press the "Save settings" button.
  4. Create new Feed importer: ( admin/structure/feeds/create ) 
    [Example]
 Name: LDAP Data to User Fields
 Machine-Readable name: ldap_data_to_user_fields
[/Example]
  5. Basic settings: ( admin/structure/feeds/ldap_data_to_user_fields/settings ) 
    [Example]
 Attach to content type : Use standalone form
 Periodic Import : Off (can turn on after testing)
 Import on Submission : Checked
 Processed in background : Unchecked  (Check after testing for larger number of users)
[/Example]
  6. Set Fetcher to "Backdrop User LDAP Entry Fetcher". ( admin/structure/feeds/ldap_data_to_user_fields/fetcher )
  7. Fetcher settings: ( admin/structure/feeds/ldap_data_to_user_fields/settings/FeedsBackdropUserLdapEntryFetcher ) 
    [Example]
 Only return ldap authenticated users : Unchecked
[/Example]
  8. Set Parser to "LDAP Entry Parser for Feeds". ( admin/structure/feeds/ldap_data_to_user_fields/parser )
  9. There are no Parser settings.
  10. Change processor to "User processor". ( admin/structure/feeds/ldap_data_to_user_fields/processor )
  11. User processor settings: ( admin/structure/feeds/ldap_data_to_user_fields/settings/FeedsUserProcessor ) 
    [Example]
  Insert new users : Selected
  Update existing users : Selected
  Text format : Plain text
  Skip non-existent users : Selected
  Status : Active
  Additional roles : Select extra roles to assign to users upon import.
[/Example]
  12. Set Mappings: ( admin/structure/feeds/ldap_data_to_user_fields/mapping ) SOURCE are fields from LDAP and TARGET are the fields from Backdrop user account (e.g. fields of users table). If you have selected a test user in your ldap server configuration, you should get example values in the "legend" sources table. 
    [Example]
  SOURCE      TARGET                   UNIQUE TARGET
  cn          User name (name)         checked
  mail        Email address (mail)     unchecked
  sn          Surname (field_surname)  unchecked
[/Example]
  13. Log in Backdrop with a new user provided by LDAP. You can see the empty "Surname" field on the user account page.
  14. Execute the import:
    • Open the page of "LDAP Data to User Fields" importer: import/ldap_data_to_user_fields ( URL of the "Feeds importers": base_url/import )
    • "Import" button.
  15. You can see the filled "Surname" field on the user account page.

Caveats:

Detailed example 2.

Step by step example of using LDAP Feeds "LDAP Query Fetcher" to bring in user data from LDAP to create new Backdrop users.

  1. Configure the LDAP server. Make sure fields related to LDAP and Backdrop users are filled out.
  2. Enable the following modules: job_scheduler, feeds, feeds_ui, ldap_query, ldap_feeds, field_ui (core module)
  3. Add user account fields: ( admin/config/people/manage/fields ) 
    [Example]
 First Name Field :  First Name  field_fname  Text (short)  Text field
 Last Name Field :  Last Name  field_lname  Text (short)  Text field
[/Example]

    Include other fields as per your needs further ahead.

  4. Create new LDAP Query: ( admin/config/people/ldap/query/add ) 
    [Example]
 Machine name for this query configuration : ecm_users (Give unique name)
 Name : ECM Users (Human readable name for the query)
 LDAP Server used for query : select your LDAP server
 Enabled : Checked
 Base DNs to search in query : CN=Users,DC=hogwarts,DC=com
 Filter : (&(objectClass=user) (memberOf=CN=give_specific_group_name,CN=Users,DC=hogwarts,DC=com))
 Attributes to return : DN,SN,GIVENNAME,USERPRINCIPALNAME,MAILNICKNAME
[/Example]
    • If you want all of users and not of specific group, you can skip section memberOf completely. Filter then becomes: (objectClass=user) Details: LDAP Filter
    • Feel free to add your needed attributes.
    • You can test the LDAP query at admin/config/people/ldap/query under "OPERATIONS".
  5. Create new Feed importer: ( admin/structure/feeds/create ) 
    [Example]
  Name : LDAP Data to User Data
  Machine-Readable name : ldap_data_to_user_data
[/Example]
  6. Basic settings: ( admin/structure/feeds/ldap_data_to_user_data/settings ) 
    [Example]
 Name : LDAP Data to User Data
 Attach to content type : Use standalone form
 Periodic import : 15 min
 Import on Submission : Checked
 Processed in background : Checked
[/Example]
    • Uncheck the option "Import on Submission", if you need scheduled importation of users from LDAP to Backdrop. (Step 14.)
    • Check the option "Import on Submission", if you want to import users from LDAP to Backdrop by manually triggered. (Step 13.)
    • "Save" this Basic settings.
  7. Set Fetcher to "LDAP Query Fetcher". ( admin/structure/feeds/ldap_data_to_user_data/fetcher )
  8. Fetcher Settings: ( admin/structure/feeds/ldap_data_to_user_data/settings/FeedsLdapQueryFetcher ) Select "LDAP Query" in here. In this case: "ECM Users" "Save" this Fetcher settings.
  9. Set Parser to "LDAP Entry Parser for Feeds". ( admin/structure/feeds/ldap_data_to_user_data/parser )
  10. Change processor to "User processor". ( admin/structure/feeds/ldap_data_to_user_data/processor )
  11. User processor settings: ( admin/structure/feeds/ldap_data_to_user_data/settings/FeedsUserProcessor ) 
    [Example]
  Insert new users : Selected
  Update existing users : Selected
  Text format : Plain Text
  Skip non-existent users : Selected
  Status : Active
  Additional roles : Select extra roles to assign to users upon import.
  Defuse e-mail addresses : Unchecked
[/Example]

  12. Set Mappings: ( admin/structure/feeds/ldap_data_to_user_data/mapping ) SOURCE are fields from LDAP (result attributes of the "ECM Users" query) and TARGET are the fields from Backdrop user account (e.g. fields of users table).

    [Example]
  SOURCE              TARGET                      UNIQUE TARGET
  MAILNICKNAME        User name (name)            checked
  USERPRINCIPALNAME   Email address (mail)        checked
  GIVENNAME           First Name (field_fname)    unchecked
  SN                  Last Name (field_lname)     unchecked
[/Example]
  13. Manually triggered import:
    • Open the page of "LDAP Data to User Data" importer: import/ldap_data_to_user_data ( URL of the "Feeds importers": base_url/import )
    • Select the related query: "ECM Users" (step 4.)
    • "Import" button.
  14. Lets see how can we schedule this importer to execute periodically to import users from LDAP to Backdrop:

Assuming we have created a module named "import_data".

A. Implement hook_cronapi()

  function import_data_cronapi($op, $job = NULL) {
    return array(
      'import_data_cronjob_1' => array(
        'title' => 'Import LDAP Users',
        'callback' => 'import_data_ldap_users_callback',
        'enabled' => TRUE,
        'scheduler' => array(
          'name' => 'crontab',
          'crontab' => array(
            'rules' => array('0+@ */12 * * *'), // Schedule for import once in 12 hours
          ),
        ),
      ),
    );
  }

B. Write Function to actually import

  function import_data_ldap_users_callback($job) {
    $vars = array();
    if (function_exists('feeds_source')){
      while (FEEDS_BATCH_COMPLETE != feeds_source('ldap_data_to_user_data')->import());
      watchdog('Cron LDAP Users Import', t('LDAP Users Imported Successfully.'), $vars, WATCHDOG_INFO,NULL);
    }
    else {
      watchdog('Cron LDAP Users Import', t('Function : feeds_source not found.'), $vars, WATCHDOG_ERROR,NULL);
    }
  }

Done! You have successfully scheduled a cron to import LDAP Users into Backdrop

Caveats:

LDAP Test module

Module for testing the LDAP module. Only for development and debugging purposes. It's required by LDAP Help module.

Summary of simpletest framework for LDAP_* modules

Configuration sources for LDAP Simpletests:

Related sources:

LDAP Help module

This module assists Backdrop administrators in configuring, debugging, sharing, and submitting support and bug request related to LDAP modules. LDAP Help module should be disabled unless you are debugging or configuring LDAP problems. Disable it in production. It adds no functionality or end user help.

Dependencies:

Assist pages:

Configuration page:

LDAP SSO module

Provides Kerberos/NTLM single-sign-on. This module is now a separate project on Backdropcms.org But the configure page is integrated into the LDAP Authentication module.

Configuration page:

Tokens

Some fields in the LDAP modules allow for "ldap tokens". For example: Administration > Configuration > User accounts > LDAP Configuration > User > LDAP Servers Providing Provisioning Data: Use server These tokens are replaced by values within an LDAP entry retrieved from the PHP LDAP extension.

Example Use Cases

The following are based on the LDAP entry below.

Use Case Template Evaluates to
ldap server mail template [cn]@myuniversity.edu jdoe@myuniversity.edu
ldap server mail template [cn]@[dc:1].edu jdoe@myuniversity.edu

Example Illustrating Derivation of Token Values

An LDAP entry array such as:

'dn' => 'cn=jdoe,ou=campus accounts,ou=toledo campus,dc=ad,dc=myuniveristy,dc=edu',
'mail' => array( 0 => 'jdoe@myuniversity.edu', 'count' => 1),
'sAMAccountName' => array( 0 => 'jdoe', 'count' => 1),

Would have the following tokens available for its templates:

Additional Example Tokens

Use the test link at the servers page: admin/config/people/ldap/servers You can see the tokens and sample values when you enter a test username and submit the form.

Automated testing

You can test four LDAP modules by Simpletest:

  1. Enable the Simpletest and Field UI (field_ui) core module:
    • Administration > Functionality > List modules > Testing: Enabled
    • Administration > Functionality > List modules > Field UI: Enabled
  2. Open the Testing page: Administration > Configuration > Development > Testing
  3. Select these tests:
    • LDAP Servers Tests
    • LDAP User Integration Tests
    • LDAP User Unit Tests
    • LDAP User User Interface
    • LDAP Authentication Tests
    • LDAP Authorization Basic Tests
    • OG 1.x-2.x Tests. (This requires the Organic Groups module.)
  4. Press "Run tests" button.

Manual testing

(Detailed examples: Local LDAP test server by Vagrant)

LDAP Server module

After configuring a server, use the "test" link. Available at admin/config/people/ldap/servers Fill the form, and press the "Test" button.

LDAP User module

LDAP User test form

A test page is available at admin/config/people/ldap/user/test for testing your LDAP User configuration. The value of this form is to see what would happen based on your current configuration or to actually execute an action for a single account. This can be very useful to confirm your LDAP user and LDAP server configuration.

To use, enter a test Backdrop username and check the events you want to test. The resulting page will show what the provisioning would be. If you select the "Execute Action" mode, the transactions configured will be performed (for that user).

Notes about the resulting arrays:

LDAP User test scripts

Manual testing scripts are available at: ldap_user/tests/ldap_user.test.manual.txt These are handy for understanding the expected behavior of the ldap user module.

LDAP Authentication

Login with a user provided by LDAP.

LDAP Authorization module

After configuring an "authorization consumer", use the "test" link to see the authorizations a given test user would be granted. Available at admin/config/people/ldap/authorization Fill the form, and press the "Test" button. The result page shows detailed authorization data.

LDAP Query module

After configuring a query, use the "test" link to see the result of the query. Available at admin/config/people/ldap/query

LDAP Views module

Create a new view: LDAP Views module > How to use

LDAP Feeds

Try these:

Local LDAP test server by Vagrant

You can test the LDAP module with a local LDAP test server. Main steps:

  1. Building a test environment
  2. Configure the LDAP module for the local test server
  3. Manual tests of the LDAP module on the local test server

1. Building a test environment

You can build a test environment with this description. You can download and install a prepared configuration. There is a Vagrantfile included that will build a virtual machine with a working LDAP directory.

  1. Install VirtualBox:
    • https://www.virtualbox.org/ (Version 6.1.10 tested.)
    • Enable the virtualization in the BIOS.
    • The language of Virtualbox must be "English", because Vagrant reads VirtualBox's responses.
  2. Install Vagrant: https://www.vagrantup.com/ (Version 2.2.9 tested.)
  3. Download this project: https://github.com/VasasA/simple_ldapVM/archive/7.x-1.x.zip (It is a fork of https://github.com/ulsdevteam/simple_ldap)
  4. Unzip it into a directory.
  5. Open Terminal, and cd to this directory (containing the Vagrantfile).
  6. Run this command: vagrant up It will download and build a virtual machine with a working LDAP directory. (It may take a long time.)
  7. When complete, there is the IP address in the last line. If OS X is the Vagrant host, then the vagrant box is available at simpleldap.local For other operating systems, the IP address will need to be obtainted manually, and added to the local hosts file for best results. (%WinDir%\System32\drivers\etc)
  8. You can create some new LDAP users:
    • Open phpLDAPadmin. Available at http://simpleldap.local/pma
      • Login DN: cn=admin,dc=local
      • password: admin
    • Select the ou=people in the tree.
    • Use the "Create a child entry" link.
    • Select "Default".
    • ObjectClass: inetOrgPerson
    • Press the "Proceed" button.
    • Create Object:
      • RDN: cn
      • cn: "username"
      • sn: "surname"
      • Email: "user email address"
      • Password: "user password"
      • Press the "Create Object" button.
    • Press the "Commit" button.
  9. You can create some new LDAP groups:
    • Open phpLDAPadmin. Available at http://simpleldap.local/pma
      • Login DN: cn=admin,dc=local
      • password: admin
    • Select the ou=groups in the tree.
    • Use the "Create a child entry" link.
    • Select "Default".
    • ObjectClass: groupOfNames
    • Press the "Proceed" button.
    • Create Object:
      • RDN: cn
      • cn: "name of the group"
      • member: You must set up at least one user. Example: cn=ldapuser,ou=people,dc=local
      • Press the "Create Object" button.
    • Press the "Commit" button.
  10. After testing, you can shut down the virtual machine with this command: vagrant halt

LDAP

Or:

phpLDAPadmin

Virtual machine's console or ssh credentials

Drupal 7

2. Configure the LDAP module for the local test server

Configuration page: Administration > Configuration > User accounts > LDAP Configuration

3. Manual tests of the LDAP module on the local test server

LDAP test script without Backdrop

Location of the script file: ldap_help/ldap_test_script This script is intended to help separate LDAP module configuration and bugs from LDAP server, ldap php extension, and related connectivity and LDAP permissions issues. It uses the php ldap extension functions like ldap_connect(), ldap_search(), etc. rather than the Backdrop LDAP module code. The test script does not depend on the Backdrop LDAP module and should not be run within a web server context. This script is preconfigured by config.inc according to the "Local LDAP test server by Vagrant". Details: ldap_help/ldap_test_script/README.md

Debugging

  1. Enable LDAP Help module (ldap_help) and detailed watchdog logging to get more information on what is occurring:
    • Use LDAP Help module status page: admin/config/people/ldap/help/status
    • Enable "Detailed LDAP Watchdog logging": admin/config/people/ldap
    • Enable Database Logging module: admin/modules/list
  2. Try to understand the responses in the log and the different stages in which they occur: admin/reports/dblog
  3. Try narrowing down your problem by making sure that the each step works before moving on to the next. (Use "Manual testing") i.e.:
    • Connection
    • Bind
    • Search
    • Authentication
    • Authorization
  4. Isolating LDAP problems from LDAP Module problems When things get tricky, sometimes its best to go to the php scripts or command line queries of ldap to make sure a problem is in Backdrop or LDAP modules and not in the LDAP server, PHP ldap extension, or particular LDAP user or group entries:
    • For authentication issues, make sure the user is able to use other software with their LDAP credentials.
    • Try a PHP script that is not tied to Backdrop such as the one in the LDAP Help module within ldap_help/ldap_test_script: LDAP test script without Backdrop This will help isolate Backdrop issues from php ldap extension and LDAP server problems.
    • Use another tool such as apache directory or command line LDAP queries. For example: $ ldapsearch -H ldap://127.0.0.1 -x -b dc=people,dc=local -D joe@example.local -w 'Thepassword'
  5. Debugging LDAP Authorization
    • Go to the test form: admin/config/people/ldap/authorization/test/backdrop_role
    • Submit with a username.
    • In the response page to the form, examine the "Prefiltered and Final Mappings" section. It lists all the "raw authorizations" or the authorizations before filtering and mapping. If you do not see the raw authorizations you expect, your "II. LDAP to Backdrop role mapping and filtering" is off: admin/config/people/ldap/authorization/edit/backdrop_role Otherwise your problem is likely in part III. of the authorization configuration which triggers when authorization happens.
    • There is some ability to see intermediary data in the authorization code. This can be helpful for debugging. Enable "Detailed LDAP Watchdog logging" as above. Then log on as the user in question. There will be detailed logs in watchdog of the LDAP authorization steps: admin/reports/dblog
  6. Picking data Picking through the database and the configuration can be helpful. Here are some queries. The serialized data can be better viewed at http://unserialize.net/serialize.
    • table: ldap_authmap: Will contain a record for every user who is ldap authenticated. select * from ldap_authmap where module like 'ldap%';
    • table: users: LDAP data specific to a user will be stored in the data field of this table. select cast(data as char(1000)) from users where data like '%ldap%';
    • table: ldap_servers
    • table: ldap_authorization: Data used to map users LDAP entry to authorization rights.
    • Picking through configuration:
      • admin/config/development/configuration/single/export
      • Configuration group: Configuration
      • Configuration name: Select an LDAP module.
      • Copy the content of "Exported configuration" field.

Common Error Messages and Warnings

Need to use LDAPS

Some LDAP servers require ldaps. Make sure to do the following:

Need to use Start TLS

To use TLS, you either need your certificate to work OR need to configure LDAP to never require a certificate.

Issues

Bugs and Feature requests should be reported in the Issue Queue: https://github.com/backdrop-contrib/ldap/issues Please always provide detailed log output and information on your configuration. See also admin/config/people/ldap/help/issues for debugging output you can copy and paste into the issue.

Current Maintainer

Credits

License

This project is GPL v2 software. See the LICENSE.txt file in this directory for complete text.

Screenshot

LDAP screenshot