
Facebook
********


OAuth2
======

Facebook uses OAuth2 for its auth process. Further documentation at
Facebook development resources:

* Register a new application at Facebook App Creation, don't use
  "localhost" as "App Domains" and "Site URL" since Facebook won't
  allow them. Use a placeholder like "myapp.com" and define that
  domain in your "/etc/hosts" or similar file.

* fill "App Id" and "App Secret" values in values:

     SOCIAL_AUTH_FACEBOOK_KEY = ''
     SOCIAL_AUTH_FACEBOOK_SECRET = ''

* Define "SOCIAL_AUTH_FACEBOOK_SCOPE" to get extra permissions from
  facebook. Email is not sent by deafault, to get it, you must request
  the "email" permission:

     SOCIAL_AUTH_FACEBOOK_SCOPE = ['email']

* Define "SOCIAL_AUTH_FACEBOOK_PROFILE_EXTRA_PARAMS" to pass extra
  parameters to https://graph.facebook.com/me when gathering the user
  profile data (you need to explicitly ask for fields like "email"
  using "fields" key):

     SOCIAL_AUTH_FACEBOOK_PROFILE_EXTRA_PARAMS = {
       'locale': 'ru_RU',
       'fields': 'id, name, email, age_range'
     }

If you define a redirect URL in Facebook setup page, be sure to not
define http://127.0.0.1:8000 or http://localhost:8000 because it won't
work when testing. Instead I define http://myapp.com and setup a
mapping on "/etc/hosts".


Canvas Application
==================

If you need to perform authentication from Facebook Canvas
application:

* Create your canvas application at
  http://developers.facebook.com/apps

* In Facebook application settings specify your canvas URL
  "mysite.com/fb" (current default)

* Setup your Python Social Auth settings and your application
  namespace:

     SOCIAL_AUTH_FACEBOOK_APP_KEY = ''
     SOCIAL_AUTH_FACEBOOK_APP_SECRET = ''
     SOCIAL_AUTH_FACEBOOK_APP_NAMESPACE = ''

* Launch your testing server on port 80 (use sudo or nginx or
  apache) for browser to be able to load it when Facebook calls canvas
  URL

* Open your Facebook page via http://apps.facebook.com/app_namespace
  or better via http://www.facebook.com/pages/user-name/user-id?sk
  =app_app-id

* After that you will see this page in a right way and will able to
  connect to application and login automatically after connection

* Provide a template to be rendered, it must have this JavaScript
  snippet (or similar) in it:

     <script type="text/javascript">
         var domain = 'https://apps.facebook.com/',
             redirectURI = domain + {{ FACEBOOK_APP_NAMESPACE }} + '/';

         window.top.location = 'https://www.facebook.com/dialog/oauth/' +
                                     '?client_id={{ FACEBOOK_KEY }}' +
                                     '&redirect_uri=' + encodeURIComponent(redirectURI) +
                                     '&scope={{ FACEBOOK_EXTENDED_PERMISSIONS }}';
     </script>

More info on the topic at Facebook Canvas Application Authentication.


Graph 2.0
=========

If looking for Graph 2.0 support, use the backends "Facebook2OAuth2"
(OAuth2) and/or "Facebook2AppOAuth2" (Canvas application).
