Step-by-Step Guide to Integrating OpenAuth into Your PHP Web Application

Part of the OpenAuth Web Integration Series

by Jack Herrington
September 21, 2007

No matter what kind of Web application you build, the process always seems to start in the same place: managing user accounts. Writing a file-sharing application for the Web? You begin by identifying who is uploading the file. Writing a chat application for the Web? You have to know who will use the chat session, so you can give them access. Because the Web is inherently multi-user, any application you build is going to require managing a list of users.

For PHP programmers, this means one of several approaches:

Roll your own – You could build it yourself by creating a table of users, building the data accessors, encrypting the passwords, and all that back-end stuff. Then you have to create an interface for logging in, requesting passwords, sending e-mails, and so on. In addition, you have to manage the accounts of your customers. To do it right is a lot of work.
Use an example – You could use an example set of code like the one I provide in my book PHP Hacks. But it’s still just a starting point. It doesn’t offer password recovery or any of the features that you need in a production application.
Build from an application base – There are many PHP application starting points, like Joomla or Drupal, that you could build on. The good news is, they handle basic user management. The bad news is that they include a lot of functionality you might not need. It also leaves your customers with yet another username/password combination to keep track of.
Use an identity provider – The last option (and not coincidently the point of this article) is using an external identity provider. In this case, I’ll show you how using the AOL Open Authentication API (OpenAuth).

Using an external identity provider offers a lot of advantages, not just to you, the application developer, but also to your customers. You get to start building your application right away, confident that you will be able to identify users and log them in quickly and reliably. And your customers will be able to reuse their existing screen names and passwords. Of course, that depends on the popularity of the identity provider; in the case of AOL this means leveraging the millions of people who have already registered with AOL Instant Messaging (AIM), among many other services.

Getting an Account

Getting started with the AOL OpenAuth system is remarkably easy. The first step is to get an AOL account. They are free, so this is easily done. If you have an AIM account you can also use that instead of an AOL account. The next step is to get a developer ID (devId) for your AOL account. To do this we start at the OpenAuth home page. Then click the Getting Started link toward the top of the page to continue.

Click the AOL Developer Site link to see a list of devIds associated with your account, if any.

Click the Create new devId link to access the devId request form.

On this form enter your first and last name, your e-mail address, and then, most importantly, the URL where your customers should be redirected after a successful login. When you have this information filled in, submit the form and you should see results similar to the following:

The Id field is the important one here. It is the ID you will use on the login page in your Web application.

The OpenAuth Page Flow

With the devId set up, let's take a step back and figure out how the login page flow is going to work in your application. The following screen shot shows the page flow when the customer is not logged in to an AOL account.

The customer first goes to your start page, Index.php. Because they have not yet logged in, the customer clicks a link to take them to the AOL login page. Here the customer fills in their screen name and password. If their credentials are verified, the customer is redirected to the Index.php page through URL-based arguments that encode the screen name of the customer who logged in.

To complete the login the Index.php page that receives the URL parameters from AOL needs to go to the AOL OpenAuth site to retrieve your account information. This is done using the standard CURL library. The user doesn’t see the request. Their screen name appears in the application thanks to the GetInfo call that returns the screen name from AOL. In addition to GetInfo, there are other calls you can make to see if someone is already logged in to AOL, or to log them off.

If the customer is already logged in, OpenAuth bypasses the login page.

This means that customers can log in to your site without retyping their AOL screen name and password, if they are already logged into AOL. An extra advantage for free!

If you intend to use AOL as your exclusive user management system you could bypass the initial link on the Index.php page by simply forwarding the customer to the AOL login page if they are not already logged in.

Building the Login Page

Although the page flow might look complex, the actual PHP code that manages the OpenAuth login is remarkably simple. The entire PHP code for Index.php is shown in Listing 1.

Listing 1. Index.php

<?php
session_start();
?>
<html><body>
<?php echo $_GET['statusText'] ?><br /><br />
<?php
$succUrl = "http://muttmansion.com/openauth/index.php";
$devId = "** your devId **";

if (isset($_GET['token_a'])) {
  $getinforesults = callgetInfo( $devId, $succUrl );
  parse_str($getinforesults, $info);
  $_SESSION[ 'user' ] = $info['userData_loginId'];
?>
You have successfully logged with your ID: <?php echo( $_SESSION['user'] ); ?><br/>
Go to your <a href="home.php">Home page</a>
<?php
} else {
  $href = 'http://api.screenname.aol.com/auth/login?f=qs';
  $href .= '&devId='.$devId.'&supportedIdType=SN,ICQ,OID';
  $href .= '&succUrl='.urlencode($succUrl);
?>
Use your AOL/AIM ID, ICQ Account or OpenId url to
<a href="<?php echo($href); ?>">Login</a>
<?php 
}
?>
</body></html>
<?php
function callgetInfo( $devId, $succUrl ) {
  $aolAuthToken = $_GET["token_a"];

  $getInfoUrl = 'http://api.screenname.aol.com/auth/getInfo?f=qs';
  $getInfoUrl .= '&devId='.$devId.'&a='.urlencode($aolAuthToken);
  $getInfoUrl .= '&referer='.urlencode($succUrl);
  
  $getInfoRequest = curl_init();
  curl_setopt( $getInfoRequest, CURLOPT_URL, $getInfoUrl );
  curl_setopt( $getInfoRequest, CURLOPT_RETURNTRANSFER, true );
  $response = curl_exec($getInfoRequest);

  if (curl_errno($getInfoRequest)) {
      print curl_error($getInfoRequest);
    return "";
   } else {
    curl_close($getInfoRequest);
    return $response;
   }
}
?>

All you need to do is change the $succUrl and $devId variables to the URL for your site and your developer ID respectively.

The code starts by creating a session. It will use that session to maintain the user name returned from OpenAuth. In your own Web service you likely will want to forward the user to their home page if the user name is already set.

After that the code looks at the URL arguments to see if the customer is being sent back to the page after a successful AOL login. If that is the case, the user name is set to whatever is returned by the GetInfo call. If the URL arguments are not set, this is likely the first time the customer has been to the page and so they are given the login link.

To see this in action I’ll go to Index.php in my browser.

It’s not much to look at, but it works. Here I click the Login link, which takes me to the AOL login page. This is where the customer logs in to their AIM, ICQ, or OpenID account.

This is where the customer logs into the their AIM, or ICQ or OpenID account. I’m going to use my AOL screen name ‘idratheryouemail’. I gave myself that name as a silent protest against a company where I worked that required that everyone have instant messaging installed. I hate instant messaging, so I figured a name that said, “I’d rather you email” would get the point across. It didn’t.

After I click Sign In, assuming the credentials are correct, I am returned to Index.php, logged in.

How easy is that, right? Now I have a complete user management system for my application in just--what, 20?--lines of PHP? Pretty sweet. And my customers get to use their AIM accounts to log in, so they don’t have to remember yet another account name and password to access my Web service.

The home page for the user is very simple and easy to use. It shows the screen name of the person who is logged in, and provides a link to the user's AIM buddy list.

Listing 2. Home.php
<?php
session_start();
?>
<html><head>
<script type="text/javascript"
 src="http://o.aolcdn.com/aim/web-aim/aimapi.js"></script>
</head><body>
<table width="100%"><tr><td valign="top">
User: <?php echo( $_SESSION['user'] ); ?>
</td><td valign="top">

<div id="AIMBuddyListContainer" wim_key="** Your WIM key **"></div>
<a onclick="AIM.widgets.buddyList.launch();return false;"
 href="nojavascript.html">Launch my Buddy List</a>

</td></tr></table>
</body></html>

Most of the code here is to support the buddy list. At the top I include the Aimapi.js file from AOL, which contains the code for the AIM widgets. Below I put in a buddy list container <div> and an anchor tag that has Javascript to launch the widget.

You can see this in action after I have logged in.

You don’t need to have the buddy list to get this to work. This is just an example of how you can use some of the other AOL APIs to enhance what customers can do on your site.

Going On from Here

This isn't the only service that AOL offers. AOL is opening APIs and technologies from identity to instant messaging, media and community, and providing Web application developers with a wide range of scalable solutions. In addition to the Web AIM widgets, AOL has a file-hosting service called OpenXdrive that you can use to host image or movie files, the same way developers are using Amazon's Simple Storage Service (Amazon S3) Web service. AOL has a video-sharing service similar to YouTube, and an industry-leading video search engine called Truveo. MapQuest maps can be integrated into your page. All the currently available AOL Open APIs, and associated documentation, are at http://dev.aol.com/apis. AOL is really opening up and this article shows you how easily AOL APIs can be integrated into your applications.

Conclusion

Even if you don’t want to use OpenAuth as your identity management system, this API presents an easy way to give users access to your service with minimal hassle. And if you want to use it as your user management system, you get a very easy-to-use API for free. It’s definitely worth your time to look into using OpenAuth on your site. That way you get to concentrate of the fun features that make your site interesting and avoid the hassle of reimplementing user account and password maintenance features for the umpteenth time.

Topic Centers

Submit Post

More Articles