LDAP for PHP-Nuke 2.2.0 (NukeLDAP) README
by Wm. Wong, 02/03/2006 
bwong at voicenet dot com


Overview:
This package synchronizes the PHP-Nuke user database with an LDAP database
so names and passwords can be maintained in the LDAP database. It can coexist
with other LDAP support such as POSIX and SAMBA allowing LDAP to act as a 
central repository for user authentication and information.

This version of NukeLDAP does not support synchronization of fields other
than the password field.

This version of NukeLDAP was tested on:

	CentOS 4.x
	OpenLDAP 2.2
	PHPNuke 7.8

It should work with any LDAP server and versions of PHPNuke from 7.7 onward.


Note for Version 1 users:
Version 2 is a completely new architecture so if you have version 1 you will
want to start with a fresh PHP-Nuke installation. Version 2 adds an
administration interface. Installation is much easier and LDAP support
can be disable and enabled from the administration page instead of 
editing system files. It can also be setup so user management is 
restricted to LDAP users although user management will then have to
be done outside of PHP-Nuke. 


Theory of operation:
NukeLDAP is installed as an administration module in admin/modules. It
provides a management interface accessible only to PHPNuke Super Users.
It has a support module that is loaded via the database support and
changes have been made to the Your_Account module to facilitate the
interaction between the LDAP server and the PHPNuke database.

The following is a summary of the areas affected by NukeLDAP.

1. admin/modules        - NukeLDAP management and language files added
2. images/admin         - NukeLDAP icon added
3. modules/Your_Account - modified index.php files
4. db                   - modified db.php and added ldap.php

In addition, changes may be required to the system if script
support is used and if the nuke.schema is used with your LDAP server.
The system has been tested with OpenLDAP and the sample files provided
are for this server running on Linux. It is suitable for other
LDAP environments as well but instructions and examples are not
provided here. Anyone knowledgable about the operation of their
LDAP server should be able to take the OpenLDAP examples and 
adapt them to their own server.

Settings are stored in the nuke_ldap table in the PHPNuke database. 
These settings are changed using the NukeLDAP administration page
that is accessible via an LDAP icon on the main administration page. 
The settings control the operation of the NukeLDAP support and the
access methods and structures used with the LDAP server. Typical
settings include the URI or IP address of the LDAP server, the
port used and the root name and password. For an OpenLDAP server,
these values are found in /etc/openldap/slapd.conf.

NukeLDAP hooks into Your_Account in the administration and user
index.php files. There are minimal changes and the function names
used are all prefixed with ldap_fn_ making them easy to find. They
are located in four major areas: user creation, user deletion,
password changing and authentication. Less than half a dozen
lines of code are added to these files. Make sure the changes
have been made appropriately to these files if the version of PHPNuke
you are using differs from the one used to supply the changes as
part of this package.

The NukeLDAP functions are called before or after PHPNuke performs
the matching function such as deleting a user. The functions perform
a similar operation but using the LDAP server. The main interaction
is via authentication. In this case, the user supplies their user
name and password. This is checked against the LDAP database. If it
is valid then the PHPNuke database entry for the user is modified
since the password may be different. This allows users to make
changes to their LDAP password using other means. If the user name
is correct but the password does not match then a random PHPNuke password
is set preventing the user from logging on.

This approach allows the PHPNuke system to utilize the password in
its native form independent of the LDAP support. The downside it that
any module with PHPNuke that changes the password will need to be
modified with NukeLDAP support. At this point, only Your_Account
makes these kind of changes. 

The interaction between the LDAP server and NukeLDAP is primarily
done using the user name and password. This typically match the
LDAP uid and userPassword fields. However, LDAP is very configurable
and there are different versions so the names of these fields may
differ. The NukeLDAP administration interface makes changing these
an easy task.


LDAP Basics:
You should be somewhat familiar with LDAP and objectclass'es. 
Essentially each type of LDAP entry is defined by a set of 
fields that are required or optional as specified by an objectclass
definition found in an LDAP schema file. A particular entry 
normally has a few objectclass definitions associated with it.

The two fields (uid and userPassword) can be specified by
one or more objectclass definitions that define a user LDAP
record. One of these objectclass'es may be NukeAccount.

The NukeAccount objectclass is provided in the nuke.schema
file. The OID number used is registered and should not conflict with
any LDAP definitions. The NukeAccount can be used and the standalone
samples utilize it to provide a simple LDAP structure. 

It is possible to use a different set of objectclass'es and not 
use the NukeAccount objectclass to allow a user entry to include 
the two required fields. This approach is often more desirable 
for systems that already have an LDAP server in place.

If you are just using LDAP for NukeLDAP then the samples provided
will be sufficient. If you are including other objectclass definitions
for services such as Samba then you will have to examine them a 
little more closely to see if you need to include the NukeAccount
definition for user entries or if you can get by without using
NukeAccount.

NukeAccount can interact with the system when creating user entries
in two ways. One is for NukeLDAP to create a user entry directly 
using parameters, including a list of objectclass'es, from the
NukeLDAP administration page or using scripts. The latter are
run outside of the web server process, whereas NukeLDAP works as
part of this process. The scripts are command line actions that
can invoke any program allowing you to customize the action
for your system. For example, the add script could create an
LDAP Samba user by calling the Samba LDAP support programs that
perform this function. The script can also provide logging
information. The level of complexity or simplicity is up to you
and your requirements as well as your script programming talents.
In general, simple operations can be done in a line or two of
text. The samples provided with NukeLDAP log actions such as 
creating a user in the operating system message log. 

The internal and scripting support can be used alone or together.
If you are not logging any information and you are using a basic
LDAP configuration like the one provided as an example then
you can get away with just using the internal support and 
never writing a script. The option is there if you need it.

NukeLDAP is transparent to users. If they change their password using 
PHPNuke then the change is reflected in the LDAP database. If this
database is used for other services such as Samba then the LDAP
server can provide single sign on support or at least consistent
passwords for different services. 


Installation:
The package is delivered in a TAR/GZIP format with a .tgz extension. It can
be extracted using a Linux command line like the following:

	tar -xzv <nukeldap.2.1.0.tgz

This creates a directory containing the documentation (this file), LDAP
sample files, an SQL table creation file and directories that contain
files that should be copied to the matching directory structure on most
Linux servers. In some cases, the latter should actually be done by editing
the matching files in the destination directories if the PHPNuke files
in the destination are from a different version or if changes or patches
have been applied. Here is a list of the directories that are provided.
Note, additional directories may be included in future releases. Some
of the directories may contain subdirectories and files that will 
normally be placed in a similiar spot on the server.

	etc/openldap
	html/db
	html/images
	html/admin
	html/modules/Your_Account

In the root directory you will find nukeldap.sql. This must be 
applied to the PHPNuke database server like the nuke.sql file 
used in its initial configuration. This is typically done using a 
database-specific command line like:

	mysql nuke <nukeldap.sql

The etc/openldap directory contains a sample slapd.conf configuration
file and the nuke.schema LDAP schema file. Check out the OpenLDAP
documentation or the documentation for the LDAP server you will be
using.

The html directory contains files for PHPNuke. All need to be copied
or used to determine the necessary changes to modify the files for
the version of PHPNuke you are using. Various text difference tools
can help identify where changes should be made. A general familiarity
with PHP is necessary to make changes. 

The html/db file contains the modified db.php file (one line change
to include ldap.php) and the ldap.php file that contains the
generic NukeLDAP support used in the Your_Account module and the
NukeLDAP administration interface. 

The html/images directory contains image files used by NukeLDAP.
These can be copied as they do no conflict with any other
PHPNuke components.

The html/admin directory contains the NukeLDAP administration 
files. These can be copied as is. There is an English language
file, ldap-lang-english.php, included with this package. You
can add more language files using this as a template and 
there may be additional ones provided in the future. 

The html/modules/Your_Account directory SHOULD NOT BE COPIED
unless you are using a matching, unmodified PHPNuke version
as noted above in the test system. Otherwise, you will have
to compare the files to see where changes have occurred and
copy just those lines associated with NukeLDAP into the new
files. The NukeLDAP lines can be identified because the
lines contain the string ldap_fn_. The two files involved
include index.php and admin/index.php.


Setting up the LDAP server:
If you are familiar with LDAP or have an LDAP server already 
running then you can probably skip over or skim this section.
This particular example assumes an new OpenLDAP server is
being configured.

Make sure the LDAP and web server are running. If you are using
a new LDAP system and you need to create a new set of LDAP records
then you can use the base.ldif file using a command line like:

  ldapadd -D cn=admin,dc=company,dc=com -w password -x -f base.ldif

This example uses the OpenLDAP ldapadd program. The parameters
must be changed to match your LDAP configuration. This also
assumes that the LDAP server is running on the localhost. It
is possible to use a remote LDAP server but you should make
sure that SSL is used as passwords are sent in cleartext
between NukeLDAP and the LDAP server.

The base.ldif sets up some base records including an organizational
group named 'people'. Using LDAP syntax, the base distinguished
name (dn) ou=peope,dc=company,dc=com. Remember, you need to make 
matching changes to the various example files if you are using a
different LDAP configuration. For example, if your domain is
foo.com then the prior example would look like ou=people,dc=foo,dc=com.
Corresponding changes would have to be made to slapd.conf and 
on the adminstration page. 

The base.ldif file does not add any users. This can be done using the
test button on the administration page or from PHPNuke once the 
system has been configured and tested.


Testing NukeLDAP: 
Once the LDAP server is running and the basic LDAP objects have
been setup then you can start acces the NukeLDAP administration page.
Log in as a super user and locate the LDAP icon on the top part of the
main PHPNuke administration page. This brings up the LDAP administration
page. Here you can change the settings to match your configuration. The
required fields at the beginning of the page are used to access the
LDAP server. There is a Test button that saves any changes you have made
and tries to access the LDAP server. The results are displayed at the
top of the page. 

Next, assuming you are not starting with the scripting support, comes the
user configuration. This includes the objectclass'es and and fields
that should be initialized when a new user is created. There is also
a test button in this section that is used to create and then delete
an LDAP user record. It does not use the scripting support and it does
not create a PHPNuke user. If the create step works but the delete
fails then you will have an LDAP user record setup that you may have
to delete manually using LDAP tools. 


Testing the NukeLDAP Scripting Support:
Once you can create and delete an LDAP user you can move onto the script
support. The example provided here is for Linux. The scripting
support should work under any operating system but the command line
syntax and program names will likely be different. NukeLDAP can
operate without the scripting support assuming the built-in 
LDAP management is sufficient. 

The default settings utilize the Linux logger program that
writes messages to the main log file. This can be useful for debugging,
monitoring the system or you can write scripts that invoke other
programs to provide support such as creating a Samba user or creating
a mail directory. This is beyond the scope of this document to you will
have to investigate the shell and scripting support for your operating system
if you do not already have this expertise.

If you are using the scripting support then check this out.
Add the following line (or something like it) to the /etc/sudoers file.

    apache  ALL=NOPASSWD: /usr/bin/logger

This assumes 'apache' is the user ID associated with the web server,
normally called httpd, and the program that can be run is /usr/bin/logger.
This type of support is not needed if scripting is not employed.

The execute program is one used to invoke any script. No script will be 
executed if the field is blank. You only need to have scripts for those
functions you want to handle using a script. If you need to execute
many actions or a complex set of actions then the scripting interface
can invoke the program or script file that does this.

The scripting support is best tested by creating and deleting users and
changing passwords with the scripts setup to log information as in the
default settings. You can experiment once these are working. 

There are check boxes in the middle of the administration page that
indicate just the script should be run for a particular action. This
allows those with expertise in scripting and LDAP support to perform
custom operations.


Instructions for use:
Once the system is configured and tested from the administration page
everything should work automatically and tranparently.


Notes:
The system is relatively complete. It does not currently replicate
other fields between PHPNuke and LDAP so it may pay to have a
user LDAP PHPNuke module so users can change LDAP attributes. This
is handy because an LDAP server is often used to provide an address
book capability to users. The user LDAP module may be done in the future
as part of NukeLDAP if there is enough demand.

The create user support is basic but sufficient for a number of 
applications that do not require special computation to be performed
when a record is created. For example, POSIX and SAMBA user LDAP
support requires linking user records to groups and generating 
user and group ID numbers. This cannot be done using the built-in
support in NukeLDAP but it can be done via scripting support. 



License: GNU General Public License
         See the COPYING file in this distribution for details.

Copyright (c) 2005-2006 by W. Wong (bwong at voicenet dot com)

Revisions:
2.2.0  02-03-2006   New test result page added, moved to production status
2.1.0  12-12-2005   Initial version using new architecture
                    and management interface

