******************************************************************
** phplist-ldap
**
** Author: Brad Peabody (bradpeabody at scientology.net)
** License: Same as PHPList (GPL)
**

A patch to provide LDAP support for PHPList administrator accounts.

******************************************************************
** Overview:

Organizations which have an LDAP directory which they use to store
accounts may want to leverage their directory to provide logins for
administrators of PHPList instances.

Note that this code does not explore the idea of having actual
email list entries in LDAP - just administrator accounts.

There are two basic types of admin users that you can have:

 * "all_users" - This means that all users that match the criteria
   of these settings are allowed into PHPList as admins.  If a
   database record doesn't exist for one of these users, it is
   created when the user logs in.  This gives you the ability to
   control via the LDAP directory exactly which users can log
   into PHPList - without having to do any per-admin-user
   PHPList setup.

 * "matching_users" - This means all users that match this criteria
   and also have a corresponding admin account in PHPList.  With
   this scenario you can have a large number of accounts in the
   directory that are in this category, but only those whose user
   ID matches an admin account PHPList are allowed access.

The "all_users" model suits ISPs or other organizations which need
to administer multiple instances and have administrative people
that can log into each instance without having to explicitly
be set up with an account on each.

The "matching_users" model is more appropriate where you have a
directory which contains a large number of clients, employees,
etc. and you just want to give access individually for specific
people to have administrative access to specific instances
(usually this would be the marketing-type person who will be
doing the mailings, etc.)

You may use one or both of these types of admin users at the same
time.  For example, you may want just your system administrators
setup as "all_users" so they can log into any instance with thier
account and debug issues easily, but then be able to also just
add specific users from the LDAP directory, with the sole benefit
being that the user doesn't have to remember/maintain another
set of login credentials - you can just enter his user name
as an admin in PHPLIst and he's in.

Note that there is no way (unless there's some bug in my code :0)
for any administrator to remove or disable an "all_users" admin
account by manipulating the admin accounts in PHPLIst - since
the account will be recreated and reenabled the next time that
person logs in.  ("all_users" accounts are added and removed in
the LDAP directory.)  This is intentional and prevents a system
administrator from being locked out.

******************************************************************
** Applying the Patch:

This is the easy part:

cd phplist-2.10.4
patch -p0 < phplist-ldap-0.1.patch

******************************************************************
** Configuring:

Just edit your config.php, which will now contain (after the patch)
example configuration parameters for LDAP.

Set $ldap_enabled = 1 to enable LDAP accounts.  Be sure to read
through and properly set the rest of the configuration parameters
before you do this, otherwise the effect will be to just prevent
you from logging in.

You may want to use the $ldap_except_users feature to retain some
accounts which are not checked against the LDAP directory. This
feature is disabled by default however, with the hope that most
people won't use it, thus creating a bit more security by
disabling the default admin/phplist credentials.

******************************************************************
** Security Tips:

* Be aware of the following scenario:

  1) Username "joe" is an "all_users" admin (Let's say this is
  "Joe A".  When he first logs in a record is created for him
  in the PHPList admins table.  "Joe A" can now access the
  system using 

  2) Username "joe" is in the list "matching_users" (this,
  however, is a DIFFERENT user - "Joe B").  "Joe B" was never
  meant to be an administrator, but since his account is available
  through the "matching_users" criteria that is searched when
  a login is attempted, and a record for "joe" (his UID) is
  in the list of PHPList admins - he can now log in an admin.

  In the above case, either one of "Joe A" or "Joe B" would be
  able to log in with their own username and password.

  The only way to prevent this (with the current way the code is
  written) is to remove or rename one of the accounts so you don't
  have two people with the same name.