Web server minimum requirements
This scripts have been designed to work with PHP 4.x and PHP 5.x using the LDAP extension. LDAP is the Lightweight
Directory Access Protocol, and is a protocol used to access "Directory Servers". The Directory is a special
kind of database that holds information in a tree structure.
Installation on windows systems :
This extension can be added easily in most of the windows php release by uncommenting the following line in your php.ini :
In order for this extension to work, there are DLL files that must be available to the Windows system PATH :
libeay32.dll and
ssleay32.dll. This dlls can be downloaded from the
Openssl website.
On *nix system you will need to use the --with-ldap[=DIR] configuration option when compiling PHP to enable LDAP support.
The web server must be able to communicate with an Active Directory Global Catalog server meaning that if the
web server is hosted on a DMZ network you'll have to open TCP & UDP 389 assuming you'll use the ldap:// protocol
and/or TCP & UDP 636 to use the ldaps:// protocol.
Notes on Active Directory structure and LDAP
First of all I would suggest you to download and install the excelent and free
Softerra LDAP Browser.
This tool will allow you to easily open and browse your Active Directory. Additionaly, you will be able to see the schema
and the fields associated to the users / groups / computers.
The way your Active Directory is designed is important if you plan to use the User Browser. The best open organisation
( in my opinion ) is to create department or geographical Organisational Units to split users. Each OU can have
customised configuration ( Delegation, Group Policies ) and are easy to manage. If you are using a Windows 2003
Active Directory, you can drag-n-drop users from one OU to another.
In this example, the base path of the users is :
LDAP://OU=Users,OU=objects,DC=sunyday,DC=net. They are
organised by geographic locations. You can also see that users, groups and computers are splitted, this allow the network
administrator to delegate less power to the local administrators and to define special group policies depending on
the network speed.
If you have a flat Active Directory ( often the case in small networks with less than 50 users ), you will not be
able to use the User Browser.
Important note : If you are using a flat active directory ( all the users created in the Users build-in folder )
you'll not be able to create sub Organisational Units. Organisational Units can be created at the domain root or
inside an already existing Organisational Unit.
Script installation
All the
phpAD scripts are located in the
phpAD/ folder.
This folder must be uploaded on your web
server. If this folder is located at the same level of the pages calling it, you'll have nothing to change in
then javascript & php inclusion but if your are using a different folder structure, you may have to modify manually
all the javascripts and php path. This means for the javascript calls :
and for the php scripts :
Setting up the LDAP-Config.php file
The
LDAP-Config.php file contained in the
/phpAD directory is used by the scripts to retrieve configuration settings
for your domain. You'll have to edit manualy this file to reflect your Active Directory settings before using phpAD.
| $ldap_window_title |
User browser window title. |
| $ldap_def_string |
Default message when nobody selected ( User Browser ). |
| $ldap_server |
DNS name or IP address of the LDAP server. |
| $auth_user |
User name to use for binding on the LDAP server. |
| $auth_pass |
Password to use for binding on the LDAP server. |
| $ldap_dn |
OU containing users. In the previous screenshot it will be :
ou=Users, ou=objects, DC=sunyday, DC=net |
| $ldap_default_ou |
Default OU to open in the User Browser. ( if not specified ) |
| $ad_domain_name |
Name of the NT Active Directory domain. |
| $ldap_auth_file |
Name of the file containing folder security settings. To be used with the authentication script.
( see @.security file syntax below ) |
 |
Note that the $auth_user
and $auth_pass can be an account with very poor permissions ( domain user ) if you don't want to do administrative
tasks on the AD using the phpAD scripts. It is basically needed to browse the active directory and is mandatory. I recommend
you to create a service account with the "password never expire" option that will be only used to make the php<->AD connection.
|
This parameters will be used as default. Some of them can be override while calling phpAD functions.
Using the Active Directory authentication
Securing scripts and folders were the main purpose of phpAD. This documentation is assuming that you've installed
phpAD in the
/phpAD folder, if not review the include path. To force Active Directory authentication on
one of your web page, add the following code at the top of your php file :
|
For security reasons it is better to host your web application asking for authentication
on an https:\\ server. If you are running it from a http:// server, the username and
password will be sent in clear text and can be intercepted by a third party. See your
apache configuration to know how to setup an https site or vhost.
|
If you try to display this page, you'll get an authentication request poping-up a login window. This script is
compliant with HTML standards, this means that any application supporting web authentication ( HTTP/1.0 401 Unauthorized )
will be able with proper credential to retrieve the page. Note that you can also write your user name in the format
DOMAIN\Username.
The
Authenticate() function can accept parameters ( that will override phpAD.config.php ) :
Authenticate(string Real,string Description,string Redirect, bool UseSecurity)
Real and
Description are the values shown in the authentication box.
Redirect is the URL
where users that haven't been granted privileges will be redirected.
UseSecurity specify if we take care of
the
@.security files.
|
If no @.security files are present in the folder of the script, any user authenticated
with the Active Directory will be granted read privilege to the page.
|
@.security files
This files can be described as an adaptation for our LDAP needs of the famous
.htaccess file. It can contains
authentication rules that will be applied after the user login is validated against the Active Directory. By using
@.security files you will be able to apply per user / groups permissions to one folder. The syntax is pretty
simple, using two operators + to authorize, minus to explicitly deny :
The value following the symbol + or - is an LDAP field that is searched in the logged on user properties. The
logged on user will be compared with the values between brackets ( multiple values can be specified, delimited
with a semicolon ). In this example, only the person that are authenticated on the Active Directory and have
a samaccount name of
administrator or
roland or are present in the group
Web_Access will
have access to the page. An exception is made if the samaccountname is
omar. Users that are authenticated
but who aren't matching this criterias will be redirected to the page
$phpAD["auth_error_page"] ( see
phpAD.config.php )
Securing @.security files
Be carrefull to deny access to your
@.security files from web clients. If an hacker is able to read this file,
he will be able to know the requirements to get access to this folder ( AD Groups, Usernames, .. ). To do so ( and
assuming that you've kept
@.security as security file ), add the following lines to your
httpd.conf :
You'll need to restart apache after this changes.
Using the User browser
The User Browser allows you to easily add to your web applications an user selection box. You can choose the
fields that you want to display ( eg : User ID, Full Name, Mail... ) and directly retrieve the
results in your HTML forms. Before using the browser in your application you must configure your
phpAD.config.php
file ( see
Setting up the LDAP-Config.php file ).
Here is a sample of a basic application of the User Browser ( you can see a sample
here ). Add this one time :
.. and the following for each input box of your form that you want to link with the AD :
In this example, clicking on the
"Pick in the AD" link will popup a window displaying the users contained
in the default OU ( see "ldap_default_ou" in the configuration file ). The first parameter define in which
input box to put the result of the user browser ( should be the same as the
ID= field of the INPUT text
field ). The second parameter define the value to be returned :
- 0. LastName FirstName OU ($Account) eg : POGOLOTTI Jean-Damien FRANCE (jd)
- 1. LastName FirstName
eg : POGOLOTTI Jean-Damien
- 2. DOMAIN\UserID
eg : SUNYDAY\jd
- 3. Mail
eg : jd@sunyday.home
The last parameter defines the second column that will appears in the User Browser, in this example, it will display
the user's description. You can use any Active Directory LDAP field.
|
You can instanciate as many User Browser as you want but don't forget to set an unique ID for each INPUT fields. This
is the only way for the script to determine where to store the result.
|
Using the forms fields validator
The Forms field validator allow you to use Ajax like technology to validate the fields of your web forms with the
Active Directory contents. For example, if you want the user to provide an email address, you can validate that this
address is belonging to someone in your organisation.
To use it, insert the following code once :
.. and for each form entries :
In this sample by clicking on the
Validate link, you'll check in the Active Directory ( assuming your
phpAD.config.php is correctly filled ) if the email is existing. The validator is using wildcards to compare
the field in the Active Directory and will complete the user choice is if is not clearly found. Note that you
must use two identifier : one for the text field itself (
E_Field ) and one for the DIV containing the
link (
E_Div ). This two ID must be unique on your entire page.
The
Validate() function accept 3 parameters :
Validate(string TextFieldID,string LDAPField,string DivID)
Where
TextFieldID is the identifier of the text field,
LDAPField is the LDAP field that you want
to compare in the AD. ( samaccountname, mail, .. ) and
DivID is the identifier of the DIV element.
Overriding configuration file
The configuration file
phpAD.config.php is intended to contains global configuration that
will be applyed to any web pages. In some cases you may want to have specifics settings on a page
( the LDAP Server, Active Directory domain, ... ). You can override this settings using
this kind of script :
This will allow you to make a per page configuration.
Script installation // Integration
