[geeklog-cvs] Auth_Enterprise/doc README.txt,NONE,1.1

[jellybob at iowaoutdoors.org]

Update of /var/cvs/Auth_Enterprise/doc
In directory www:/tmp/cvs-serv31121/doc

Added Files:
	README.txt 
Log Message:
Major changes to the API everywhere.

The README is currently out of date, to find out how to use the new API
please check doc/examples/

Some features are currently untested, and may not work.


--- NEW FILE: README.txt ---
!!!WARNING!!! 
Much of the installation information in this document is out of date.
To see how to set things up please see the example folder, which contains a basic example
of using both the Localhost and XML-RPC clients with a PEAR DB server.

Auth_Enterprise README.txt
$Id: README.txt,v 1.1 2004/07/08 14:36:17 jellybob Exp $

CONTENTS
--------
- About Auth_Enterprise
- System Requirements
  - Client Requirements
  - Server Requirements
  - Database Requirements
- Auth_Enterprise Server Installation
- Auth_Enterprise Client Installation
- Common Installation Problems
- Support

About Auth_Enterprise
----------------------
Auth_Enterprise was built to provide a solution to any enterprise for managing authentication and
authorization.  My many years in the IT field became frustrating when I got tired of each
application I was involved with managing user accounts and access rights all in different ways.
Worse yet, applications deployed within the enterprise all require seperate sets of credentials
making it tough for users to manage.  On another level, Auth_Enterprise attempts to tackle other
related issues such as account creation, password recovery and more advanced things like single
sign-on.

What makes Auth_Enterprise an enterprise solution is the fact it can support applications written
in any language and, in fact, this distribution ships with clients for PHP5, PHP4, Java and C#.
Because the core of this system is open source, it is easy for those wishing to port the client
to other languages beause the client is truly a thin layer.  Another enterprise feature worth
noting is Auth_Enterprise applications can communicate with the server over differnt protocols.
Right now XMLRPC and SOAP are supported and the architecture is such that the server (and client)
can be expanded to talk over other protocols.

Finally, the true power of Auth_Enterprise is it's ability to authenticate against a variety of
datastores.  By default we support PEAR::DB supported databse, LDAP or Active Directory.  Custom
providers can be easily added.

One final note is that Auth_Enterprise allows applications to do authentication, authorization or
both.  I mention this because it may be easier for some to simply start with the authentication
features and worry about adding authorization later.  

System Requirements
--------------------

Client Requirements
--------------------
- PHP5 Client
  - Stable version of PHP5
  - PEAR's base packages (installed by default).  The specific packages needed are:
      - PEAR::DB, PEAR's database abstration layer
      - PEAR::XML_RPC, only needed if you want to talk to the remote server over XML RPC
  - If using SSL you must have --with-ssl and --with-curl compiled into your PHP installation
  
- PHP4 Client
  - Stable version of PHP4
  - PEAR's base packages (installed by default).  The specific packages needed are:
      - PEAR::DB, PEAR's database abstration layer
      - PEAR::XML_RPC, only needed if you want to talk to the remote server over XML RPC
  - If using SSL you must have --with-ssl and --with-curl compiled into your PHP installation
  
- Java Client
  - TBD
  
- C# client
  - TBD
  
Server Requirements
--------------------
- PHP5
- Servers using Auth_Enterprise's LDAP providers must compile PHP with the --with-ldap option
- The following PEAR modules (see http://pear.php.net):
    - PEAR::DB, always required
    - PEAR::XML_RPC if you plan on using the XML RPC support.
- NOTE: the use of SSL is strongly recommended if you have an application that will be accessing
  the Auth_Enterprise remotely.  You will need to implement SSL on the chosen protocols (i.e.
  XMLRPC, SOAP, etc).
  
Database Requirements
----------------------
In most cases you will need to have a database that is supported by PEAR::DB even if you don't
want to use something other than the database for authentication.  That is because, by default,
the providers shipped with Auth_Enterprise use a database for storing user privileges.  See the
list below for the requirements of supported DBMS's.

- MySQL user's must have at least version 4 and have INNODB enabled as Auth_Enterprise makes us
  of SQL transactions.  Your MySQL installation must also support foreign key constraints.

NOTE: we are always looking for more DBMS's we can support.  If you port the Auth_Enterprise DDL
to one we haven't supported yet, by all means share it so we can include it in the distribution.
  
Auth_Enterprise Server Installation
------------------------------------
 - As you probably already did, you install this package by using the pear command included with
   most PHP4 and PHP5 installations. Again, you have to have PHP5 on the server you are running
   the service on.  The exact command to execute is "pear install Auth_Enterprise" or, if you are
   installing a beta, "pear install Auth_Enterprise-beta".
 - You will then need to create a database and import the data structures.  As of right now only
   MySQL is supported but we plan to add new DBMS's after we reach an release candidate status.
   The SQL to import is in /path/to/pear/Auth_Enterprise/Server/sql/.
 - Once you create your database you will need to modify AEServerConfig.php to use your database
   settings.
 - When running a server you will need to determine which communication protocols you want to
   support.  The only method enabled out-of-the box is localhost communication which allows only
   the PHP5 client to talk directly to the server.  To enable XMLRPC support you must create a
   PHP script in your web tree with only following code in it:
   
        <?php require_once 'Auth_Enterprise/Server/AEXMLRPCHandler.class.php'; ?>
        
 - You will probably need to edit the path to the PEAR_Exception class in Common/Exceptions.php
   because this is probably the direction PEAR in PHP5 will be going.  Because that class doesn't
   exist yet in PEAR you'll need to download it. Read the directions in Common/Exceptions.php
   
 - In most instances you will want to use SSL to communicate with an Auth_Enterprise server.  In
   the case you are using either the PHP4 or PHP5 clients you must have curl and the curl
   development libraries intalled.  NOTE: you must be sure to do this otherwise you will be talking
   straight HTTP over an HTTPS port even though you think you are encrypting your traffic.  This is
   a fairly big security concern so be sure to test your SSL configuration.
   
Auth_Enterprise Client-only Installation
-----------------------------------------
 - Coming soon

Common Installation Problems
-----------------------------
1) For MySQL server, Auth_Enterprise attempts to create all tables with the INNODB type, however,
   if INNODB is not installed or configured they will show up as MyISAM.  To check which table you
   have open a MySQL client and run this query:
   
        SHOW CREATE TABLE <table_name>
        
   If the table shows up as MyISAM that means you will need enable INNDOB support.  Please, do not
   send any questions to me regarding this.  Your easiest fix would be to download the latest
   stable MySQL RPM's from http://www.mysql.com.  Having INNODB is important as it is required
   if you want Auth_Enterprise to use SQL transactions and it provides FOREIGN KEY constraints.
   
2) If upon checking your SSL logs you see error about talking HTTP on an HTTPS port then odds are
   the SSL handshake isn't happening because you are using the PHP4 or PHP5 client and don't have
   curl or the curl development libraries installed.
   
   
Support
-------

Free support for Auth_Enterprise can be sought either on my site, http://www.tonybibbs.com, or
via IRC on irc.freenode.net in #geeklog (I'm under the handle IA-Outdoors).  Commercial support
is also available at an hourly rate.  Those wanting commercial support can contact me directly
via email at tony at geeklog.net.