Developer Roadmap Update: Moving to OAuth 2.0 + HTTPS

We continue to make Platform more secure for users. Earlier this year, we introduced the ability for users to browse Facebook over HTTPS. As a result, we provided “Secure Canvas URL” and “Secure Tab URL” fields in the Developer App for developers to serve their apps through an HTTPS connection. Today, 9.6 million people are browsing Facebook over HTTPS and the trend is continuing to increase.

As part of these efforts to make our Platform more secure, we have been working to transition apps from the old Facebook authentication system and HTTP to OAuth 2.0 (an open standard co-authored with Yahoo, Twitter, Google, and others) and HTTPS. Because of the number of apps using our legacy auth system, we need to be thoughtful about this transition. Over the past few weeks, we determined that OAuth is now a mature standard with broad participation across the industry. In addition, we have been working with Symantec to identify issues in our authentication flow to ensure that they are more secure. This has led us to conclude that migrating to OAuth & HTTPs now is in the best interest of our users and developers.

Today, we are announcing an update to our Developer Roadmap that outlines a plan requiring all sites and apps to migrate to OAuth 2.0, process the signed_request parameter, and obtain an SSL certificate by October 1.

Migration to OAuth 2.0 + HTTPS timeline:

• July 1: Updates to the PHP and JS SDKs available that use OAuth 2.0 and have new cookie format (without access token).
• September 1: All apps must migrate to OAuth 2.0 and expect an encrypted access token.
• October 1: All Canvas apps must process signed_request (fb_sig will be removed) and obtain an SSL certificate (unless you are in Sandbox mode). This will ensure that users browsing Facebook over HTTPS will have a great experience over a secure connection.

We believe these changes create better and more secure experiences for users of your app. A migration plan below outlines the potential impact on your apps.

For Websites using the old Connect auth flow (not using the JavaScript or PHP SDK)

If you currently use the old Facebook Connect auth flow (login.php) directly, you will need to migrate to OAuth 2.0. If you’re directly referencing the JavaScript SDK, this change will happen automatically.

Old Facebook Authentication Flow:

<?php
  $url='http://www.facebook.com/login.php?api_key=[YOUR_API_KEY]    
  &connect_display=popup&v=1.0&next=[YOUR_URI]
  &cancel_url=http://www.facebook.com/connect/login_failure.html
  &fbconnect=true&session_key_only=true';

  header('location:' . $url);
?>

Facebook Platform supports two different OAuth 2.0 flows for user login: server-side (known as the authentication code flow in the specification) and client-side (known as the implicit flow). Implement this by reading our updated Authentication Guide. Please ensure that you are using OAuth 2.0 by September 1.

Using JavaScript and PHP SDKs

On July 1, we will have an updated JavaScript SDK and PHP SDK available that supports the upgraded auth flows as well as a modified cookie format that includes the code parameter. Once ready, we will publish a post on the update. If you’re directly referencing the JavaScript SDK, this change will happen automatically.

For Canvas Apps using fb_sig

In our legacy Canvas auth flow, we passed the fb_sig parameter to your app. After migrating to OAuth 2.0 by September 1, your apps may still need to rely on a session key for making API calls. For these apps, we will provide an endpoint to exchange the code parameter for the session key and session secret parameters. We will share the details of this exchange in an upcoming post.

Removing fb_sig

With the migration to OAuth 2.0, we are also removing fb_sig on October 1. We have provided additional time for this migration to the signed_request parameter.

The signed_request parameter contains a base64url encoded JSON object, which gives your app information about a user. The following PHP example demonstrates how to access the signed_request parameter and prompt the user to authorize your app:

<?php 
  $app_id = "YOUR_APP_ID";
  $canvas_page = "YOUR_CANVAS_PAGE_URL";

  $auth_url = "https://www.facebook.com/dialog/oauth?client_id=" 
   . $app_id . "&redirect_uri=" . urlencode($canvas_page);

  $signed_request = $_REQUEST["signed_request"];

  list($encoded_sig, $payload) = explode('.', $signed_request, 2); 

  $data = json_decode(base64_decode(strtr($payload, '-_', '+/')), 
    true);

  if (empty($data["user_id"])) {
    echo("<script> top.location.href='" . $auth_url . "'</script>");
  } else {
    echo ("Welcome User: " . $data["user_id"]);
  } 
?>

You can learn more about the signed_request parameter including how to validate the signature in our Signed Request Reference guide.

If you have any questions or feedback, please leave them in the Comments Box below. We understand that these migrations are significant and require a good amount of work. Our goal is to provide you with enough lead time and support you through this effort. We plan to follow up with updated docs, “How-To” blog posts, and emails to the primary developer account to help support getting your apps migrated to OAuth 2.0 and HTTPS. Having a single standard for authentication and apps served through HTTPS allows us to provide a simpler, more secure, and reliable Platform.