According to the Facebook Developer Roadmap, all Facebook apps must migrate to OAuth 2.0.
If you are to start the migration, no matter you are using the PHP SDK v3.0 or not, I believe you will be reading the Facebook Authentication page from time to time.
To avoid any confusion and to save some of your time, I would like to share with you for what I have found wrong in the documentation.
In the new OAuth authentication flow, once Facebook has successfully authenticated the user, the OAuth Dialog will prompt the user to authorize the app. It is shown in the document that there are 2 buttons “Allow” and “Don’t Allow”. According to the document,
If the user presses Don’t Allow, your app is not authorized. The OAuth Dialog will redirect (via HTTP 302) the user’s browser to the URL you passed in the redirect_uri parameter with the following error information:http://YOUR_URL?error_reason=user_denied& error=access_denied&error_description=The+user+denied+your+request.
However, by executing the authentication flow in my application, I don’t see the “Don’t Allow” button and a “Leave Application” is shown instead.
By clicking the “Leave Application”, the user is simply redirected to his/her Facebook Profile page.
While I am using the PHP SDK v3.0 to build my application, I have double verified this “mistake” in the documentation by accessing the OAuth Dialog directly in my browser and the same “Leave Application” is displayed.
It is found that in order to have the “Don’t Allow” button shown, the redirect_uri must be within the same domain as the Site URL you specify in Web site tab of the Developer App. Otherwise, the “Leave Application” will be shown. In other words, for canvas application, if you are redirecting user to your application’s canvas page (i.e. something like http://apps.facebook.com/myapp/main.php), as the canvas page is not within your domain, the “Leave Application” is shown.
This makes sense for “simple applications” that requests for extended permission at their own index.php page as if the “Don’t allow” button is shown, then by clicking that, the user is very likely to be redirected back to the index.php page. But for application that request extended permission on a need-basis (i.e. necessary extended permissions are only requested when the user users/unlocks some particular functions), this does not make sense.
But WAIT!!! even for “simple applications”, the above “make sense” handling is working ONLY according to MY ASSUMPTION (which Facebook assumes also). What if my application has provided an “intro” page that will explain to the user what my app does and why I request for those permssion? So, it makes sense to request extended permission when the user visit my index.php, but if the user does not allow, then I would prefer to redirect the user to intro.php.