Random Neural Firings

In our first battle, we were simply trying to understand what needed to happen and where in order to produce a valid authenticated user. Really we didn’t even get that far; we simply identified how the modular authentication system of phpBB3 is supposed to work. We really didn’t get into the nitty-gritty of phpBB’s execution.

If we’re going to try to track our “quantum particles” (i.e. execution…see the series opener for explanation) through that nebula, the place to start is with the User Control Panel (ucp.php). That is, after all, where most battles take place, or at least where they begin.

So, from the top…

The script opens with several definitions and includes that contain more definitions. We’re not going to concern ourselves much with those. Just note that those lines appear in most of the public-facing scripts in phpBB.

In fact, we really don’t care about anything until we get to the session_begin() function. I went into some detail about this function in the previous post, so I won’t go into it again here. We’ll get into it later when we get back to the discussion of Overstock’s unique needs and how I was finally able to meet them.

After the session is opened, phpBB needs to detemine the permissions held by the user. That’s done by a call to the $auth->acl() function, which takes an array of user data as it’s argument. The user data array ($user->data) exists by virtue of the session that was previously opened for the user ($user). As that user object is constructed, user permissions are either queried from the database for that particular user (if a record exists) or they are queried from a “guest” account to allow the user to browse around the forums as a guest as allowed by the forum permissions (set by admin; outside the scope of this discussion).

Now that the session is created and the permissions set, the next thing we care about is $mode. You may have noticed a few lines up the line that defines the $mode variable by a call to the request_var function. I’ve never taken the time to read through this function, but my cursory observation and the obvious implication of the name lead me to deduce that this is phpBB’s wrapped method of extracting values from other places (such as REQUEST arrays). In this particular case, the value being extracted comes from the URL string, so it is a GET parameter called mode. If the user is not logged in, the value of this parameter will be login.

So, following through ucp.php, we come to a switch statement that is testing the value of $mode. For now, we only care about the block that executes if the value of $mode is “login.”

The original phpBB code checks to see if the user if registered. If so, the user is redirected to the index page; otherwise, the login_box() function is called, which (you guessed it) renders the phpBB login box. All well and good under normal circumstances, but in Overstock’s case, this wasn’t the desired behavior. As I mentioned in the first post, Overstock wanted to bypass the standard phpBB login process and replace it with their own “universal login” procedure. So rather than using the standard phpBB login screen, the desired behavior was for the system to check for an existing universal login session (certain cookie values), and if it existed, automatically log the user into phpBB; otherwise, redirect the user to Overstock’s univseral login screen, which would then send the user back to the referring page upon successful authentication. Once returned from the universal login, the user needed to be authenticated and logged into phpBB seamlessly.

Sounds simple enough; however there is one further complicating wrinkle that needed to be handled. In the event that the user had never used the Overstock forums before (i.e. didn’t have an existing phpBB account), the login procedure needed to create the phpBB account for them. So, effectively, the user would have two accounts–one universal login account for Overstock sites, and one phpBB account–that needed to be seamlessly synchronized. The phpBB account would be used for phpBB authentication and permissions, but the user’s experience has to act as though everything is controlled by the universal login account.

So back to the UCP.

To accomplish the desired effects, I took out all of phpBB’s original login code and replaced it with an if/else procedure that tests for a valid universal login session (ID). If found, the username and password for the user’s phpBB account are determined (I’m keeping the details of this procedure to myself for security reasons). Finally, it executes the $auth->login() function, passing in the username and password. If successful, it redirects to the index page and phpBB functions as normal from there with the user fully logged in.

So there it is. Mission accomplished…sort of. We’re now able to successfully authenticate a user in phpBB using an external authentication procedure. Of course, that assumes the user already has an existing phpBB account that corresponds to their universal login account.

But what if they don’t? How do we iron out that particular wrinkle?

Read on. We’re winning battles, but the war is still far from over.