OpenID-LDAP-PHP 
***************
An open source PHP-based OpenID IdP package using LDAP as backend.
      

By Zdravko Stoychev <zdravko (at) 5group (dot) com> aka Dako.
Copyright 1996-2011 by 5Group & Co. http://www.5group.com/
See LICENSE file for more details.

This work is based on CJ Niemira's phpMyID - A standalone, single user, OpenID 
Identity Provider, version 0.8, home page: http://siege.org/projects/phpMyID.

OpenID-LDAP-PHP is a small, fairly lightweight, standalone, multi user Identity
Provider for OpenID authentication. It comprises a few PHP scripts that can be
used by one individual to run their own personal OpenID IdP.

This program requires no external libraries, and has very minimal requirements.
It should run on any PHP server (v4.2+), and can support OpenID in 'Smart Mode.'
This program caches all data using built-in PHP session handling, so it requires
no database, and no explicit write access to the file system.

OpenID-LDAP-PHP is NOT compatible with Suhosin or other hardened PHP systems 
(Debian users take note).

NOTE: User authentication is done using HTTP Basic authentication, so your 
      password is transmitted over the wire in plain text, base64 encoded. Thus 
      we STRONGLY RECOMMEND using SSL for your hosting (https://yourdomain.com)
      
      In fact, if you are not using SSL the Authorization OpenID mode *will*
      fail with an error message. Since OpenID-LDAP-PHP version 0.8.7 you are
      required to use SSL connection.

      'Smart Mode' OpenID authentication requires the use of "big math"
      functions. If you do not have bcmath or GMP available, you can use a built
      in pure-PHP "big math" library, but it is not very efficient. You are
      encouraged to use bcmath if at all possible.

      No MySQL or any other database is required. This software does not use a 
      backend database by design! It uses a LDAP server tho, to fetch users data.
      Currently OpenID-LDAP-PHP does not provide any way for creating or
      editing user accounts. You have to use some other way to perform this.

      There's no reason that OpenID-LDAP-PHP should not work under IIS.
      
      It is proved that OpenID-LDAP-PHP works fine with Microsoft Windows Server
      and Active Directory user accounts.


FOR MORE INFORMATION ON OpenID, PLEASE SEE http://openid.net/


************
INSTALLATION
************

OpenID-LDAP-PHP can be installed on just about any PHP server. It is recommended 
that you use a server that you own and control.


1) Decide how you want to install OpenID-LDAP-PHP. It requires at least few files, 
   and can be installed in a number of ways. The files you will be uploading are
   
   - installation root folder:

     engine.php		The application library

     showme.php		Username to URL redirection library

     index.php		This is the file you'll be visiting in your browser

     ldap.php		The LDAP-link library, contains creds, and options
   
     style.css		Some CSS formating definitions
     
   - into images directory:
   
     logo.gif		The OpenID logo and text, plus LDAP, on white background
   
     openid.ico		A small OpenID logo icon (can be placed in root folder
                        and renamed to "favicon.ico", see * notes bellow)
   
     openid.gif		The OpenID logo on white background
   
     openid.png		The OpenID logo with transparent background
   
     openid-logo.gif	The OpenID logo and text on white background
   
     user.gif		A small person image
   
   Please keep the directory structure while uploading files. Do not store all
   files in one location unless you want to edit source files respectively.


2) Upload the files. That's right, just upload 'em. Put 'em wherever you want. 
   I suggest your root URL, but you can do whatever you need to make them web
   accessable, as long as you can figure out what the URL should be.


3) Visit your upload location in a web browser. You should see a message that
   says "This is the <company> OpenID provider home page." You should also see
   some welcome message and help links.

   If you don't see all of these things, proceed to the Troubleshooting section
   of this document.


4) If your "Realm" is anything other than the string 'OpenID' (like say, if it
   has a number after it) then make note of the value. This means that PHP is
   running in "safe mode," and while I disagree for the reasons they change the
   realm, there's nothing I can do about it.

   Edit your config file, and change the key "auth_realm" to reflect the "Realm"
   value displayed in your browser. The default is 'OpenID' and it only needs
   to be changed if the string you see in your browser is something different.

   If you're going to want to change this to some custom value just edit the 
   "auth_realm" key to read whatever you want. Remember, however, that you need 
   to double check your realm value by visiting MyID.config.php in a browser after 
   you make the change (and upload it). 


5) Now you get to configure your LDAP connection settings. Edit ldap.php file
   and set up your Primary and secondary (Fallback) server names or their IP
   addresses. Also provide BindDN and Password to connect to servers.
   
   SearchDN is a root where users shall be looked up. The entire subtree will 
   be searched using Filter setting. Note that it contains '%s'; that's where
   the username will be substituted before performing the lookup. For more
   information about LDAP search filters, go to 
   http://confluence.atlassian.com/display/DEV/How+to+write+a+LDAP+search+filter
   
   And finally, TestDB setting is similar to Filter one, except it describes 
   the DN of the user which tryes to login. It is needed in order to validate 
   provided password. The '%s' will be replaced with provided username.
   
   Fill names matching between OpenID Simple Registration and LDAP fields.


6) Upload modified files again, replacing the ones that were already there.

   Visit upload location in a browser again, or refresh the current page. The
   output shouldn't change, you're just looking to be sure there are no errors.

   Be certain that the 'Realm' listed exactly matches the value you used when
   you created your password hash in step 5.
   
   Enter your LDAP username into text-edit field and click "Enter" button. For
   example, the URL shall now be "https://yourdomain.com/some/path/username".
   
   You should see a welcome message saying your fullname and your OpenID URL. 
   If an error message is displayed or "User not found in our database, sorry."
   text is shown, then go back and edit your ldap.php file again.
   
   If you still can't get trought it, proceed to the Troubleshooting section.

   Click 'Login' - you should be redirected a couple of times and then presented
   with a login dialogue box. Enter your username and password and click ok.
   Again, you should be bounced around for a sec, then get a message which says
   you're logged in as whoever your username is.

   If you can't log in, if you get an error, or if doesn't work in some other
   way, proceed to the Troubleshooting section.


7) Now, you are logged in, click "Continue" to return to your Identity Provider. 
   This is the URL you must use to authenticate as to any OpenID-enabled site,
   as this is your personal OpenID.
   
   If you wish to use another URL (owned by you), instead of this one, then use 
   the above link as your openid.server and the new URL as openid.delegate.

   The preferred way of setting this up is to determine the URL you wish to
   authenticate as (for example "http://myblog.org/"), and add the following
   to the HTML <head> section for that document:

    <link rel="openid.server" href="https://yourdomain.com/path/username">
    <link rel="openid.delegate" href="http://myblog.org/">

   You may now use your URL http://myblog.org/ with OpenID-enabled sites.
   

8) Remember, you have to run this package under SSL in order to protect user
   passwords. OpenID-LDAP-PHP generates OpenID for each LDAP user in form:
   
   https://yourdomain.com/some/path/username

   This requires some changes in you Apache configuration. We'll use mod_rewrite 
   features and put these settings into your ssl.conf file - in general host
   section, or in some virtual host one, depending of your configuration.

   First, you might want (highly recommended) to redirect all non-SSL requests
   via SSL. Add this to your "httpd.conf" file:

   RewriteEngine On

   RewriteRule   ^/dir$         https://host/dir/      [R=permanent,L]
   RewriteRule   ^/dir/$        https://host/dir/      [R=permanent,L]
   RewriteRule   ^/dir/(.*)$    https://host/dir/$1    [R=permanent,L]

   Next, add this to your "ssl.conf" file to proxy usernames to internally 
   processed requests to index.php script:

   SSLProxyEngine On
   RewriteEngine On

   RewriteCond %{REQUEST_URI}      !^/(.+)\.php(.*)$
   RewriteCond %{THE_REQUEST}      ^[A-Z]{3,9}\ /dir/([A-Za-z0-9]+)\?(.*)\ HTTP/
   RewriteRule ^/dir/(.*)$         https://host/dir/index.php?user=%1&%2    [P]

   RewriteCond %{REQUEST_URI}         !^/(.+)\.php(.*)$
   RewriteRule ^/dir/([A-Za-z0-9]+)$  https://host/dir/index.php?user=$1    [P]
   
   Make sure you replace 'host' and 'dir' above with corresponding values from
   your setup (i.e. 'yourdomain.com' and 'some/path', for example).

   The SSL host definition must be using the IP and not the hostname. It
   should look like: <VirtualHost 192.168.1.1:443>. If you fail to do so
   you may spend quite some time why mod_rewrite is doing nothing.

   Don't forget to change in httpd.conf: "AllowOverride None" to
   "AllowOverride All" (it may appear several times).

9) Set right permissions to ldap.php file because it contains your LDAP password
   
   $ cd /var/www/ssl/some/path
   $ chown root.apache *
   $ chmod 644 *
   $ chmod 640 ldap.php


*) Additional notes:

 - Using favicon.ico in your webserver root folder could require a change to
   your apache.conf file. Add this line to it, if its not there already:

   AddType image/x-icon .ico

   then restart the httpd service and reload the page in your browser.

 - Running PHP under Windows, by default, stores sessions in a directory called
   "sessions" in the PHP directory. However, this directory doesn't exist in the
   distribution, and it won't be created, so sessions fail and OpenID-LDAP-PHP 
   won't allow logins. So for phpmyid to work, an empty directory called "sessions"
   needs to be created in the php installation directory.

 - Connecting to Active Directory is enabled by default and could be disabled by
   setting $ldap['isad'] setting to 'false'.


#####
USAGE
#####

There isn't much to using OpenID-LDAP-PHP other than pointing at it, and logging 
in. If you wish, you can log out by visiting:

   http://yourdomain.com/some/path/username?openid.mode=logout

There is also a 'log in' mode that will prompt you for credentials without
having to be referred from a client site.

   http://yourdomain.com/some/path/username?openid.mode=login


####################################
SIMPLE REGISTRATION EXTENSION (SREG)
####################################

OpenID features something called 'sreg' which is a way to supply commonly
requested personal information to any site which you log into. Typically, a
client site uses this to create your profile the first time you log in. This
'sreg' information comprises such things as your nickname, email address, time
zone preference, etc...

All of the SREG keys are optional. To enable the use of any of them, simply
edit ldap.php file and supply name matching between SREG and LDAP attribute,
corresponding to that key. If you don't feel like supplying a particular detail, 
just leave it commented out, or empty. Note that these settings are common for
all LDAP users.


####################
ADVANCED CONFIG KEYS
####################

Several other configuration keys exist and can be set in the 'profile' array:

'allow_test'	If set to true, this key will allow OpenID-LDAP-PHP to run a special
		test mode. Set the key to true, and visit your IdP url. You
		should see a "Test" link that was not previously available.
		By clicking it, OpenID-LDAP-PHP will conduct a series of tests designed
		to validate the functionality of the internal signature and
		math functions. This information is useful for troubleshooting.

'auth_realm'	You can configure the name of the realm you are prompted to log
		into during authentication. Remember, if you change this value,
		you will have to adjust your 'auth_password.'

'debug'		If set to true, OpenID-LDAP-PHP will do perform debug logging. If you 
		turn this on, you are strongly encouraged to also set the key
		'logfile' to explicitly set the path to your debug log. If not,
		OpenID-LDAP-PHP will attempt to automatically ascertain the correct
		location to put a 'OpenID-LDAP-PHP.debug.log' file, and will cause an
		internal error if it cannot write to that location.

'idp_url'	This key defines the identity that OpenID-LDAP-PHP will allow 
		you to claim. It is almost always set correctly by default.

'logfile'	When the 'debug' key is true, this key is used to define the
		absolute path to a debug log.
		
'force_ssl'	When writing openid.server and openid.delegate into HTML <head>
		section, always use SSL (https) protocol, if this key is 'true'.


######################
# OPTIONAL CONFIG KEYS
######################

'microid'	If you would like OpenID-LDAP-PHP to assert your ownership via 
		MicroID tags, you can configure this key (either as a string or an
		array). Any values must be complete URI to the asserted owner.
		One suggestion is to enter the value of the URL you are
		delegating from (installation step 7). You can also use your
		email address. In either case, be sure to prefix your URI
		correctly with "mailto:" or "http://" etc...

'pavatar'	If you would like OpenID-LDAP-PHP to assert your ownership of a 
		Pavatar by embedding an optional image tag into its HTML document
		header, you can configure this key. The value set should be a
		complete URL to your Pavatar image. See http://pavatar.com
		for more information.


##########################
# EXPERIMENTAL CONFIG KEYS
##########################

'paranoid'	Part of the OpenID specification requires clients to ask the
		identity servers to trust a specific root URL for all identity
		transactions. OpenID-LDAP-PHP ignores this requirement by default
		in favor of a speedier and more fluid login for users, however,
		you can a "paranoid" mode that will allow you to receive prompts
		to trust each client as you log in to them.


###########################
REALLY ADVANCED CONFIG KEYS
###########################

'allow_gmp'	When set to true, the GMP (Gnu MP Bignum library) extension,
		if available, can be used for big math calculations (ie
		encryption, or "Smart Mode").

'auth_domain'	This is the domain value used in the HTTP Basic authentication.
		It defaults to your idp_url (see above).

'force_bigmath'	If set to true, the internal pure-PHP big math library will be
		used to ensure "Smart Mode" is always available, even if neither
		bcmath nor gmp extensions can be used. Note that using this may
		result in a severe performance degredation for your system. You
		should only switch this on if you *really* need to use "Smart
		Mode," and cannot otherwise get bcmath or gmp installed on your
		system.

'lifetime'	This key defines how long an OpenID session is valid for. The
		default value takes into consideration both the internal PHP
		session lifespan as well as the default frequency of garbage
		collection on your system.


###############
TROUBLESHOOTING
###############

*) Can't log in while running OpenID-LDAP-PHP under IIS

   By default, PHP for Windows ships in such a way that sessions do not work 
   correctly out of the box. You will need to create a folder called "sessions"
   in your PHP installation directory.

*) Received error: "This site is not compatible with 'suhosin'"

   Suhosin is a security add-on for PHP which, amongst other things, removes
   PHP's ability to open and access multiple sessions at one time. Simply put,
   OpenID-LDAP-PHP is reliant upon this feature, and will therefore not work with
   a hardened PHP.

   Some users have reported successfully using OpenID-LDAP-PHP with suhosin, 
	either by modifying the script, or using an alternate webserver (such as 
	lighttpd). These solutions are unsupported. There is currently no official 
	support for OpenID-LDAP-PHP with suhosin.


*) Received error: "Missing expected authorization header."

   OpenID-LDAP-PHP must be able to read http request headers which are only 
   available if PHP is running as a webserver module. If you are using PHP 
   in CGI mode, you must convert the HTTP 'Authorization' header into an 
   environment variable ("PHP_AUTH_DIGEST") or query parameter ("auth") that 
   can then be used to perform the authorization.

   If you are using Apache, the included 'htaccess' file contains three examples
   of how you can use mod_rewrite or mod_setenvif directives to set the
   necessary variable. If you need to use this technique, it is recommended
   that you place OpenID-LDAP-PHP in its own directory, isolated from the rest 
   of your web site.
   
   
*) Received error: "User <name> not found..." no matter what name I provide.

   Check your ldap.php connection settings, again. Also try it out at the
   command prompt, if it works?
   
   $ ldapsearch -s sub -x -h <ServerIP> -W -D <BindDN> -b <SearchDN> <Filter>
   
   You could try lookup your own user account. Note that the returned result
   should be only 1. If for some reasons the results are more that one, it
   wan't work.


*) Why does/doesn't my Server string have "www." in it, my URL does/dosen't?

   If your ServerName is set to one value (in your webserver configuration)
   and you regularly access it with something else (say, an alias or w / w/o a
   www on the front of it), OpenID-LDAP-PHP may get confused.

   The easiest way to remedy this situation is to explicitly set the "idp_url"
   key in your profile array. The value should be the exact, complete URL, to
   your installation of OpenID-LDAP-PHP.

	$GLOBALS['profile'] = array(
		...
		'idp_url' => 'http://yoursite.com/index.php',
		...
		);


*) Still can't figure it out?

   Sometimes the unexpected happens. Sometimes bugs creep into the code. For
   all these times, check if you're using the latest version at:

   http://www.openid-ldap.org/


EOF