Authenticating Users with Facebook Connect
From Facebook Developer Wiki
One of the main goals of Facebook Connect is to make it as easy as possible for users to register for and log in to your website. At a high-level, authentication works as follows:
- When a user visits your site, you can use the Facebook Connect JavaScript library to detect whether the user has connected accounts between your site and Facebook.
- If the user is logged in to Facebook, you can either redirect the user to a logged-in view of your page or you can update the content of your page inline using JavaScript.
- If the user is logged out of Facebook, you can either display a login button on the current page or redirect the user to the login page for your site
- When the user clicks the login button, the Facebook Connect login process starts. When it is complete, we will call the JavaScript callback you registered
Contents |
Terminology
A user is connected with a particular site if that user has authorized that site (see Logging In And Connecting). Connecting with a site is analogous to authorizing an application inside of Facebook.
A user has disconnected from a site if they have removed that connection (e.g., via the Facebook Edit Applications page). Disconnecting is analogous to removing an application on Facebook.
A user is logged in if they are logged in to Facebook. When a user is logged in to Facebook, they are automatically logged in to all connected sites.
A user is logged out if they are not logged in to Facebook. When a user is logged out, they are logged out of Facebook and all connected sites.
Detecting Connect Status
When a user initially visits your site, the first thing that you want to do is detect whether that user has already connected with your site. The easiest way to do this is to use the FB.Connect.ifUserConnected JavaScript function. This function takes two arguments – a true argument (if the user is connected) and a false argument (if the user is not). Once the user's Connect status is determined, we will invoke either the true argument or the false argument.
For example, if your site has a default home page for logged-out users (like "/index.php") and another for logged-in users (like "/home.php"), then you can detect whether the user is logged in on index.php and redirect them as follows:
This means that if the user is logged in, go to /home.php. If the user is logged out, do nothing.
See documentation for this method and Detecting Connect Status for more details.
Note: If you are not using Facebook as your primary login mechanism, you can still use this approach to automatically log users into your site using your own account system. To do this, simply store a mapping from Facebook user IDs to your own account identifiers and then use the Facebook session to look up and use a local account on your site. See Account Linking for more details.
Logging Users into Your Site
If the user has not yet logged in or connected with your site, you will need to prompt the user to connect in order to use the Facebook Connect libraries.
The most straightforward way to do this is to use the Facebook Connect login button, using the fb:login-button XFBML tag:
This displays the following login button on your site:
When the user clicks the login button, Facebook displays a Connect dialog that allows the user to connect with your website. When the user successfully connects, the onlogin JavaScript argument gets invoked.
Note: The dialog appears as a JavaScript lightbox. However, you can choose to force a browser popup for authentication if you want. To do so, add "forceBrowserPopupForLogin":true to your FB.init dictionary. For example:
For details on the login flow, please see Logging In And Connecting. Also, a variety of Connect buttons are available for your use.
Logging In Users for the First Time
One of the goals of Facebook Connect is to make it as easy and streamlined as possible for users to register for your website. As such, Facebook recommends that you leverage the user’s existing profile and social graph to simplify the registration flow for first-time users. For example, most users have already configured a name, profile picture, gender, location, birthday, and so forth, so it’s not necessary to query the user for this information again. Similarly, by virtue of being a Facebook user, you know that the user already has a valid email address and has solved a CAPTCHA.
Logging Users Out of Your Site
Since a user is logged in to your site if they are logged in to Facebook and have connected with your site, logging a user out involves logging them out of both your site and Facebook. (The other alternative, disconnecting the user, is analogous to deleting an account on your site and should not be used for logout purposes.)
To log a user out of your site, you can use one of two methods – either FB.Connect.logout or FB.Connect.logoutAndRedirect. These calls log the user out of both your site and Facebook. The latter method also redirects the user once the logout dialog closes.
Disconnecting Users From Your Site
Users should have the option to permanently disassociate their Facebook account from your site on your site itself (they always have this option via the Facebook Edit Applications page). To sever this connection, you should use the auth.revokeAuthorization method in the PHP client library. This method can’t be called from the JavaScript client yet (however, this feature is coming soon).
When a user disconnects from your site (whether on Facebook or via auth.revokeAuthorization), Facebook notifies your registered Post-Remove URL (specified in your application settings). If your application caches any data about the user, you must register a valid Post-Remove URL. When you are notified that the user has disconnected, you must remove all cached information about that user from your system. Please see the Facebook Platform Terms of Service for more information.
For more details on the logout flow or disconnecting, please see Logging Out And Disconnecting.
Linking Profiles Only
It is possible to use Facebook Connect to augment existing profiles only by linking data from the user's Facebook profile with their profile on your site (instead of also allowing the user to log in to your site using their Facebook account). Note, however, that your Facebook user must be logged in to Facebook for the Facebook Connect library to retrieve data on their behalf. There are two approaches to achieving this:
- Prompting logged-out users to also log in to Facebook – if a user is logged in to your site but not logged in to Facebook, you can prompt them to also log in to Facebook using the instructions above.
- Requesting offline access – you can request the
offline_accesspermission using either FB.Connect.showPermissionDialog or fb:prompt-permission. This permission grants a long-lived session to the application. Because users may be reluctant to grant this permission for your application, it is not a generally recommended approach.
