FACEBOOK LOGIN API
Authorization and Authentication for Desktop Applications
A desktop application runs on a user's computer as an application; it doesn't run in a browser. Examples include Facebook for Adobe AIR or the Facebook Exporter for iPhoto
To use Facebook API calls from your desktop application, you need to trigger certain actions in a browser window such as login and permission dialogs.
Please note that this method only works if you can control a browser window (such as Webkit) directly...
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.
- If need be, you can take steps to end a user's session.
Detecting the User's Login State
When a user launches your application, you need to authenticate that user, detecting whether the user has authorized your application previously, or if the user has deauthorized it. You do this by validating the session when user launches your application again.
To check for the session, call users.getLoggedInUser
Make this call to the api.facebook.com/restserver.php. Facebook returns the user's user ID (UID). You should crosscheck the UID to make sure it matches the UID that was part of the session object returned from a previous call to login.php. If it doesn't match, you have to prompt the user to authorize your application again by redirecting the user to login.php, as described in Prompting for Permissions below.
You can also check the time for the expires parameter that was returned earlier to see if you need to re-authorize the user, in case the user didn't grant you a non-expiring session.
Logging In and Getting a Session
Facebook has made the desktop authorization process simpler. Desktop applications now use Facebook Connect for authentication. In order for you to authenticate your users, you need to launch display an HTML page in a frame within your application; don't create a separate popup window. To do this, you need to use WebKit or an equivalent programmatically controlled browser environment.
For information on how to frame an HTML page from within a desktop application, read one of the following articles for the environment in which you're developing:
- Adobe AIR applications
- .NET applications
- Objective C/Cocoa applications
Note: You no longer need to create an auth token, nor do you need to call auth.getSession (though this method still works, it's not as seamless as using Facebook Connect). This way you don't need to redirect the user to a browser to log in to Facebook; the user logs in from your application directly.
To log a user into a desktop application, when the user launches your application, direct the browser to www.facebook.com/login.php using WebKit (or your controlled browser environment of choice). Include the following URL parameters:
connect_display: Set to popup to display the login dialog as a popup window. Set to page to do a full-page redirect to the login page.
return_session=true. This requests a session from Facebook. The session gets stored in a cookie in your WebKit instance.
session_key_only: Set to true if you want to get a session for the user without logging the user out of any other Facebook sessions in any browser.
next=URL: The next URL to request after the user logs in to your application. This URL either can be a subdomain of your Connect URL (which you specify in your application settings) or it can be anywhere on the facebook.com domain, like www.facebook.com/connect/login_success.html.
cancel_url=URL: The next URL to request if the user cancels or otherwise cannot log in successfully. This URL either can be a subdomain of your Connect URL or it can be anywhere on Facebook, like www.facebook.com/connect/login_failure.html.
req_perms=permission,permission,permission: A comma-separated list of extended permissions you require from the user. The user cannot authorize your application without granting it these permissions. See Extended permissions#Requiring Extended Permissions for more information. If you there are optional permissions you would like from the user, prompt the user for them after the user authorizes your application. See Prompting for Permissions below.
For example, the full URL for logging in a user could be:
If the user is redirected to the URL specified by the next parameter, then Facebook grants your application a session. This session is appended to the URL as a JSON-decodable object of the form:
In continuing with the above example, the redirect for a successful login would be:
If the user grants your application the offline_access extended permission, 0 gets returned for expires and the session never expires unless the user removes the application. In this case, you should store the session key so the user doesn't have to log in the next time he or she launches your application.
Once the browser has been redirected successfully and you have your session information, you should automatically close the browser window.
To check for the session, call users.getLoggedInUser:
Make this call to the api.facebook.com/restserver.php. Facebook returns the user's user ID (UID). You should crosscheck the UID to make sure it matches the UID that was part of the session object returned from a previous call to login.php. If it doesn’t match, you have to prompt the user to authorize your application again by redirecting the user to login.php, as above.
Since this is within your desktop application, you may either direct the user's main browser to this URL, or create a window or browser within your own application to do this.Important: Use the Session Secret, not the Application Secret
When you configure an application with the Facebook Developer application, you are given an API key and an application secret. You can disregard the application secret and you should never include it in your desktop application's code, as it can be decompiled and used maliciously.
Instead, you get a session secret when the user authorizes your application, as described above. You should store it along with the session key, typically on the user's desktop where the user installed your application.
Desktop sessions last 24 hours, or until the user closes your application. The session secret expires when the session key does.
You can see which API methods you can call with a session secret When you sign your API calls using the session secret, you should append ss=true to every call.
Prompting for Permissions
There are two ways your desktop application can prompt a user for extended permissions
- When a user authorizes your application. Pass the req_perms parameter to login.php, as described above. You should use this method if having a certain permission, like read_stream, is necessary immediately after authorization.
- At any time in your application flow, where needed. Direct the user to www.facebook.com/connect/prompt_permissions.php.
When you direct the user to www.facebook.com/connect/prompt_permissions.php, append the following URL parameters:
- next=URL: The next URL to request after the user logs in to your application. This URL either can be a subdomain of your Connect URL (which you specify in your application settings) or it can be anywhere on the facebook.com domain, like www.facebook.com/connect/login_success.html. You need to include the xxRESULTTOKENxx parameter in the URL. The xxRESULTTOKENxx parameter gets replaced with a comma-separated string listing any permissions that the user granted to your application.
- ext_perm=PERMISSION,PERMISSION: A comma-separated string of the permissions you want the user to grant.
- enable_profile_selector: If one of the permissions you are requesting is publish_stream, and the current user is a Page admin, setting this URL parameter to '1' causes a dropdown list to appear in the permission dialog. This allowing the user to select for which Page(s) the permission should be granted. The dropdown contains only Pages for which the publish_stream permission hasn't been granted. If the user isn't the admin of any Pages, the dropdown list doesn't appear. After the user grants the permission, you can use the page admin (FQL) and the p (FQL)tables to query which Pages the user admininsters have the publish_stream permission.
- profile_selector_ids: A URL-encoded, comma-separated list of profile IDs used to filter the profiles in the profile selector.
For example, the full URL for prompting a user for the read_stream and publish_stream permissions could be:
The user then is prompted with a series of dialogs, one for each permission. The user can choose to grant some, none, or all of the permissions for which you are prompting. So, in the above example, if the user granted your application both permissions, the redirect would be:
To confirm the permissions a user granted your application, make the following FQL query (by calling fql.query) to restserver.php the next time that user launches your application:
This query returns the list of permissions that user or Page admin granted your application. If the user or Page admin removed any permissions since the last time the user launched your application, you can redirect the user to prompt_permissions.php and ask for them again.
Since this is within your desktop application, you may either direct the user's main browser to this URL, or create a window or browser within your own application to do this.Ending a User's Session
Users don't log out of desktop applications. A user's session expires after 24 hours, or when the user closes your application. If you need to, you can terminate a user's session by calling auth.expireSession
If you want, you can revoke a user's authorization of your application by calling auth.revokeAuthorization The user will have to authorize/connect to your application the next time the user launches it.
Finally, you can revoke extended permissions by calling auth.revokeExtendedPermissionSee Also
- How Facebook Authenticates Your Application
- Connect/Authentication and Authorization
- Authorization and Authentication for Facebook Connect Websites
- Authorization and Authentication for Facebook Connect for iPhone