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.
The LoginManager
The Auth Containers
The Perm Containers
The LoginManager is the heart of LiveUser. It manages the hole login and init process (validate login, include necessary files, etc.)
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 |
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. |
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 |
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.
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. |
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. |
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. |
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. |
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 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:
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. |
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. |