PHPlib:Manual: The complete guide to authentication and user variables

The complete guide to authentication and user variables

Usually, you write code like this into the top of the page you want to protect:

         <?php
         page_open(array(
             "sess" => "My_Session",
             "auth" => "My_Auth",
             "perm" => "My_Perm")); // see Perm docs for specifics
         $perm->check("admin");            // see Perm docs
         ?>

         

         <?php
         page_close()
         ?>

How is the Auth class used usually?

Usually, you write code like this into the top of the page you want to protect:

         <?php
         page_open(array(
             "sess" => "My_Session",
             "auth" => "My_Auth",
             "perm" => "My_Perm")); // see Perm docs for specifics
         $perm->check("admin");            // see Perm docs
         ?>

         

         <?php
         page_close()
         ?>

	         function auth_loginform() {
	           include("loginform.ihtml");
	         }

and you put your code into that file. We also provide sample code for that file, but you are not limited to that code and may write a loginform.ihtml as it meets your needs.

When the loginform has been filled in and submitted back by the user, Auth calls $auth->auth_validatelogin(). Again, this function is empty in Auth itself and so Auth by itself will never function correctly. You have to subclass Auth and provide your own implementation of $auth->auth_validatelogin() in local.inc to make it work.

What you actually do in that function is completely irrelevant to Auth itself. It only exspects that you either return false, if the user-supplied authentication data was invalid, or a user id, if the user could be validated. Auth then takes care to create the appropriate entries ($auth->auth["uid"] and $auth->auth["exp"]) in the session record.

I still do not understand! What am I supposed to code?

You write your code into local.inc, after you have removed the classes Example_Auth, Example_Default_Auth and Example_Challenge_Auth from that file (keep a copy around, just for reference).

You code a class called My_Auth and you use that name later in your calls to page_open as an argument to the auth feature, as show at the start of this message. Follow the standard rules for deriving persistent classes in PHPLIB when you create your code, that is, do it like this:

         class My_Auth extends Auth {
         var $classname = "My_Auth";
         // we inherit $persistent_slots and do not need to modify it.

         // later code is inserted here
         }

Now configure the lifetime of the authentication, that is, how many minutes in the future shall the current value of $auth->auth["exp"] be? Also, name a database connector class and name the table that you will be using to check usernames and passwords.

	// insert this code as indicated above.
	var $lifetime = 15;
	var $database_class = "DB_Example";
	var $database_table = "my_special_user_table";

         // later code is inserted here

Okay, now we have a basic implementation of My_Auth that is only lacking the required functions auth_loginform() and auth_validatelogin(). Our implementation of auth_loginform() will have access to all $sess variables by globaling $sess into our context (because these can come in handy) and to all $auth variables (via $this).

	function auth_loginform() {
	  global $sess;
	  include("loginform.ihtml");
	}

The loginform is free to do whatever it damn well pleases to create a form for the user to supply the needed values for authentication. It has access to anything $sess and anything $this related.

The loginform will display some input fields for the user, for example a given name, a surname and a password. When the form is submitted back, auth_validatelogin() is being called. The form values are global variables (or $HTTP_x_VARS[]) and must be imported into $auth->auth_validatelogin(). Then, $auth->auth_validatelogin() is free to do whatever it must do to produce a unique identifier for that user (or return false).

Suppose you created input fields named given_name, surname and password. So go ahead, global $given_name, $surname and $password and set $uid to false. Then create the SQL needed to access you user table and retrieve the user record from your database as indicated by $given_name and $surname and $password.

The query may succeed, if a record with matching $given_name, $surname and $password is present. In that case return the uid, which uniquely identifies exactly that (given_name, surname) pair. Else return false.

In code:

	function auth_validatelogin() {
	  // import authentication data
	  global $given_name, $surname, $password;

	  $uid = false;

	  $query = sprintf("select uid
	                      from %s
	                     where given_name = '%s'
	                       and surname = '%s'
	                       and password = '%s'",
	             $this->database_table,
	             addslashes($given_name), addslashes($surname),
	              addslashes($password));

	  // $auth->db is our DB_Example database connection
	  $this->db->query($query);

	  // now check for any results
	  while($this->db->next_record()) {
	    $uid = $this->db->f("uid");
	  }

	  // either $uid is false now (no results)
	  // or set to the last retrieved value from the uid
	  // column.

	  // Anyway we are set now and can return control
	  return $uid;
	}

Okay, that's all and useable now. There is room for some improvements, though: First we did not retrieve permission data, so this will not work, if we want to use the perm feature as well.

This is easily changed: Modify the query to select uid, perms instead of select uid alone. Of course, you may call your perm column whatever you like, just adapt the SQL accordingly. Also, add a line after the $uid assignment so that the code looks like this:

	$uid = $this->db->f("uid");
	$this->auth["perm"] = $this->db->f("perms");

This will store the retrived perms value under the key perm within the $auth->auth[] array. It will be kept around in that place in case $perm is called and starts looking for the current permissions of that user.

Another possible improvement becomes apparent when you try to login and fail to do so correctly: auth_validatelogin() returns false and you hit the loginform again. Empty loginform that is, because we did not remember what you typed into the given_name and surname fields before. If we remembered what you typed, we could easily supply these values back to you so that you can correct them. We would also be able to detect if this is a second, third, ... attempt to login and display an appropriate error message somewhere in that loginform to inform the user of his or her typo. A convenient place to store these values is the $auth->auth array, which is persistent anyway.

Standard Example_Auth uses the field $auth->auth["uname"] to store that value, but you may use any field and as many fields as you like as long as you make sure not to clash with any of the three officially used fields, uid, exp, and perm.

Do not try to turn the global variables $given_name and $surname into persistent variables by calling $sess->register("given_name") and $sess->register("surname")! Remember: These are form variables! Never ever make form variables persistent and never ever trust unvalidated user supplied from the Internet!

So add the folling code just below the "global" line:

	  $this->auth["gname"] = $given_name;
	  $this->auth["sname"] = $surname;

and check for these two variables in loginform.ihtml at the appropriate places.

Ok, I did that and it works. I even understood it. Now, what exactly is that uid used for?

It is simply a token to indicate that the user is authenticated. We use a different token for each user, so that we can decide which user we are currently dealing with. You can think of the uid as a primary key for your auth_user table (or whatever it is being called in your current application). The ( given_name, surname ) tuple would also be a possible primary key, albeit a compound one. It is the external, human-readable (and probably sometimes very long) representation of the internal uid. The password field is functionally dependent on either of both key candidates.

The internal user id should never be presented to the user; the ( given_name, surname ) pair is much more natural to handle for the user and easier to remember (A user who does not remember his or her name would probably not be in a state of mind to operate the rest of the application anyway :-).

The internal user id should always be used to identify a user internally within an application, though. That is, because the uid is of a fixed length and has a known form and structure, so you can make assumptions. A given_name or surname may be of any length and may contain about any character, so you probably do not want to use this as a user-reference internally.

But is the uid used internally by PHPLIB?

Yes, if you make use of the user feature of page_open(), that is, if you create user variables.

The User class is actually a subclass of Session. That is, user variables are just like session variables. They are even stored in active_sessions. The only difference is that the session has a different name (it is called Example_User instead of Example_Session, if you use the classes and names supplied in local.inc).

And in Example_User, the user id of the authenticated user becomes the session id in the active_sessions table. That is the reason why we recommend md5(uniqid("abracadabra")) style uids.

	Thursday, August 28, 2008
	download \| documentation \| faq \| changelog \| resources

search for in the