  $Id: README_http_auth.txt,v 1.1 2003/06/24 23:42:17 mdruilhe Exp $
 
  ===========================================================================================
                      
      Installation and Usage instructions for HTTP Basic authentication in w-agora 4.1

  ==========================================================================================



I. Package content and description
----------------------------------

This package contains the following files :

  doc/README_http_auth.txt   This file
  user/http_user.php    User source class for HTTP Basic authentication

This package adds a new user source called "http" in w-agora. It permits
users identified thru the WEB Basic authentication to be automatically registered 
(with a userid + a default email address) and authenticated in w-agora.

Notice that the authentication itself is done externally to w-agora and can rely on various 
authentication modules such as Basic Authentication (mod_auth apache module), 
PAM (mod_auth_pam apache module), Windows authentication, or whatever your WEB server 
is configured, assuming that the REMOTE_USER variable is set properly.

This module has been tested with Apache and IIS5.


II. Package installation and configuration
------------------------------------------

Extract this package into your w-agora installation. For Unix/Linux users,
this may be done by the following commands :

     cd /to/your/w-agora
     tar zxvf http_user-1.0.tgz

For Windows users, just extract the archive using winzip other your w-agora installation

The "HTTP Basic" user source requires that the web server is configured so that the access 
to the w-agora pages are restricted to authenticated users.

The following sections describe how to achieve this on various platforms.


a) Configuration for Apache
   ------------------------

The authentication must be configured either in the apache configuration (<Directory>) or 
in a .htaccess file

Example of apache configuration :
---------------------------------

AuthUserFile    /path/to/your/.htpasswd
AuthGroupFile   /dev/null
AuthName        w-agora
AuthType        Basic

Require valid-user

-------------------------------------


b) Configuration for IIS on Windows
   --------------------------------

The authentication must be enabled for the w-agora directory thru the IIS control panel.

- In the Internet Information Services snap-in, select the w-agora root directory 
and open its property sheets. 
- Select the appropriate Directory Security property sheet. 
- Under Anonymous Access and Authentication Control, click Edit. 
- In the Authentication Methods dialog box, select one or more appropriate methods. 



III. Using the HTTP Basic user source
-------------------------------------

Create a new site as usual and select  "http" in the "User source" menu
("Validering" in Danish, "Gestion des utilisateurs" in French, etc.). Create
the forums of this site.

When a user access a w-agora page, the following happens :

- The WEB server send an "Authentication Required" message to the client browser 
causing it to pop up a Username/Password input window. 

- Once the user has filled in a correct username and password, the same w-agora page will be called 
again with the variable $REMOTE_USER set.

- if this userid is not already registered in the list of users of
  this site, automatic registration is done using the userid/password (see section IV below)

- the user is identified, no password is checked.

- The user can later change his profile (username, email, ...)


IV. Customizing the HTTP Basic user source
-------------------------------------------

When the "HTTP Basic" module attempt to register a new user, it must set a 
valid userid, username, password and email address, because these fields are required 
by w-agora to register a user.

Since the only information available is the userid (the password is also available in case
of Basic authentication), the following method is used to set the other fields :

- The userid is pulled out from the REMOTE_USER server variable.
 Notice that the NT domain is eventually stripped (eg.NT-DOMAIN1\joe" becomes "joe")

- The username is set to the userid

- If the (clear) password can not taken from the PHP_AUTH_PW server variable then a 
random password is generated. This should not cause a problem since the authentication is always 
done externally.

- the email address is obtained by the concatenation of the userid and the server's domain name

This behaviour is controlled by two PHP functions located in the
user/http_user.php script.

getUsername()      Returns the user name of the authenticated user.

getUseraddress()   Returns the email address of the authenticated user.


V. Pitfalls
-----------

- The GUI of W-Agora handles user sources only when creating sites. Thus
there is no web form which permits you to change the user source for
an already existing site. This should be done manually by editing the
the $bn_usersource variable in the various configuration files of
your site.

- The "Login" link has been disabled, so it is not possible to re-identify yourself 
to a site using another userid. 

--
Marc Druilhe <mdruilhe@w-agora.net>, June 2003.
