PHP Classes

File: README.txt

Recommend this page to a friend!
  Classes of Mark Round   AuthLdap   README.txt   Download  
File: README.txt
Role: Documentation
Content type: text/plain
Description: Documentation
Class: AuthLdap
Simple LDAP Authentication and user access class
Author: By
Last change: Updated to cover version 0.2
Date: 20 years ago
Size: 10,365 bytes
 

Contents

Class file image Download
class.AuthLdap.php LDAP Authentication and basic User management class for PHP - version 0.2 http://www.markround.com/unix Contents 1. Introduction 2. License 3. FAQ 4. Changelog 5 . Usage and examples 6 . Detailed class reference 7 . Misc 1. Introduction This is the documentation for class.AuthLdap.php, a LDAP authentication and user management class for PHP. It provides a mechanism for easily authenticating users against an LDAP database, as well as extracting information, changing passwords and the like. It's not intended to be a full-blown all singing, all dancing LDAP access class - rather, it performs a few basic, frequently used functions. Everytime I undertake a project in PHP, I end up writing many utility classes to perform various functions, and this was one that I felt would be useful to the public in general, so here it is. It's very basic, and could do with optimisation in several areas, but as far as I know there are no major bugs. If you're looking for more information on PHP and LDAP, see the PHP manual on the php.net website - it's a superb source of information, and the user comments are very helpful. 2. License This class, and all associated documentation is released under the Gnu General Public License (GPL). A copy of this is included in the downloadable archive. All I ask is that if you find any bugs in the code, or have some improvements, that you send them back to me. Otherwise, feel free to do what you want with the code, within the limits of the license. Of course, an email saying that you're using the class would be welcome too - it'd be nice to know that people are getting some kind of use from this :) 3. FAQ As this class has not been publicly available for very long, there haven't been many FAQs. If you have a question about this class, please email me, and I'll do my best to answer your question and include it in later revisions of this documents. Q: What LDAP servers does this class work with ? A: It should work with nearly everything - LDAP being an open standard. However, I have only tried it with Sun's iPlanet Directory Server (now called "Sun One".) Version 0.2 includes changes made by Michael Joseph (michael@jamwarehouse.com) so that it works on Microsoft Active Directory. I have kept the specific implementation details easily changeable - read the usage documentation/source code for more examples. If you get it running on any other servers, please email me and let me know so I can update this documentation. Q: Are there any specific gotchas with this class ? A: Two spring to mind. For iPlanet,if you want users to be able to change their passwords, you'll have to create an ACL allowing them to do this ( and any other attributes you want to let them change). The iPlanet documentation should tell you everything you need to know. Secondly, Active Directory does not allow anonymous searching, so you will need to specify a username and password for an account with permissions to search the directory. You'll also need to set your domain - this is discussed in the documentation. Q: Does this class allow for the creation of users accounts ? A: No. It's primary purpose was to authenticate users, and then extra functionality got tacked on as the project progressed. However, the adding of users was done by a separate script so wasn't needed by this class. Q: I downloaded the class and the files are unreadable - there's no line breaks! A: You're probably on Windows, and have downloaded the Unix version instead of the Windows one. Go and grab the .zip file instead of the .tar.gz one. Q: Where can I get updated versions of this class ? A: New versions of this class will always be available from my website (http://www.markround.com/unix/) 4. Changelog version 0.2, 11.04.2003, Michael Joseph <michael@jamwarehouse.com> * - Added switches and workarounds for Active Directory integration * - Change documentation to phpdoc style (http://phpdocu.sourceforge.net) * - Added a constructor * - Added an attribute array parameter to the getUsers method * - Generated PHPDoc reference and included online and in package (Mark Round) 5. Usage and Examples This section will give a basic overview of some of the usage of this class. There are several more useful methods besides the ones discussed in this section, for more detailed information of each of these, please see the source code and the PHPDoc reference. 5.1 Initialisation and connecting to a LDAP server After including the script and creating a new instance of the AuthLdap class, you need to specify the LDAP servers you wish to connect to, and then you need to specify the base DN. After this is done, you can then connect to the server. This must be done before you can access any of the other methods. You specify the server(s) by creating a 2-dimensional array with a new "row" for each server you wish to connect to. If the class cannot connect to the first server, it will try the second, and so on. This is useful if you wish to have redundant servers in case one goes down. You can specify hostnames or IP addresses in this array - both will work (if you use hostnames, the web server obvisuoly must have some way of resolving hostnames.) Both the server and base DN attributes are set through the class properties $server and $dn respectively. For Active Directory, you need to set the server type, domain, and search user properties. All examples in the documentation are for iPlanet, as I do not have an Active Directory server to test on, however usage should be exactly the same assuming these properties are set. For more information, see the source code, or the PHPDoc files at www.markround.com/unix/ldapdocs/. Example: <? include "class.AuthLdap.php"; $ldap = new AuthLdap(); $server[0] = "10.1.1.1"; // Primary LDAP server $server[1] = "10.1.1.2"; // Replica LDAP server $ldap->server = $server; $ldap->dn = "dc=foo,dc=com"; // Base DN of our organisation if ( $ldap->connect()) {   echo "Connected OK!"; } else {   echo "There was a problem.<br>";   echo "Error code : " . $ldap->ldapErrorCode . "<br>";   echo "Error text : " . $ldap->ldapErrorText . "<br>"; } ?> 5.2 Authenticating users Authenticating users is done through the checkPass method. It takes two parameters, the username and plaintext password. This assumes that the users are stored under the "People" branch of your LDAP server. If this is not the case, you'll need to set the "people" property accordingly. You can only authenticate users AFTER connecting successfully to a LDAP server. Again, for Active Directory, you'll need to set a domain. Example : <? if ($ldap->checkPass( "username","password")) {   echo "Password OK!"; } else {   echo "Password check failed.<br>";   echo "Error code : " . $ldap->ldapErrorCode . "<br>";   echo "Error text : " . $ldap->ldapErrorText . "<br>"; } ?> 5.3 Changing passwords Assuming that the users have an ACL set on the LDAP server permitting them to change their passwords, this can be done through the changePass method which takes three parameters - their username, old password, and new password. Example : <? if ($ldap->changePass( "username","oldpassword","newpassword")) {   echo "Password change OK!"; } else {   echo "Password change failed.<br>";   echo "Error code : " . $ldap->ldapErrorCode . "<br>";   echo "Error text : " . $ldap->ldapErrorText . "<br>"; } ?> 5.4 Retrieving attributes Attributes can be retrieved using the "getAttribute" method. This will return an array of the returned values. Normally, there would only be one value returned, but some attributes may have several values stored in them - for instance, multiple email addresses. Example : <? if ($attrib = $ldap->getAttribute ( "username","mail")) {   echo "First returned email address : ".$attrib[0]; } else {   echo "There was a problem.<br>";   echo "Error code : " . $ldap->ldapErrorCode . "<br>";   echo "Error text : " . $ldap->ldapErrorText . "<br>"; } ?> 5.5 Closing the connection Once you have finished with your LDAP connection, you should close it down to free resources. This is done with the close() method, which takes no parameters. Example : <? if ($ldap->close()) {   echo "Connection closed!"; } else {   echo "Connection close failed.<br>";   echo "Error code : " . $ldap->ldapErrorCode . "<br>";   echo "Error text : " . $ldap->ldapErrorText . "<br>"; } ?> 5.6 Error handling This class will not generate fatal LDAP errors if a query encounters a problem. Instead, each method will return false if it encountered problems, and set the ldapErrorText and ldapErrorCode variables accordingly. It usually sets these to codes returned from the LDAP server, but in some cases uses an internal code of "-1", and some corresponding error text. For example, if it could not connect to the server, it obviously won't return a proper error code, so instead uses "-1, Could not connect to any server." In order to catch these errors, you should check what each method returns, as detailed in the examples above. If you wish to change the behavior of the class so it does produce fatal errors in some instances, you can remove the @ symbol before several LDAP calls - but this is recommended for advanced users only. Some common error codes returned when using iPlanet are : 19 - Account locked out (too many invalid login attempts) 32 - User does not exist 49 - Wrong password 53 - Account inactive (manually locked out by administrator) 6. Detailed class reference This section of the documentation is now depreciated. For a full reference guide to the class, see the PHPDoc generated reference at http://www.markround.com/unix/ldapdocs/ (or included in the downloaded archive) in conjunction with the annotated source code. 7. Misc Not much else to say here - just thought I'd give "props" to my Linux User Group for being such a great bunch of people :) If you're in the Surrey area of the UK, and want to meet up with fellow Linux users have a look at our website (http://www.surrey.lug.org.uk)