How to Go From Zero to Access Token in Under 10 Minutes with Facebook’s OAuth 2.0

This excerpt from Mining the Social Web will help you get up and running with Facebook's OAuth 2.0 implementation.

---

As with any other OAuth-enabled app, to get started you’ll need to acquire an application ID and secret to use for authorization, opt into the developer community, and create an “application.” The following list summarizes the main steps, and some visual cues are provided below:

• First, if you don’t already have one, you’ll need to set up a Facebook account. Just go to http://facebook.com and sign up to join the party.
  
  
• Next, you’ll need to install the Developer application by visiting http://www.facebook.com/developers and clicking through the request to install the application.
  
  
• Once the Developer application is installed, you can click the “Set Up New Application” button to create your application.
  
  
• Once you’ve completed the security check, your app will have an ID and secret that you can use to complete the steps involved in Facebook’s OAuth 2.0 implementation, and you’ll be presented with a form that you’ll need to fill out to specify your application’s Web Site settings. Just enter the URL that you eventually plan to use for hosting your app as the Site URL and include the same domain as the Site Domain. Facebook uses your Web Site settings as part of the OAuth flow, and you’ll receive an error message during the OAuth dance if they’re not filled out appropriately.

From top to bottom: a) the button you’ll click from http://www.facebook.com/developers to set up a new application, b) the dialog you’ll complete to give your app a name and acknowledge the terms of service, c) your application now appears in the list of applications, and d) your app’s settings, including your OAuth 2.0 app ID and secret


It may not be obvious, but perhaps the simplest way for you to get back to your development application once you’ve left it is to just return to http://facebook.com/developers (requires a login).

With the basic details of application registration out of the way, the next step is writing a script that handles authentication and gets you an access token that you can use to access APIs. Our script will pop open a web browser, you’ll sign into your Facebook account, and then it’ll present a special code (your access token) that you’ll copy/paste into a prompt so that it can be saved out to disk and used in future requests. The example code below illustrates the process and is nothing more than a cursory implementation of the flow described in Desktop Application Authentication. A brief review of Facebook’s authentication documentation may be helpful. However, note that the flow implemented in the example below for a desktop application is a little simpler than the flow involved in authenticating a web app.

# -*- coding: utf-8 -*-

import os
import sys
import webbrowser
import urllib


def login():

    # Get this value from your Facebook application's settings

    CLIENT_ID = ''

    REDIRECT_URI = \
      'http://miningthesocialweb.appspot.com/static/facebook_oauth_helper.html'

    # You could customize which extended permissions are being requested on the login 
    # page or by editing the list below. By default, all the ones that make sense for  
    # read access as described on http://developers.facebook.com/docs/authentication/ 
    # are included. (And yes, it would be probably be ridiculous to request this much 
    # access if you wanted to launch a successful production application.)

    EXTENDED_PERMS = [
        'user_about_me',
        'friends_about_me',
        'user_activities',
        'friends_activities',
        'user_birthday',
        'friends_birthday',
        'user_education_history',
        'friends_education_history',
        'user_events',
        'friends_events',
        'user_groups',
        'friends_groups',
        'user_hometown',
        'friends_hometown',
        'user_interests',
        'friends_interests',
        'user_likes',
        'friends_likes',
        'user_location',
        'friends_location',
        'user_notes',
        'friends_notes',
        'user_online_presence',
        'friends_online_presence',
        'user_photo_video_tags',
        'friends_photo_video_tags',
        'user_photos',
        'friends_photos',
        'user_relationships',
        'friends_relationships',
        'user_religion_politics',
        'friends_religion_politics',
        'user_status',
        'friends_status',
        'user_videos',
        'friends_videos',
        'user_website',
        'friends_website',
        'user_work_history',
        'friends_work_history',
        'email',
        'read_friendlists',
        'read_requests',
        'read_stream',
        'user_checkins',
        'friends_checkins',
        ]

    args = dict(client_id=CLIENT_ID, redirect_uri=REDIRECT_URI,
                scope=','.join(EXTENDED_PERMS), type='user_agent', display='popup'
                )

    webbrowser.open('https://graph.facebook.com/oauth/authorize?'
                    + urllib.urlencode(args))

    # Optionally, store your access token locally for convenient use as opposed
    # to passing it as a command line parameter into scripts...

    access_token = raw_input('Enter your access_token: ')

    if not os.path.isdir('out'):
        os.mkdir('out')

    filename = os.path.join('out', 'facebook.access_token')
    f = open(filename, 'w')
    f.write(access_token)
    f.close()

    print >> sys.stderr, \
            "Access token stored to local file: 'out/facebook.access_token'"

    return access_token

if __name__ == '__main__':
    login()

One important detail you’re probably wondering about is the definition of EXTENDED_PERMS, and a brief explanation is certainly in order. The first time you try to log in to the application, it’ll notify you that the application is requesting lots of extended permissions so that you can have maximum flexibility in accessing the data that’s available to you (see the image below). The details of extended permissions are described in Facebook’s authentication documentation, but the short story is that, by default, applications can only access some basic data from user profiles—such as name, gender, and profile picture—and explicit permissions must be granted to access additional data. The subtlety to observe here is that you might be able to see certain details about your friends, such as things that they “like” or activity on their walls through your normal Facebook account, but your app cannot access these same details unless you have granted it explicit permission to do so. In other words, there’s a difference between what you’ll see in your friends’ profiles when signed in to facebook.com and the data you’ll get back when requesting information through the API. This is because it’s Facebook (not you) who is exercising the platform to get data when you’re logged in to facebook.com, but it’s you (as a developer) who is requesting data when you build your app.




Warning: If your app does not request extended permissions to access data but tries to access it anyway, you may get back empty data objects as opposed to an explicit error message.

Warning: The Facebook platform’s documentation is continually evolving, and they may not tell you everything you need to know about extended permissions. For example, it appears that in order to access religious or political information for friends (your friends_religion_politics extended permission), those friends must have your app installed and have explicitly authorized access to this data as well via their user_religion_politics extended permission.