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 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.
First of all I would suggest you to download and install the excelent and free . 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.
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 :
- 'path/to/phpAD/LdapBrowser.js'?>
and for the php scripts :
- include("path/to/phpAD/phpAD.config.php");
- include("path/to/phpAD/phpAD.php");
- ?>
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.
![]()
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 :
- include("phpAD/phpAD.config.php");
- include("phpAD/phpAD.php");
-
- Authenticate();
- ?>
![]() |
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 :
- +samaccountname[administrator;roland]
- +memberof[CN=Web_Access,OU=France,OU=Groups,OU=objects,DC=sunyday,DC=home]
-
- -samaccountname[omar]
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 :
- "^\@.security">
- Order allow,deny
- Deny from all
-
You'll need to restart apache after this changes.
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 ).
Here is a sample of a basic application of the User Browser ( you can see a sample ). Add this one time :
.. and the following for each input box of your form that you want to link with the AD :
- User ID :
- 'javascript:OpenLDAP("UserList",2,"description");'>Pick in 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. |
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 :
- Email :
- 'E_Div'>
- 'javascript:Validate("E_Field","mail","E_Div");'>Validate
