For a current (PHP) project I need a highly flexible authentication and permissions management system. Having heard plenty of mentions on the various PEAR lists I decided to try out LiveUser, which seems to currently be the most comprehensive such system for PHP. It’s a large codebase that seems to cover most of the necessary permutations and includes a number of prominent coders amongst its developers.
What I hadn’t taken into account, of course, was the lack of documentation. I spent quite a while trawling through their wiki and googling before concluding that the best way to work LiveUser out would be to work through the code piece by piece. And since that’s a long, slow process it seemed worth documenting here. I’m going to do that step by step, starting today with configuration and instantiation.
LiveUser’s initial configuration is managed through a large associative array that should be passed to the factory in order to instantiate the core object. Unlike some of the other arrays used as arguments to functions, this one is documented inline, but it still took a while to pick apart.
Here’s an example:
$liveuser_config = array(
First up we have some core parameters for LiveUser
autoInit determines whether or not the class tries to instantiate the various ‘containers’ when it is first called
'autoInit' => true,
the login parameter allows us to specify whether login should be attempted off-the-bat and whether or not the session ID should be regenerated after a successful login.
'login' => array( 'force' => true, 'regenid' => true),
With the core parameters set, we can move onto the ‘containers’. LiveUser employs containers to allow for flexibility. Containers can be thought of as ‘plugins’ that allow access to any sort of authentication or permissions management system you want to connect.
First up I define my permissions container. There are three container types that come with LiveUser out of the box: ‘simple’, ‘medium’, and ‘complex’. I’m looking for as much flexibility as possible so am using ‘Complex’.
We then provide some ‘storage’ parameters. LiveUser provides several storage option for permissions (primarily PEAR::DB, MDB and MDB2) and you can add extras in. Here I am using PEAR::DB and so specify a DSN and the prefix I’m using for my tables.
If I already had a DB object instantiated, I could remove the ‘dsn’ parameter and replace it with ‘connection’ which would be a reference to my existing connection.
'permContainer' => array( 'type' => 'Complex', 'storage' => array( 'DB' => array( 'dsn' => $dsn, 'prefix' => 'liveuser_'))),
For me, one of the key draws of LiveUser for me was the fact that I could authenticate against multiple sources for one application. This application includes a directory for a membership-based organisation, and I want all members to be able to login. There are also a few administrators who are not members, but need to be able to log in to the site.
authContainers is itself an associative array, with the keys being the names by which you want to address the different authentication sources. In this case ‘members’ and ‘admins’. You can specify a few options that should be familiar to anyone who’s used PHP’s sessions and then a few others. I’m again using the PEAR::DB interface for my authentication so I specify type as ‘DB’.
Options for the DB container are then given in the ‘storage’ parameter. As with the permissions, ‘dsn’ can be replaced with ‘connection’. ‘alias’ is an array that maps the table (‘users’) and fields that LiveUser’s DB container uses by default to the table and fields that we have in our application.
'authContainers' => array( 'members' => array( 'type' => 'DB', 'loginTimeout' => 0, 'expireTime' => 3600, 'idleTime' => 1800, 'updateLastLogin' => false, 'allowDuplicateHandles' => false, 'allowEmptyPasswords' => false, 'passwordEncryptionMode' => 'PLAIN', 'storage' => array( 'dsn' => $dsn, 'prefix' => '', 'alias' => array( 'users' => 'member', 'auth_user_id' => 'id', 'is_active' => 'status', 'handle' => 'username', 'passwd' => 'password'))), 'admins' => array( 'type' => 'DB', 'loginTimeout' => 0, 'expireTime' => 3600, 'idleTime' => 1800, 'updateLastLogin' => false, 'allowDuplicateHandles' => false, 'allowEmptyPasswords' => false, 'passwordEncryptionMode' => 'MD5', 'storage' => array( 'dsn' => $dsn, 'prefix' => '', 'alias' => array( 'users' => 'admins', 'auth_user_id' => 'id', 'is_active' => 'id', 'handle' => 'username', 'passwd' => 'password')))));
With that array set up, LiveUser can easily be instantiated using:
$live_user = LiveUser::factory($liveuser_config, $username, $password);
or
$live_user = LiveUser::singleton($liveuser_config, $username, $password);
and we can check whether the user is now logged in with
$live_user->isLoggedIn() which returns true if login succeeded, false if it failed.
(NB: LiveUser’s own database schema is distributed within the examples that come in the PEAR package. It is provided as an MDB-compliant XML file)
Tags: Authentication, authorization, LiveUser, PHP
[…] s | portfolio | code | blog | about | contact
a work on process
« Configuring LiveUser Getting Started with LiveUser Permissions […]
This is a great resource for new users to LiveUser. I’ve used it a little but never really in depth.
Can you provide a layout for your “users” table? I think it’d be helpful to visually see how your auth aliases map.
I’m curious about your thinking behind the assignment of the “is_active” alias. I’m guessing that “status” is a boolean (or equivalent) column and that’s activating or deactivating a “member” account but that you’re using the “id” column for admins since it’s the primary key that’ll always return a value that evaluates to true. Have I got that right?
One more thing. You’ve left the “prefix” value empty in the auth storage container arrays. So does that mean that the default name that LU uses for a user tablename is `users` and the value of “prefix” would be prepended to that name? Or is the “users” auth storage container alias a pointer to the tablename to use for that particular auth container? I think that’s the part that isn’t precisely clear above.
Thanx for these posts though. They’re really helpful. Looking forward to reading them all.
(e)
Glad you’re enjoying the posts.
The table I’m using is:
auth_user_id – char(32)
handle – char(32)
passwd – char(32)
owner_user_id – int(11)
owner_group_id – int(11)
lastlogin – timestamp
isactive – tinyint(1)
name – char(50)
email – char(100)
And it’s named liveuser_users. I got the table definition from the MDB XML file that’s included in one of the examples. IIRC the “prefix” defaults to “liveuser_”.
I’m not entirely sure why is_active is set to tinyint, but I suspect it’s to retain control so that there can be nuances beyond ‘active’ or ‘inactive’, though that’s how I’m expecting to use it.
Hi,
according to your Aliases in the Auth Containers, don´t your tables look like this?:
Table: Member
id – char(32)
username – char(32)
password – char(32)
status – tinyint(1)
…
Table: Admins
id – char(32)
username – char(32)
password – char(32)
…
Else this whole Alias stuff wouldn´t make sense or did i get something wrong?
Btw: Nice to see that someone makes an effort in documenting this package more clearly 🙂
Sorry. You’re right Octavian. It’d been a while since I looked at my table layout. The layout I put in my previous comment is the default liveuser table name, and liveuser doesn’t default to a particular prefix. Those are indeed the layouts of my tables.
I think I need to wait till the coffee kicks in before responding to comments!
Just wanna say “thank you”!
I’m not sure if had made it without your post. and there are still some things whcih are really bothering me. perhaps we should help populating the wiki. otherwise it will be difficult to coordinate the efforts 😉
the wiki is currently a bit access limited ..
let me know if you are getting ready to add content ..
alternatively you can add it to the docbook documentation as well ..
[…] Tonight I am working on adding a flexible permissions system to my PHP application ‘Dataface’. I have a predisposition towards using PEAR classes where I can so naturally I decided to try LiveUser. Unfortunately the documentation is scarce, and all but to-the-point. I was, however impressed with this short article (http://jystewart.net/process/archives/2005/07/configuring-liveuser) that cuts to the chase on how to set up Live User. I recommend this one to anyone looking for User management in a PHP application. […]
i was playing with the example 5( php/doc/LiveUser/docs/examples/example5/ )
but i can’t initiate the objet
$usr = LiveUser::singleton($conf);
i try with &
$usr = &LiveUser::singleton($conf);
and no object is created
just this work for me:
$usr = &LiveUser::factory($conf);
did you know why??
Great post.
How would you properly log the user out?
&LiveUser::singleton() gota 2nd parameter called signature
http://pear.php.net/package/LiveUser/docs/latest/LiveUser/LiveUser.html#methodsingleton
if u set this paramter the sigleton method works
I am incorporation LiveUser in our Intranet. I manage to log a user in by the following code (using your configuration example).
$live_user = LiveUser::singleton($liveuser_config);
$live_user->login($username, $password, true);
However, I don’t seem to grasp how I can have the user logged in on the following pages?
hm, for me it’s not handing it a ‘connection’, but rather ‘dbc’ in place of ‘dsn’ that works. i’m using 0.6.19
cheers, nice article!
lars: the answer is, welcome PHP session magic, watch out or you’ll fall in love.
check out the values “$expireTime” and “$idleTime” in LiveUser_Auth_Common:
http://pear.php.net/package/LiveUser/docs/latest/LiveUser/LiveUser_Auth_Common.html
looks like they default to expireTime = 0 – which means logged in until logged out or PHP session variable clears. i haven’t checked this out for sure, i’m pretty fresh to LiveUser too (counting in hours here)
enjoy!
Steve, on how to log someone out – here’s a snippet that ought to answer your question – gets logout from a _REQUEST variable if it’s there and does “the big job” on your current logged in LiveUser.
$logout = (array_key_exists(‘logout’, $_REQUEST)) ? $_REQUEST[‘logout’] : false;
if ($logout) {
$usr->logout(true);