********************************************************** authentication.txt $Id$ @author gERD Schaufelberger @copyright 2004/2005 Wombat Web Bench @link http://wombat.exit0.net @package wombat @subpackage manual ********************************************************** Using Users =========== The Wombat Framework comes with build-in user managerment and authentication/ authorization modules/handler. Even if they are part of the base system, there are versatile options for customization. Also authentication handlers are desinged as adapters, it may be very easy to write another handler, that connects Wombat to any (?) existing user-system. Of course, the framework also runs fine without any authentication. Without using the authentication modules you don't have to set up any tables in the database etc. Currently, Wombat comes with two authentication handler. Those are "Wombat" and "Null". While "Wombat" links wbSite to wbUser (an user-handling class developed for the wombat framework) the "Null" handler is just empty. Therefore with wbAuth_Wombat you can actually login into and logout from the current site, wbAuth_Null always results in an anonymous visitor. If you don't need user logins etc, "Null" is the hanlder of your choice. The other handler "wbAuth_Wombat" uses wbUser as backend. wbUser is fully supported by the Wombat framework and provides you with a nice adminstration interface as well as password-renew modules etc. Also there are various permission checking modules that work hand in hand with wbUser. This is the bright side. On the dark side, wbUser may not be compatible with your custom application that you want to run within the framework. In this case you may want to write your own authentication handler. Even if this is not tested, it should work by putting your adapter in next to wbAuth_Wombat-class (include/wbAuth/Wombat.php). Let's go back to the bright side and assume, wbUser is already set up and you use the authentication handler "Wombat". Basic Authentication features ============================= The login handler is controlled by the configuration section: auth in the main configuration. For a basic setup you just have to adjust the parameter: . A valid auth-section may look like this: -----------------8<-----------------8<-----------------8<----------------- Wombat enabled,approved,!new Null staticString Permission denied staticString Permission denied -----------------8<-----------------8<-----------------8<----------------- Authenication handler --------------------- Specifying the authentication handler allows to switch of the authentication and authorization processes. As mentioned above, you may choose between "Null" and "Wombat" (ir implement your own handler). Also mentioned, "Null" is like if there were no login - all users are treated as anonymous visitors. In order to make something happen, "Wombat" it the handler of our choice. Authentication flags -------------------- The configuration value of may or may not contain something, or something else. What it means is, that it depends on the authentication handler what can be used here. Basically, it is some kind of parameter, that can be passed to the authentication handler during instanciation. The idea behind is, to add some additional parameter that must be checked to grant a user to login. Of course, the user name and password must match, but you may also want to validate, that the user is over 18 years old, for example. In other words, may contain whatever the used authentication handler understand. The authentication handler "Wombat" understands a comma separated list of user flags. It also understand a prefix "!" - this is to negate a flag. What the authentication handler "Wombat" (or better wbUser) does, is to check whether the user's data satisfy those flags. For this example, if a user attempts to login with his username and password, both, the username, password AND the listed flags will be required. In this case, the flags "enabled" and "approved" must and the flag "new" must not be set. With wbUser, those flags are represented as a "set" field in the user-table. If any of those checks fail, the user is not allowed to log in. As you may imagine, this makes it very easy to enable or disable accounts without removing them. Setup wbUser ============ As described above, the authentication handler uses wbUser as backend. Actually wbUser implents all the features. Hence wbUser must be setup properly. Requirements ------------ All user data, like login-names, password and group-information will be stored in a database. Even if the base system uses PEAR::DB (which supports various databsase) using MySQL is recommended. All user relevant data will be stored in three tables in the database: - user - group - usergroup All of those tables will be defined in the global configuration - usually in tables.xml (see configuration value: ), e.g.: -----------------8<-----------------8<-----------------8<----------------- userflags=deleted
groupname
group
-----------------8<-----------------8<-----------------8<----------------- The User Table -------------- The user table stores the basic data of all users: user-name, user-id and password. Besides that other essential information are: realname, email, created-date, recent-date and a set of user flags. - user-id: the user-id is the primary key of the user table - user-name: this is login name of the user - password: the users password. Passwords will be stored in an encrypted format, therefore they will be hidden from the administration users as well. - created-date: this field contains a timestamp of the creation - recent-date: everytime the user logs in, this timestamp will be updated - email: The email-address of the user is required to contact the user (send password, etc) - flags: The flags represent the current state of the user-account. This set-field must at least allow: - deleted: removed accounts - even if it is possible to change the configutation it is strongly recommended to "mark" users as delete instead of removing them. - new: for registered users - approved: the new account is approved by a system administrator (optional but strongly recommended) - enabled: account is enabled The group Table --------------- The group table is quite simple, it basicly contains two fields: group-id and groupname. Of course, the groupname must be unique. The Usergroup Table ------------------- The usergroup table implements the relation between users and groups. Therefore it stores both, user-ids and group-ids. The default setup should be all right in most cases. Additional Fields? ------------------ The base system including the build-in account manager as well as the user register tools require the above mentioned fields in the user table. Therefore the described tables is the minimal setup. If your application needs additional data for example in the user table, the framework will run fine with extended tables. The same for user-flags - you are allowed to expand the set-field if you need addtional flags. Of course, you are allowed to use addional fields in the group and usergroup table, too. SQL-dump -------- See sql.txt, the sql-statements can be found in doc/sql/wbuser.sql. Permissions =========== In order to use the authrozation features as well, see auth.txt. User Managerment ================ Well, writing code is more exiting, than punching in manuals... Automatic User Registration --------------------------- User Account Administration ---------------------------