As Facebook has beaten into me via my RSS reader over the last few months:

All apps must migrate to OAuth 2.0 for authentication and expect an encrypted access token. The old SDKs, including the old JS SDK and old iOS SDK will no longer work.

<digression> In the spirit of typical Facebook developer documentation, even this ostensibly unambiguous statement raises questions.  See, I have been using the “new” Graph API to authenticate for many months now, but not with the oauth flag set to true.  (In other words, I am on Oauth 1.0?)  Does this mean my code will break on Oct. 1st?  Or when they say that legacy authentication will break on Oct. 1st, do they mean that only the really old legacy auth will break?  In either case, I may as well upgrade to the latest and greatest now. </digression>

Here are the changes I had to make to get my stuff working with the oauth flag set to true.  They are mostly field and param name changes.  There may be other changes important to you, but this is what I needed to modify to upgrade.

1. Add ‘oauth: true‘ to FB.init()

So change this:

FB.init({ appId : XXXXXX });

to this:

FB.init({ appId : XXXXXX, oauth : true });

I infer from Facebook (which is usually dangerous) that this flag will be enabled for everyone on Oct. 1st.

2. Change ‘perms‘ to ‘scope‘

Anywhere you request permissions for your app upon Facebook login, you must change the ‘perms’ field to ‘scope’. So for a typical XFBML implementation, change this:

<fb:login-button perms=”offline_access”></fb:login-button>

to this:

<fb:login-button scope=”offline_access”></fb:login-button>

For a typical JS implementation, change this:

FB.login(function(response) { }, { perms : ‘offline_access’ });

to this:

FB.login(function(response) { }, { scope : ‘offline_access’ });

For a typical non-JS, server-side (PHP) implementation, change this:

<a href=”<?php echo $facebook->getLoginUrl(array(‘req_perms’ => ‘offline_acces's’)); ?>”>Connect with Facebook</a>

to this:

<a href=”<?php echo $facebook->getLoginUrl(array(‘scope’ => ‘offline_acces's’)); ?>”>Connect with Facebook</a>

3. Update JavaScript response object

Functions like FB.login() and FB.getLoginStatus() accept a callback that gets passed a response object from Facebook after an authentication attempt.  The previous response looked like this:

response = { perms : ‘offline_access’, 
             session : { 
               access_token : ‘XXXXXX’, 
               base_domain : ‘mydomain.com’, 
               expires : ‘0’, 
               secret : ‘XXXXXX’, 
               session_key : ‘XXXXXX’, 
               sig : ‘XXXXXX’, 
               uid : ‘XXXXXX’ }, 
             status : ‘connected’ };

The new response looks like this:

response = { authResponse : { 
               accessToken : ‘XXXXXX’, 
               expiresIn : 0, 
               signedRequest : ‘XXXXXX’, 
               userID : ‘XXXXXX’ }, 
             status : ‘connected’ };

You must update your JS authentication logic accordingly.

4. Change server-side PHP call getSession() to getUser()

Versions of the PHP SDK prior to 3.0 had both a getSession() and a getUser() method. After 3.0, there is only the getUser() call.  If you were using getSession() to check for authentication previously, you must use getUser() now.  If you don’t care about the internals of the new SDK, then getUser() functions the same as before and returns the Facebook ID of the currently logged in user, or 0 if there is none.

If you do care about the new SDK, then the reason for this is because Facebook has done away with the session concept and embraced the OAuth2 signed_request concept instead.  For example, the JSON-ified session array is no longer passed back to your callback URL in the query string upon authentication.  Now, an encoded signed_request is passed back in the query string, which contains the same info (user ID, access token, expiration time, etc.)

5. Change server-side PHP Facebook class constructor

The new PHP Facebook class no longer accepts a cookie flag in the constructor.  If you don’t care about the internals of the new SDK, then remove the cookie flag and you’re done.

If you do care about the new SDK, then the reason for this – well, I’m not sure what the reason is.  Perhaps a commenter could enlighten me.  Best as I can tell, they have removed overlapping features of the the JS SDK and PHP SDK. Prior to OAuth2, both SDKs had cookie flags, and both could set and read the session cookie, which could be confusing, especially if you were persisting your own authentication cookie.  Now, the JS can still set and read the signed_request cookie, but the PHP library has gotten out of the cookie game (although it can still read a signed_request cookie set by JS, and now it stores the signed_request data in the PHP session).

One more note about cookie: the new Facebook cookie begins with ‘fbsr_’ and not ‘fbs_’.

Conclusion

That’s it. As I said, these worked for me, but YMMV. Happy upgrading!