From Facebook Developer Wiki

This article describes how you implement authorization and authentication for your Facebook Connect site. For a high level summary about the benefits and best practices you can utilize, read Authentication and Authorization for Facebook Connect.

Authorization for Facebook Connect Websites

Since your site doesn't have a presence on Facebook, having your users authorize and log in to your site happens in a different manner than it does for an application on Facebook.

Authorizing and authenticating your users involves a series of tasks:

• You need to determine the user's Facebook login state.
• If the user isn't logged in to Facebook, direct the user to log in when logging in to your application.
• Once you have a user session, and you want to get more information from a user than what the API can offer, you can prompt the user for extended permissions.

Detecting Connect Status

When a user comes to your site, you need to detect if the user is logged in to Facebook and has connected to your site. When a user is logged in to both Facebook and your site, you can present the user with current Facebook data. Unlike a canvas application on Facebook, where users are either logged in or logged out of Facebook, users on Facebook Connect sites can be in one of three states:

• Connected: This state means that the user is logged in to Facebook and has already connected with your website. You must be in this state to make API calls on the user's behalf.
• Not logged in: This state means that the user is not logged in to Facebook. Because the user is not logged in to Facebook, we don't know whether the user has connected with your website. In order to make API calls on the user's behalf, you must first have the user log in (and potentially connect) with your site.
• Not authorized: This state means that the user is logged in to Facebook but has not yet connected with your website. In order to make API calls on the user's behalf, you must first have the user connect with your site.

For details, read: JS_API_T_FB.Connect#public_static_status and Detecting Connect Status.

Logging In Users

If the user isn't logged in, you need to prompt the user to connect your site with Facebook. There are two ways to prompt a user to log in to your site:

• Using the fb:login-button XFBML tag
• Using custom code

Logging In Using XFBML

Using the fb:login-button XFBML tag is the easiest way to have your users connect accounts. The tag renders a standard Facebook Connect button with one simple XFBML tag. You don't need to style your own button or write more detailed code.

First, add a few lines of JavaScript code (for full details, see Setting Up Your Site, but basically, you prompt users to connect accounts using the fb:login-button tag:

You can add an onlogin event handler to the tag so you can call a callback function after the user logs in:

This tag displays the following login button on your site:

You can specify the particular login button you want. See Facebook Connect Login Buttons for more information. Or you can create your own login button. See Creating a Custom Login Button for details.

Logging In Using Custom Code

If you don't want to use XFBML, there are two more advanced ways you can use to log users in to your site. The first method involves adding a few lines of JavaScript code (for full details, see Connect/Setting Up Your Site), then call the FB.Connect.RequireSession method from the JavaScript Client Library. You can pass a callback to this method.

Note: If your site is built with Flash, you must set isUserActionHint to true for FB.Connect.RequireSession to work.

You need to create a custom login button since you're not rendering the button with XFBML. See Creating a Custom Login Button for details.

Read more about FB.Connect.RequireSession.

Alternately, you can use an onclick handler in a simple HTML form. This only requires a bit of JavaScript, and the Facebook Connect dialog pops up in a new window.

This method is similar to how desktop applications log in users. See Authorization and Authentication for Desktop Applications for details on the URL parameters.

Getting a Session

Once the user connects accounts, the user is logged in to both your site and Facebook simultaneously. This process is known as single sign on. If this is a first-time user (that is, they're connecting with your site for the first time), Facebook also pings the Post-Authorize Callback URL specified in your application's settings, if such an URL exists, with a signature and a number of POST parameters.

After the user connects accounts, your site gets a session for the user. Sessions last an hour or until the user logs out of Facebook. For more information about sessions – how you use them, how you clear them – see Getting Started: Understanding Sessions. Once you have a session, you can make API calls to the Facebook RESTful server, api.facebook.com/restserver.php, and use the Facebook JavaScript Client Library.

Logging Out Users

A user is considered logged in to your site if they are logged in to Facebook and have connected with your site. Because of this, logging a user out of your site involves logging them out of both your website and Facebook. This is known as single sign out.

There are a number of ways you can log a user out of your site:

• You can use one of two JavaScript 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.
  
  <a href="#" onclick="FB.Connect.logoutAndRedirect('/index.php')">Logout</a>

• If you're using XFBML to render the login button, you can use the optional autologoutlink attribute on fb:login-button, which changes the login button to display Logout when the user is logged in.

• If you're using the onclick handler in an HTML form log in users, you can log them out by calling the PHP logout method:
  
  logout($next);

The next parameter is the function to call after the user logs out.

Why Does Facebook Do Single Sign Out?

Consider the case where the user is on a public computer -- at an internet cafe for example. If the user spends a lot of time on your site, then logs out of your site, they have to take the extra and deliberate step of logging out of Facebook. If the user forgets, then their Facebook session is still active for the next person who uses that computer.

Prompting for Extended Permissions

Extended permissions are special opt-in privileges a user grants to your site or application. These actions require a greater level of trust between a user and a site or application. Choose the permissions most applicable to your user experience. Typical permissions you might want include the ability to read from and publish to users' streams (the read_stream and publish_stream permissions, respectively) and the offline_access permission, which grants you a session that doesn't expire.

There are two ways you can prompt a user for extended permissions:

• Call FB.Connect.showPermissionDialog and pass in a string of permissions you want the user to grant your site. You can also pass a callback function to call after the user closes the last permission dialog.

• Use the fb:prompt-permission XFBML tag to render a link that, when clicked, displays a dialog for each permission you are requesting.

See Also

• Connect/Authentication and Authorization
• Authorization and Authentication for Facebook Connect for iPhone
• Authorization and Authentication for Desktop Applications