Legacy Connect Auth

We recently announced that all apps and sites must migrate to our OAuth 2.0 authentication mechanism by September 1, 2011. We released our OAuth implementation well over a year ago and many sites have already moved over. Nevertheless, there are a number of sites that still use the our legacy Connect authentication flow (login.php).

One of the issues with the legacy Connect flow is that it is possible for your site to accidentally pass authentication information to third parties. This can happen when including <iframe>, <img> or <script> content from third parties in the page that receives authentication data from Facebook. Our legacy mechanism passes authentication information in the URL query string which, if handled incorrectly, can be passed to third parties by the browser. The OAuth 2.0 authentication system passes this information in the URL fragment (or via a server-to-server call), which is not passed to third parties by the browser.

Allowing user ids and access tokens to be passed to third parties, even inadvertently, could allow these third parties to access the data the user made available to your site. This violates our policies and undermines user trust in your site and Facebook Platform.

If you cannot migrate to OAuth 2.0 and need to stay on the legacy Connect flow, you must create and use an interstitial page to remove the authentication data before redirecting to your page with third party content. This document walks through these steps. This approach is used by many of our largest developers today (although they are all migrating to OAuth 2.0 shortly). This is a simple and straightforward change that should have minimal impact on your site.

Legacy Login

Users start off by visiting your website without logging into Facebook first:

The legacy authentication flow is shown here in the following PHP snippet:

 $api_key = "YOUR_API_KEY";
 $interstitial_page = "YOUR_SECURE_URL"; //URL with no 3rd party apps

 $url='http://www.facebook.com/login.php?api_key=' . $api_key  
   . '&session_version=3&next=' . urlencode($interstitial_page)
   . '&v=1.0&return_session=1&fbconnect=1'
   . '&cancel_url=' . urlencode($interstitial_page);

 echo "Welcome to the Old Auth flow";
 echo "<p>";

 echo("<a href='" . $url . "'>"
   . "<img src='http://static.ak.facebook.com/images/"
   . "devsite/facebook_login.gif'></a>");

When users click on the Login button, they’ll get sent to a permission request page:

After the user clicks “Allow,” the user is sent to the the URL specified in $interstitial_page. To avoid any third parties unintentionally receiving authentication information, you must ensure that no third party content (typically referred to in <iframe>, <img> or <script> elements) exists on the page at $interstitial_page.

Handling authentication information on Interstitial Page

When the user is redirected to the $interstitial_page after authentication, you will receive the the session information in the URL query string. Specifically, you will receive the following fields (using PHP for this example):

On this interstitial page ($interstitial_page), you should remove any authentication information found in the query string, validate the information, store the data in a secure place, and the then redirect the user to the page containing any third party content.

Below is PHP sample code for the $interstitial_page, where we validate the Facebook session passed to the interstitial page by checking expected signature using your app_secret. save information in the PHP Session and redirect back to a page ($redirect_url) containing a third party content:

 <?php
   $redirect_url = "YOUR_URL?redirect=1";

   session_start();

   if($_REQUEST['session']) {
     //validate session
     $session = json_decode($_REQUEST['session'], true);
     $result = validateSessionObject($session);

     if($result) {
   $_SESSION['access_token'] = $session['access_token'];
   $_SESSION['uid'] = $session['uid'];

   //bounce back to original file
   echo("<script> top.location.href='" . $redirect_url . 
     "'</script>");
      }
   }
   else {
     echo 'You have failed to login.<p>';
     echo '<a href="http://www.myfbse.com/cat/connect_login.php">'
      . 'Click here to try again.</a>';
   }

   /**
    * Validates a session_version=3 style session object.
    *
    * @param Array $session the session object
    * @return Array the session object if it validates, null otherwise
    */
   function validateSessionObject($session) {

 $app_secret="YOUR_APP_SECRET";

     // make sure some essential fields exist
     if (is_array($session) && isset($session['uid']) &&
       isset($session['access_token']) &&
       isset($session['sig'])) {

       // validate the signature
       $session_without_sig = $session;
       unset($session_without_sig['sig']);

       $expected_sig = generateSignature($session_without_sig, $app_secret);

       if ($session['sig'] != $expected_sig) {
         print('Got invalid session signature in cookie.');
         $session = null;
       }
       // check expiry time
     } else {
     echo 'session is null';
     echo '<p>';
         $session = null;
     }
     return $session;
   }

   function generateSignature($params, $secret) {
     // work with sorted data
     ksort($params);

     // generate the base string
     $base_string = '';
     foreach($params as $key => $value) {
       $base_string .= $key . '=' . $value;
     }

     $base_string .= $secret;

     return md5($base_string);
   }
 ?>

If the $result is not null, you have a valid Facebook session and can proceed to save the access token and uid.

Redirecting to Page ($redirect_url) with third party content

When the user gets redirected to the page with third party content there is no longer information in the referer and you can proceed to make calls to the Graph API to display user data. Here is the sample PHP file (located at $redirect_url) that handles login using the old authentication flow and the redirect:

 <?php
   $app_id = "YOUR_APP_ID";
   $interstitial_page = "YOUR_INTERSTITIAL PAGE"; //URL with no 3rd party apps

   session_start();

   if($_REQUEST['redirect']) { //coming from $interstitial_page
     if(isset($_SESSION['access_token']) && isset($_SESSION['uid'])) {
       $graph_url = "https://graph.facebook.com/me?" .
         "access_token=" . $_SESSION['access_token'];

       $user = json_decode(file_get_contents($graph_url), true);

       echo "Hello " . $user['name'] . "!";
       echo "<p>";
     } 

     echo "Example 3rd party app";
     echo "<p>";
     echo "<iframe class='youtube-player' type='text/html'" . 
      "width='640' height='385' src='http://www.youtube.com/"
      . "embed/R3emjlgfNcY' frameborder='0'></iframe>";
   } 
   else { // first time on page
     echo "Welcome to the Old Auth flow";
     echo "<p>";

     $url='http://www.facebook.com/login.php?api_key=' . $app_id  
    . '&session_version=3&next=' . urlencode($interstitial_page)
    . '&v=1.0&return_session=1&fbconnect=1'
    . '&cancel_url=' . urlencode($interstitial_page);

     echo("<a href='" . $url . "'>"
    . "<img src='http://static.ak.facebook.com/images/"
    . "devsite/facebook_login.gif'></a>");

     echo "<p>";
   }

 ?>

See this flow in action here.