Legacy Canvas Auth

This document discusses our legacy Canvas authentication mechanism. We have moved to OAuth2.0 for Canvas pages by default. This document also covers how to migrate to our new approach.

---

Information Sent to your Application

Parameter Name	Description
fb_sig	Your application's Facebook signature. In order to verify a Facebook request to your canvas page, you need to remove _fb_sig__ from the rest of the keys before hashing them to verify against the signature contained in fb_sig.
fb_sig_added	If set to true, then the user has authorized your application.
fb_sig_api_key	Your application's API key.
fb_sig_user	The user ID. This is only passed once the user has authorized your application.
fb_sig_app_id	Your application's ID.
fb_sig_country	The user's country.
fb_sig_base_domain	The base domain from which your app is served.
fb_sig_in_canvas	When true, indicates the application is an FBML application; otherwise, it's not set.
fb_sig_in_iframe	When true, indicates the application is an IFrame application; otherwise, it's not set.
fb_sig_in_new_facebook	This is always true.
fb_sig_locale	The user's locale.
fb_sig_request_method	For FBML applications, indicates whether the request is a GET or a POST.
fb_sig_time	The current time, which is a UNIX timestamp.

---

Verifying Information

When Facebook sends you information about a user, you need to know that it is actually coming from Facebook. If you send a request to Facebook and receive a response, then you know that it comes from Facebook because you know who you asked. If a request comes in unsolicited, however, you need to authenticate that the user information is actually coming from Facebook servers.

The key to verification is the application secret. There are only two parties that know the secret: your application and Facebook. Whenever Facebook sends data to your server, it includes a signature that is generated using your application secret. You can perform the same encoding and check the signature to make sure it matches. If the signatures match, then you know the information came from Facebook.

Generating Your Own Signature

To generate the signature for the information Facebook sends you:

1. Remove the "fb_sig_" prefix from all of the parameter names (keys).
2. Sort the values alphabetically by the keys.
3. Concatenate all key/value pairs together in the format "k=v" (omitting the fb_sig parameter, since that is what we are calculating).
4. Append your application secret, which you can find by going to the Developer application and following the link for your application.
5. Generate an MD5 hash of the whole string.

The following PHP code provides a quick example of verifying information sent to an iFrame canvas application:

<?php 
    /* 
    typical use case: 
    process.php?string=$string&sig=fb_sig in process.php, 
    $string .= $secret and md5($string) == $_GET['fb_sig'] 
    */ 

    $fbsig = array(); 
    foreach($_GET as $key=>$value) { 
        if(substr($key,0,7) == 'fb_sig_') { 
            $fbsig[substr($key,7)] = $value; 
        } 
    } 
    ksort($fbsig); 
    foreach($fbsig as $key=>$value) { 
        $string .= $key . '=' . $value; 
    } 
    $string .= $secret;
    md5($string) == $_GET['fb_sig']; // this will return true. 
?>

---

Migrating to OAuth 2.0

As of December 10, 2010, OAuth 2.0 is the default authentication mechanism for Apps on Facebook.com.

Old Parameter Name	How to Migrate
fb_sig_added	Your application has been added if there is an oauth_token.
fb_sig_api_key	You should already know this in your application.
fb_sig_app_id	You should already know this. If you have 2 apps with the same endpoint, please give Facebook two different endpoints, and use a rewrite rule or something similar to send users to the same code.
fb_sig_canvas_user	Deprecated. Same as user_id.
fb_sig_expires	See expires.
fb_sig_ext_perms	See FQL Permissions Table.
fb_sig_friends	See /me/friends.
fb_sig_in_canvas	Assumed when there is not a profile_id and your application is an FBML app.
fb_sig_in_iframe	Assumed when there is not a profile_id and your application is an IFrame app.
fb_sig_in_profile_tab	Assumed when there is a profile_id.
fb_sig_is_admin	See /me/accounts.
fb_sig_is_fan	See /me/likes.
fb_sig_linked_account_ids	Deprecated.
fb_sig_logged_out_facebook	Deprecated. You only get to know if the user has logged into your app or not.
fb_sig_page_added	Your application has been added if there is an oauth_token.
fb_sig_page_id	See profile_id. You can check if it is a Page via the Graph API.
fb_sig_profile_session_key	See oauth_token.
fb_sig_profile_update_time	See /me.
fb_sig_profile_user	See profile_id.
fb_sig_session_key	Deprecated. Use the oauth_token for all API calls.
fb_sig_ss	Deprecated. Use the oauth_token.
fb_sig_time	Deprecated. Use your own servers's timestamp.
fb_sig_type	See 'category'.
fb_sig_user	See user_id.

To convert sessions, send a POST request to https://graph.facebook.com/oauth/exchange_sessions with a comma-separated list of sessions you want to convert:

curl -F client_id=your_app_id \
     -F client_secret=your_app_secret \
     -F sessions=session_key1,session_key2 \
     https://graph.facebook.com/oauth/exchange_sessions

The response from the request is a JSON array of OAuth access tokens in the same order as the sessions given:

[
  {
    "access_token": "...",
    "expires": 1271649600,
  },
  ...
]