A discussion about OAuth and OpenID

Strictly speaking, Facebook supports OAuth, not OpenID. OAuth is a way for your application to act on behalf of someone else on another side, while OpenId exists solely for you to use the other website as an authorization authority. The difference is subtle, however telling that Facebook has explicitly stated that it does not want to be an authorization authority. In practice, however, the two standards are interchangeable, and OAuth works pretty well as a way to authenticate a user.

How Facebook Auth Actually Works

Here’s the flow in four easy steps:

1. The user clicks on a “Login to Facebook” link on your server, which redirects them to another page on your server that handles the authentication.
2. Your Facebook Auth page puts all the parameters for your authentication, such as your app ID and scope, into a URL and sends the user to Facebook via that URL.
3. Once Facebook returns the user (presumably authenticated) to your server, you can use the parameters sent via the URL to request an authentication token from Facebook. This is done via curl or some other server-to-server communication by calling the graph API.
4. You use this authentication token to access the user’s information on Facebook.

Step 1: Get all the data you need

To properly authenticate with Facebook, you need four pieces of data. The first two are your application id and your application secret, both of which are available on your developer application page.

A sample Facebook application page

The second two pieces of data are specific to your implementation. These are the redirect URI, which is used to tell Facebook where to send the user once they are done authorizing your application, and the permission scope, which you use to tell Facebook what permissions you want to request from the user. This latter one actually warrants some more documentation, which Facebook has graciously provided here. Be careful: Users can get really suspicious if you ask for too much data.

Step 2: Redirect your user to Facebook.

With this data, you can redirect your user to Facebook. Facebook will then work some magic and ask the user whether they want to grant your application access to their profile. Don’t forget to urlencode that Redirect URI.

$loginUri = "https://graph.facebook.com/oauth/authorize?client_id={$appId}&redirect_uri={$redirectUri}&scope={$scope}";
header('Location: ' . $loginUri);

Step 3: Request an Auth Token

Assuming that the user authorizes your application, Facebook will return them to your redirect URI with the “code” parameter in the URL. You can use this parameter to request an authorization token from Facebook. In this case I’m using the Zend Request handler to simplify things a little.

$client = new Zend_Http_Client( "https://graph.facebook.com/oauth/access_token" );
$client->setParameterGet('client_id', $appId);
$client->setParameterGet('client_secret', $secret);
$client->setParameterGet('code', $code);
$client->setParameterGet('redirect_uri', $redirectUri);

$result = $client->request('GET');
$params = array();
parse_str($result->getBody(), $params);
$token = $params['access_token'];

Step 4: Read the user’s profile

At this point, you have an auth token that grants you access to read the user’s profile information in accordance to the permissions they have granted you. These permissions are completely blind- you don’t have to additionally specify what you want to access – the requests will simply return the information to which you have access.

$client = new Zend_Http_Client( "https://graph.facebook.com/me" );
$client->setParameterGet('client_id', $appId);
$client->setParameterGet('access_token', $token);
$result = $client->request('GET');
$user = json_decode($result->getBody());

Zend_Auth_Adapter_Facebook

For those of you who would rather not take the above code and wrap it into your own Auth Adapter, I’ve gone ahead and done all that work for you. Below you will find a sample Zend Controller, as well as a pre-baked Auth Adapter. If you come across any major security problems in it, I’d love to know, since I use this adapter myself .

class Zend_Auth_Adapter_Facebook implements Zend_Auth_Adapter_Interface
{
    /**
     * The Authentication URI, used to bounce the user to the facebook redirect uri.
     *
     * @var string
     */
    const AUTH_URI = 'https://graph.facebook.com/oauth/authorize?client_id=%s&redirect_uri=%s';

    /**
     * The token URI, used to retrieve the OAuth Token.
     *
     * @var string
     */
    const TOKEN_URI = 'https://graph.facebook.com/oauth/access_token';

    /**
     * The user URI, used to retrieve information about the user.
     *
     * @var string
     */
    const USER_URI = 'https://graph.facebook.com/me';

    /**
     * The application ID
     *
     * @var string
     */
    private $_appId = null;

    /**
     * The application secret
     *
     * @var string
     */
    private $_secret = null;

    /**
     * The authentication scope (advanced options) requested
     *
     * @var string
     */
    private $_scope = null;

    /**
     * The redirect uri
     *
     * @var string
     */
    private $_redirectUri = null;

    /**
     * Constructor
     *
     * @param string $appId the application ID
     * @param string $secret the application secret
     * @param string $scope the application scope
     * @param string $redirectUri the URI to redirect the user to after successful authentication
     */
    public function __construct($appId, $secret, $redirectUri, $scope)
    {
        $this->_appId = $appId;
        $this->_secret = $secret;
        $this->_scope = $scope;
        $this->_redirectUri   = $redirectUri;
    }

    /**
     * Sets the value to be used as the application ID
     *
     * @param  string $appId The application ID
     * @return Zend_Auth_Adapter_Facebook Provides a fluent interface
     */
    public function setAppId($appId)
    {
        $this->_appId = $id;
        return $this;
    }

    /**
     * Sets the value to be used as the application secret
     *
     * @param  string $secret The application secret
     * @return Zend_Auth_Adapter_Facebook Provides a fluent interface
     */
    public function setSecret($secret)
    {
        $this->_secret = $secret;
        return $this;
    }

    /**
     * Sets the value to be used as the application scope (array())
     *
     * @param  string $scope The application scope
     * @return Zend_Auth_Adapter_Facebook Provides a fluent interface
     */
    public function setApplicationScope($scope)
    {
        $this->_scope = $scope;
        return $this;
    }

    /**
     * Sets the redirect uri after successful authentication
     *
     * @param  string $redirectUri The redirect URI
     * @return Zend_Auth_Adapter_Facebook Provides a fluent interface
     */
    public function setRedirectUri($redirectUri)
    {
        $this->_redirectUri = $redirectUri;
        return $this;
    }

    /**
     * Authenticates the user against facebook
     * Defined by Zend_Auth_Adapter_Interface.
     *
     * @throws Zend_Auth_Adapter_Exception If answering the authentication query is impossible
     * @return Zend_Auth_Result
     */
    public function authenticate()
    {
    	// Get the request object.
    	$frontController = Zend_Controller_Front::getInstance();
    	$request = $frontController->getRequest();

    	// First check to see wether we're processing a redirect response.
    	$code = $request->getParam('code');

    	if ( empty ($code ) )
    	{
	    	// Create the initial redirect
	    	$loginUri = sprintf(Zend_Auth_Adapter_Facebook::AUTH_URI , $this->_appId, $this->_redirectUri);

	    	if ( !empty($this->_scope) )
	    	{
	    		$loginUri .= "&scope=" . $this->_scope;
	    	}

	    	header('Location: ' . $loginUri );
    	}
    	else
    	{
    		// Looks like we have a code. Let's get ourselves an access token
	    	$client = new Zend_Http_Client( Zend_Auth_Adapter_Facebook::TOKEN_URI );
	    	$client->setParameterGet('client_id', $this->_appId);
	    	$client->setParameterGet('client_secret', $this->_secret);
	    	$client->setParameterGet('code', $code);
	    	$client->setParameterGet('redirect_uri', $this->_redirectUri);

	    	$result = $client->request('GET');
	    	$params = array();
	    	parse_str($result->getBody(), $params);

	    	// REtrieve the user info
	    	$client = new Zend_Http_Client(Zend_Auth_Adapter_Facebook::USER_URI );
	    	$client->setParameterGet('client_id', $this->_appId);
	    	$client->setParameterGet('access_token', $params['access_token']);
	    	$result = $client->request('GET');
	    	$user = json_decode($result->getBody());

            return new Zend_Auth_Result( Zend_Auth_Result::SUCCESS, $user->id, array('user'=>$user, 'token'=>$params['access_token']) );
    	}

        return new Zend_Auth_Result( Zend_Auth_Result::FAILURE, null, 'Error while attempting to redirect.' );
    }
}

/**
 * Sample Facebook Auth Controller.
 *
 * @author Michael Krotscheck
 */
class FacebookauthController extends Zend_Controller_Action
{
	/**
	 * Application default action
	 */
	public function indexAction ()
	{
		$appId = 'YOUR_APP_ID';
		$secret = 'YOUR_APP_SECRET';
		$redirectUri = 'http://path-to-this-controller-and-action';
		$scope = 'YOUR_COMMA_SEPARATED_APPLICATION_SCOPE';

		// Create the authentication adapter.
		$adapter = new Zend_Auth_Adapter_Facebook( $appId, $secret, $redirectUri, $scope );

		// Get an authenticator instance
		$auth = Zend_Auth::getInstance();

		// This call will automatically redirect to facebook with the passed parameters.
		$result = $auth->authenticate($adapter);

		if ( $result->isValid() )
		{
			// Get the messages
			$messages = $result->getMessages();

			// Get the user object from the returned messages.
			$fbUser = $messages['user'];

			var_dump($fbUser);
		}
	}
}

Cool, huhn? Security concerns aside (Believe me, I am never giving anything on facebook my credit card information), this isn’t exactly new- pushing product information into the Facebook stream was what the original Facebook Beacon was all about, and that was shut down via a class action lawsuit because it published user sales data without user approval. Additionally, pushing rich media applications into the Facebook stream is not new- anyone who’s viewed a youtube video in their Facebook stream knows how seamless that can be. What’s interesting though is that Resource has overcome the legal concerns with two changes: First, by giving users control of what to share when, and secondly by actually launching a full commerce application into something that people check every day.

If your initial reaction is disgust (“What? Another way for people to sell us their stuff? Blegh”) then you and I are pretty much on the same page, however don’t be blinded by other creative uses of this. For instance, if you want to buy someone a Christmas present, wouldn’t it be nice if you saw their wishlist items in the stream? What about gaming- if a friend of yours is playing some kind of a live flash mini game… wouldn’t you want to join them immediately? There are legitimate uses for this that don’t turn your stomach, so I figured I’d write a quick overview on how to put it together.

So how did they do that?

If you already have an application you want to run inside the Facebook news stream, then the process of getting it shareable is extremely simple, and is easily accessible to anyone who knows a little bit about flash, HTML metadata and the facebook platform. You have to perform the following tasks, most of which are trivial unless you are trying to do anything covered by a regulatory body (like accepting credit card information). For that you have to have a secure and federally accredited server, and that’s way outside of the scope of this article.

Step 1: Add the “Share on Facebook” link on the page in question.

The first thing you need to do is give your users the ability to actually share your page. This can be as easy as including a particularly formatted link in your product page or as complicated as including FBML in your site’s header and namespace. Note that the share URL can include URL parameters that will customize the content of the page, and should be pointed at the hosted URL of your flash application- this is crucial for step 2.

<a name="fb_share" type="button_count" href="http://www.facebook.com/sharer.php?u=[url to share]&t=[title of content]">Share</a><script src="http://static.ak.fbcdn.net/connect.php/js/FB.Share" type="text/javascript"></script>

Step 2: Add the correct meta tags to the page you want to share.

When a user clicks on the above link, it actually triggers the Facebook Sharer script to scrape the provided URL for metadata that tells it how to share this page. All of this data is contained in the metadata tags of a page, and you can read the extensive documentation here, however the important piece you’re looking for is how to share multimedia content. If you’ll read the documentation carefully, you’ll notice that while all references talk about video, in reality this share functionality allows you to display any flash content in the Facebook stream simply by replacing video_url with the URL to your flash SWF. This is still restricted to user action of course- nobody will see a flash app launched immediately, they’ll still see the icon and title as with any Youtube Video, and the application won’t launch until the user actually clicks on the icon.

<meta name="title" content="video_title" />
<meta name="description" content="video_description" />
<link rel="image_src" href="video_screenshot_image_src url" />
<link rel="video_src" href="video_src url"/>
<meta name="video_height" content="video_height" />
<meta name="video_width" content="video_width" />
<meta name="video_type" content="application/x-shockwave-flash" />

EDITORIALIZING: What worries me on this is that Facebook’s documentation is very clearly targeted at video sharing, and that this may be a violation of their intent of the sharer script. In short, what Resource is publishing as an innovation to social commerce is little more than a hack bolted into a loophole. Even so, I don’t believe Facebook will try to blacklist retailer sites to put this genie back in its bottle, because it both encourages use of their platform while also opening the gates to more legitimate uses. The ability to see that someone is, say, playing a game right now and your ability to join them is only a single click away puts an entire new spin on live online gaming, especially with the recent release of Adobe Collaboration Services, but I digress…

Step 3: Get your domain whitelisted by Facebook

If you paid especially close attention to the documentation linked above, you’ll also note that multimedia sharing won’t work if your domain is not whitelisted by Facebook. This is to protect Facebook from people who might want to distribute illegal content that would get them in trouble (licensed movies for instance), but also gives Facebook ultimate white and blacklist control over any activity they don’t want subverting their functionality. The process is actually extremely simple: Click this link, fill out the form, and wait for them to get back to you. Last time I did it it took less than 24 hours, but that was for a major retail site; your experience might vary.

That’s it. Enjoy!