LiveUser - The user authentication and
permission management framework

Version 0.6    2002-03-23

by Björn Kraus (krausbn@php.net)

 

LiveUser is a set of classes for dealing with user authentication and permission management. Basically, there are three main elements that make up this package:

The LoginManager class takes care of the login process and can be configured to use a certain permission container and one or more different auth containers. That means, you can have your users' data scattered amongst many data containers and have the LoginManager try each defined container until the user is found. For example, you can have all website users who can apply for a new account online on the webserver's local database. Also, you want to enable all your company's
employees to login to the site without the need to create new accounts for all of them. To achieve that, a second container can be defined to be used by the LoginManager.

You can also define a permission container of your choice that will manage the rights for each user. Depending on the container, you can implement any kind of permission schemes for your application while having one consistent API. Using different permission and auth containers, it's easily possible to integrate newly written applications with older ones that have their own ways of storing permissions and user data. Just make a new container type and you're ready to go!
Currently available are RDBMS containers using PEAR::DB.

 

Table of contents

The LoginManager
The Auth Containers
The Perm Containers

 

The LoginManager

The LoginManager is the heart of LiveUser. It manages the hole login and init process (validate login, include necessary files, etc.)

Options

Option Value Description
sessionName string
Default: "LiveUser"
The session name to be used for all sessions.
sessionVarName string
Default: "ludata"
The name of the session variable in which the auth object will be stored.
handleParamName

string
Default: "handle"

The variable name for the user handle that comes from a HTML login form.
passwdParamName string
Default: "passwd"
The variable name for the password that comes from a HTML login form.
loginInputType "POST" or "GET" The input channel in which to look for login information. Can be POST for form input or GET for URL input.
logoutParamName string
Default: "logout"
Name of the GET-Parameter that is being monitored for logging out. If present, the auth object in the session will be destroyed.
loginFunction string
Default: ""
Function to be called when the user is not logged in. You either can set it in config file or use the setLoginFunction method.
autoInit boolean
Default: false
Flag to run the init() method when the constructor is called.
forceLogin boolean
Default: false
Flag: Should the user be forced to login? If set to true the login screen will be displayed until the login is successfull.
cookieName string
Default: "loginData"
The name for the cookie to store auth information in (used for the "remember me" function).
allowCookies boolean
Default: false
This flag determines if "remember me" cookies are allowed. If not, the LoginManager won't even look for a cookie, so login information has to be re-entered for every session. This is the recommended behaviour!!!
Set to 0 for not allowing cookies, set to 1 for allowing them.
cookieParamName string
Default: "useCookie"
The name of the "remember me" checkbox on a HTML form. If this is provided via the channel defined in loginInputType (GET or POST), and allowCookies has been set to 1, a cookie with user information will be set so the user won't have to login using his username and password again as long as the cookie exists.
cookieLifetime integer
Default: 30
The lifetime of the "remember me" cookie in days. Note that the cookie lifetime will be refreshed every time the user logs in.
cookieDomain string
Default: "localhost"
The domain for the "remember me" cookie. Example: "21st.de".
cookiePath string
Default: "/"
The path for the "remember me" cookie.
logoutRedirectURL string
Default: ""
The URL to redirect to when the user logs out.
destroySessionOnLogout boolean
Default: true
Determines whether or not to destroy the entire session on logout.
authContainers array See chapter Auth containers and the examples how to configure this option.
authContainerTypeVar string
Default: "authContainerType"
Name of the session variable that is used to store information on the backend in which the auth data resides. This is needed to include the correct backend class definition on demand.
permContainer array See chapter Perm containers and the examples how to configure this option.

Properties

Most properties can be can be accessed via getProperty() method, because they are stored in the auth and perm containers. Some other can be accessed by using the get... functions. All other properties can only available accessed by direct call:

Property name Description
expired Flag: Has the auth session expired?
idled Flag: Is the maximum idletime over?
status

Current authentication status. Instead of direct access you can call the getStatus() method. This flag can have the following values:

LIVEUSER_AUTH_OK          =  1
LIVEUSER_AUTH_IDLED = -1
LIVEUSER_AUTH_EXPIRED = -2
LIVEUSER_AUTH_WRONG_LOGIN = -3
LIVEUSER_AUTH_ISINACTIVE = -4

 

The Auth containers

Currently there are only two containers available which both support the same features: The DB container, using PEAR::DB, and the XML container, using XML::Tree to extract the data from an xml file.

Both containers have the following fields:

There are several options to set up the auth containers and to customize the login process. In the first step, we'll take a look at the common and container specific options, second we'll talk about the properties you can get from the container.

Options

Common options

Option Value Description
type "DB" or "XML" The "name" of the container. The LoginManager includes the container found in /LiveUser/Auth/Container/"type".php and creates a new object $_auth.
loginTimeout integer
Default: 12
Number of hours that must pass between two logins to be counted as a new login. If you want the auth container to count each login as new login, you've to set it to 0.
expireTime integer
Default: 0

Auth lifetime or maximum login time in seconds. If you want the user to be automaticly logged out after one hour, you've to set it to 3600.
Attention: If you want to use expire, you should set loginTimeout to 0 !!!

idleTime integer
Default: 0
Maximum time of idleness in seconds. Idletime gets refreshed each time, init() is called. If this variable is set to 0, idle time is never checked.
allowDuplicateHandles boolean
Default: false
Allow multiple users in the database to have the same login handle.
passwordEncryptionMode "MD5" or "PLAIN"
Default: "MD5"
The encryption mode the password is stored in the container. You shouldn't use plain here for security reasons.

Container specific options

1. DB

Option Value Description
dsn string The DSN that is used to connect to the database (set only if no existing connection object has been reused).
connection object A PEAR::DB object to use an existing db connection.

2. XML

Option Value Description
file string XML file in which the auth data is stored. The path can either be absolute or relative to the document root.

Properties

To get info about the current user use the getProperty() method in the LoginManager class.

Property name Description
handle The handle (username) of the current user. Instead of using getProperty() you can use the wrapper method getHandle().
passwd The (decrypted) password.
authUserId Current user's database record id.
isActive Is the current user allowed to login at all? If false, a call to login() will not set $logged_in to TRUE, even if handle and password were submitted correctly. This is useful when you want your users to be activated by an administrator before they can actually use your application.
loggedIn Has the current user successfully logged in?
lastLogin Timestamp of last login (previous to currentLogin).
currentLogin Timestamp of current login (last to be written).

 

The Perm containers

The perm containers differ between very simple once with only a few options and complex containers with a large set of possibilities to maintain the different rights. Until we have no docu for each container, you have to look at the examples and the code to learn how they work and to choose the right one for your application.

Here a short description for each container:

Options

There are only a few options that can be configured:

Option Value Description
type string The "name" of the container. The LoginManager includes the container found in /LiveUser/Perm/Container/"type".php and creates a new object $_perm.
dsn string Only for the DB containers: The DSN that is used to connect to the database (set only if no existing connection object has been reused).
connection object Only for the DB containers: A PEAR::DB object to use an existing db connection.
file string Only for the XML containers: XML file in which the auth data is stored. The path can either be absolute or relative to the document root.

Properties

To get info about the current user use the getProperty() method in the LoginManager class.

Property name Description
permUserId Current user's database record id.
rights One-dimensional array containing current user's rights. This already includes grouprights and possible overrides by individual right settings.
userRights One-dimensional array containing only the individual rights for the actual user.
This property is not supported in all containers.
groupRights Two-dimensional array containing all groups that the user belongs to and the grouprights.
This property is not supported in all containers.
userType Defines the user type. See /LiveUser/Perm/Common.php for more information.
This property is not supported in all containers.
areaAdmin Defines if the user is an area admin. If the user is an area admin this variable will be filled with an array of all areas in which the user is area admin.
This property is not supported in all containers.
groupIds Defines the (sub)groups in which the user is a member.
This property is not supported in all containers.
groupUserIds Defines the members of all (sub)groups in which the user is a member.
This property is not supported in all containers.