$Id: README,v 1.3 2001/10/12 17:04:14 mdruilhe Exp $

This directory provides a mechanism for allowing w-agora to authenticate
users from some external source, such as an LDAP directory for example.

A user source is a database of users the w-agora uses to authenticate and get information about users.
		The default user source is the built in w-agora database.
		
This directory ("user") contains user sources, one file per source.
Each user source defines some simple methods to authenticate and retrieve users
from its database.

Agora takes a copy of the user returned from the user source and updates its local
database, adding any user fields that may not have been returned from the user
source.

To configure another source you have to create a new file in this 
directory containing a certain class and certain functions.
The following is a template for the file.

 NOTE: filename must be "<something>_user.php3"
       class name must be "<filename>_source"

 for example: xxx_user.php3
             class xxx_user_source

There is an example file that shows how w-agora might be made to use users from am
LDAP directory, for example.


Alastair Foreman

//----------------------------------------------
//
<?php

if (!defined("_AUTH")) {
        include ("$inc_dir/auth.$ext");
}

class <fill in the filename here>_source extends wa_Auth {

//--------------------------------------------------------------------------	
function getRegisterURL() {

/*
	This function returns the URL of the "register user" page 
	for this user source.
	If it returns nothing then the built-in agora page is used.
	If it returns "" then this feature is disabled.
*/

}
 

//--------------------------------------------------------------------------	
function getEditProfileURL() {

/*
	This function returns the URL of the "edit user profile" page 
	for this user source.
	If it returns nothing then the built-in agora page is used.
	If it returns "" then this feature is disabled.
*/

}


//--------------------------------------------------------------------------	
function getForgotPasswordURL() {

/*
	This function returns the URL of the "forgot password?" page 
	for this user source.
	If it returns nothing then the built-in agora page is used.
	If it returns "" then this feature is disabled.
*/

}
 

//--------------------------------------------------------------------------	
function getChangePasswordURL() {

/*
	This function returns the URL of the "change password" page 
	for this user source.
	If it returns nothing then the built-in agora page is used.
	If it returns "" then this feature is disabled.
*/

}
 

//--------------------------------------------------------------------------	
function getLoginURL() {

/*
	This function returns the URL of the "Login (Authentication)" page 
	for this user source.
	If it returns nothing then the built-in agora page is used.
	If it returns "" then this feature is disabled.
*/

}
 

//--------------------------------------------------------------------------	
function encryptPassword($password) {

/*
	This function encrypts passwords for this user source.
	The result is stored in a cookie (by agora) and is passed to 
	authenticateUser() below.  The minimum behaviour would 
	returning $password (unencrypted).
*/

}
 
//--------------------------------------------------------------------------	
function getLoginInfo () {

/*
	This function returns the login information. For example it can be used 
	to authenticate using a session id, a cookie, or HTTP basic authentication
	It is called if the w-agora authentication method (currently cookie) fails.
	 The return value is an associative array with the following contents:
		"userid" => User ID (required)
		"clearpw" => clear Password (if known)
		"encryptedpw" => encrypted Password (if accurate)

*/

}
 


//--------------------------------------------------------------------------	
function authenticateUser($site, $userid, $encryptedpw) {

/*
	This function retrieves the user from the source using
	the given (encrypted) password. It must fills in the local associative array 
	$this->user with as many of the following fields as possible:
		"userid",		// login             REQUIRED
		"password",		// password
		"username",		// Name + firstname  REQUIRED
		"name",			// User name
		"firstname",		// First name
		"useraddress",		// email	     REQUIRED
		"homepage",		// Home Page URL
		"details",		// About me
		"mailok"		// Is it ok to mail user?

	If not all values can be retreived from the external source, 
	you should merge the array with the fields retreived from the
	w-agora user database. (see the ldap_example.php file for an example).

	You can add extra fields to this array as required.  You could 
	access these new values for display via custom templates.

	Note also that by making the parameters for this function passed
	by reference (&$site, for example), you can modify the behavior
	of agora.

	This function returns false if authentication fails
*/

}

}; // end class
?>
