Authentication guide
From Facebook Developers Wiki
Note: This article applies only to the old profile. You can read about how authentication works on the new profile.
Contents |
[edit] Logging In
The following is a detailed guide to the API login procedure. High level illustrations are available for logging in to a Web application and a desktop application.
In order for a Facebook API client to use the API, the user of the client application must be logged in to Facebook. To accomplish this, direct your users to: http://www.facebook.com/login.php?api_key=YOUR_API_KEY&v=1.0 or https://login.facebook.com/login.php?api_key=YOUR_API_KEY&v=1.0, which will prompt the user to log in if necessary. This URL supports these parameters:
| Parameter | Required | Description |
|---|---|---|
| api_key | ✔ | Uniquely assigned to the vendor, and identifies, among other things, the list of acceptable source IPs for this call |
| v | ✔ | The version of the API you are using. Should be set to "1.0". |
| next | A way for web-based applications to preserve some state for this login - this will get appended to their callback_url after the user logs in as described below. | |
| auth_token | ✔ for desktop | Before generating the login URL, the desktop application should call the auth.createToken API function, and then use the auth_token returned by that function here. |
| popup | An alternative style for the login page that does not contain any Facebook navigational elements. For the best results, the pop-up should ideally have the following dimensions: width=646 pixels, height=436 pixels. | |
| skipcookie | Pass this in to allow a user to re-enter their login information. This may be useful if another Facebook user previously forgot to log out. | |
| hide_checkbox | Pass this in to hide the Save my login info check box from the user. This may be useful if you don't want the user's session information to persist in your application. See Infinite sessions below for more information. | |
| canvas | If you pass this parameter, Facebook uses your canvas page URL instead of your callback URL as the base for the URL where we redirect the user. |
Upon successful authentication, if the user has never logged in to this application before, the user is asked to accept the terms of service for using the application. Finally, for Web-based applications, the user is redirected to the site callback_url + next + separator + auth_token=______, with these values as follows:
| Parameter | Required | Value |
|---|---|---|
| callback_url | The URL specified by the application developer on the account management page. If you passed the canvas page URL above, then this is the canvas page you set up instead (which then indirectly results in a request going to your callback URL). | |
| next | An optional string that can be passed in as a next parameter to login.php as described above. | |
| separator | Either ? or & depending on whether the URL already has a ? in it. | |
| auth_token | A string that the application should immediately exchange for a session key via the auth.getSession method. |
For desktop applications, the user is directed to close the browser window and return to the application, at which point the application should call auth.getSession over https passing in the same auth_token that was used as a parameter to login.php. (*NOTE* this has been found not to work by many people in the forums - however, supplying a callback_url, and using the (different) auth_token supplied there, does seem to work). For desktop applications, this method returns a secret which should be used in place of the desktop application's normal secret to sign all subsequent calls in this session.
[edit] Creating Infinite Sessions
For an extremely clear way on implementing infinite sessions with the PHP Client Library, see the infinite session howto.
By default, session keys returned by auth.getSession expire. Alternately, you can request a session key that never expires (and thus eliminate the need for users to log in to Facebook more than once). To do so, one of the following should happen:
- The user clicks the "Save my login info" box on the Facebook login page. By checking this box, the user is granting permission to generate an infinite session for your application.
- Your application directs the user to http://www.facebook.com/code_gen.php?v=1.0&api_key=YOUR_API_KEY. On that page, the user can generate an auth token. Your application should request this token from the user.
In both cases, the subsequent call to auth.getSession return a session key that does not expire. Note that there is no way to programmatically generate an infinite session without user approval. Once an infinite session has been established for a user and application, all subsequent calls to auth.getSession (that are otherwise valid) return the same session key. At any time, users can revoke their own sessions on the privacy page.
[edit] Requesting Authentication
Once a session has been established, the session key can be used to make request calls to the Facebook API. To make a request, the client should POST data to http://api.facebook.com/restserver.php. There are two types of requests - those that happen within the context of a session and those that do not require a session to exist. There are only two methods that happen outside the context of a session: auth.createToken and auth.getSession (which establishes the session).
These are the parameters required for all API calls:
| Parameter | Required | Description |
|---|---|---|
| method | ✔ | The method name. The method must be one of those exposed by the API documentation, or the API returns error code 3 (with message 'Unknown method'). |
| api_key | ✔ | The vendor-specific API key corresponding to the site making the API call. This is the same as in the login request. |
| sig | ✔ | The signature for the method call.
The signature is constructed using the following algorithm (after all the other arguments have been determined): args = array of args to the request, not counting sig, formatted in non-urlencoded arg=val pairs Below is an PHP example on how to generate the sig: <?php $argument1 = 'argument1'; ?> |
For desktop applications, be sure to use the secret returned by getSession when signing a call that include a session_key. If this is used in auth.createToken, use your application's secret key as the secret. These are the parameters required for all API calls except those that happen outside of the context of a session:
| Parameter | Description |
|---|---|
| session_key | The session key assigned to the user after they have logged in via the vendor page. This is the code returned to the application from the login request. This key may time out, after which the $API_EC_TIMEOUT error gets returned. The application then needs to redirect the user to the login page to obtain another key. |
| call_id | This is simply a number that must increase with each API call in a particular session. We strongly recommend using the current time in milli- or micro-seconds. In PHP, this can be set equal to microtime(true). |
Whether the request generates an error or not, an XML stream gets sent back to the application as a response to the request.
[edit] Logging Out
To enable a user to log out of Facebook, POST to http://www.facebook.com/logout.php, with the parameter confirm set to 1.
If you want the user to log out of a single application, use this tab on the privacy page.
