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.

You are trying to implement Facebook Connect in your site so that your visitors can log in to your site using their Facebook accounts. You followed the simplest example available in
a Facebook wiki document, however for some reason the “Connect with Facebook” button does not seem to do anything – no pop-up, no error, nothing. Why is that?

Context

This article is for those who want to implement Facebook Connect in their websites. It explains the scenario when a simple Facebook Connect login button does not seem to work.

Solution

The login button does not do anything most likely because you have not set it up to do anything.

The basic example shown in this Facebook developers wiki page: http://wiki.developers.facebook.com/index.php/Connect/Setting_Up_Your_Site has instructions in great detail, however it has not mentioned clearly that it actually only shows you how to display a Facebook Connect login button.

The test.html described in the wiki page is


<html xmlns="http://www.w3.org/1999/xhtml" xmlns:fb="http://www.facebook.com/2008/fbml">
<head></head>
<body>
<script src="http://static.ak.connect.facebook.com/js/api_lib/v0.4/FeatureLoader.js.php" type="text/javascript"></script>
<fb:login-button></fb:login-button>
<script type="text/javascript">
FB.init("YOUR_API_KEY_HERE", "xd_receiver.htm");
</script>
</body>
</html>


If all instructions in the wiki page have been followed correctly, clicking on the resultant Connect-with-Facebook login button should trigger a Facebook login form to appear in a pop-up window, given that the user has not logged in to Facebook yet.

If user has logged in to Facebook and clicks on the login button for the first time, a pop-up will appear to ask the user to authorize the integration between your website and Facebook.

Once user logs in via the pop-up window or agrees on the Facebook Connect authorization, clicking on the login button will no longer trigger any actions because user is now “connected” and there is no “callback function” specified in the html file.

To make it slightly more confusing, the authorization pop-up will only appear once: Even after you clear all the cookies and log out of Facebook in an attempt to start from the beginning, the login button will no longer trigger any actions if you log in Facebook again and click on the test login button. This is because Facebook remembers your authorisation from its servers.

When the wiki page says “Optionally, you can add a JavaScript handler to the callback function to call when the user logs in”, it actually meant “Unless you want user to see no changes after logging in, you need to add a JavaScript handler…”.

So how do you specify a “callback function” and how does Facebook Authentication work? A separate article has been written to answer this question.