Facebook Connect is a mechanism provided by Facebook that lets their users bring their identity and social experience to any website. The first step is authentication – let visitors login to your site with their Facebook accounts. This article explains how that works.

Context

This article is for web application developers learning how to implement Facebook Connect authentication in their websites. It is introductory and explains the interaction between the browser, Facebook and your website during authentication. The article also contains references to the sample Facebook Connect web application, The Turn Around, to point out where the actual function calls are.

Solution

The authentication process begins when user clicks on the Facebook Connect login button in your website. User will see a pop-up from Facebook and sign in with Facebook account details. Once user logs in, your website can retrieve Facebook user info like profile photo and will be able to write back to Facebook (e.g. publishing feed story in profile) if user grants the required specific permissions.

Exchange of handshakes, credentials, cookies and various function calls occur between the user browser, your website and Facebook server during the authentication process. They are illustrated in the interaction diagram below.

Facebook Connect Authentication - Interaction Diagram (click to enlarge)

1. User visits your website.
2. Your website checks with Facebook to see if user has already signed in using Facebook Connect.
3. Facebook says no. Using codes in TheRunAround as an example:
   1. index.php – checks if user has logged in Facebook via User::getLoggedIn()
   2. getLoggedIn() in lib/user.php – calls facebook_client() and retrieve the facebook user via Facebook::get_loggedin_user()
   3. facebook_client() in lib/fbconnect.php – creates Facebook object
   4. Constructor in facebook.php (in Facebook PHP library) – connects to facebook server using api_client, retrieves params via validate_fb_params() but will not get anything. As a result no user will be set
   5. get_loggedin_user() in facebook.php returns null which eventually gets passed back to index.php
4. Your website returns a page that displays a Connect with Facebook login button. In the sample app, this is done in render_fbconnect_button() in lib/fbconnect.php. Note how the button can be displayed by showing the image directly and calling the FB.Connect.requireSession(), or just by using the xFBML syntax.
5. User clicks on login button. FB.Connect.requireSession() is called
6. FB.Connect.requireSession() found that user has not logged in Facebook yet and display a “Connect with Facebook” pop-up. The pop-up could be in the form of pop-up window or an iFrame window depending on parameters. Note that starting from this step, it is part of the Facebook javascript library and is not open-sourced. Its API is available. This is also an example of the much-discussed “cross-site scripting”, as this is a page from your server dynamically loading a script from Facebook server.
7. User enters Facebook credentials.
8. Facebook verifies user credentials. Once verified, it calls the javascript callback function registered in waitUntilReady(). The callback function has been registered in facebook_onload() in fbconnect.js.
9. The callback function in facebook_onload() detects that session status has changed and refresh the page.
10. Step 1 is repeated again to check if user has logged in to Facebook.
11. Facebook says yes. User::getLoggedIn() will create and return a user object with a valid Facebook user ID.
12. Web page displays Facebook content such as profile photo, friends who are also using your website, etc.

Once connected, your website will be able to read from and write to the Facebook system on behalf of the logged in user via Facebook API.

Because of the many documents available online and the fact that many of them are outdated, downloading The Run Around sample application and studying it in detail is highly recommended.

Reference

• http://wiki.developers.facebook.com/index.php/Getting_Started_with_Facebook_Connect – The beginner’s guide to Facebook Connect.
• http://wiki.developers.facebook.com/index.php/Using_Facebook_Connect_with_Server-Side_Libraries – Facebook wiki doc explaining how server-side libraries are used.
• The Run Around – Sample Facebook Connect application provided by Facebook. Its source code is available for download.