Facebook
========

Python Social Auth provides multiple backends for Facebook authentication:

- **FacebookOAuth2** (``social_core.backends.facebook.FacebookOAuth2``) - Standard Facebook OAuth2 authentication
- **FacebookAppOAuth2** (``social_core.backends.facebook.FacebookAppOAuth2``) - For Facebook Canvas Applications
- **FacebookLimitedLogin** (``social_core.backends.facebook_limited.FacebookLimitedLogin``) - For Facebook Limited Login (iOS SDK)

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.

- Add the Facebook OAuth2 backend to your ``AUTHENTICATION_BACKENDS`` setting::

    AUTHENTICATION_BACKENDS = (
        ...
        'social_core.backends.facebook.FacebookOAuth2',
        ...
    )

- 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 default, 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``.

Currently the backend uses Facebook API version `18.0` by default, but this can
be overridden by the following setting::

    SOCIAL_AUTH_FACEBOOK_API_VERSION = '19.0'

.. note::
    If you're using Facebook Graph API v3.0 or later, be aware that several
    parameters have been deprecated:

    - The ``display`` parameter (e.g., ``{'display': 'touch'}``) is no longer
      supported. Facebook now automatically detects mobile devices based on
      the user agent.
    - Make sure to check Facebook's `Graph API Changelog`_ for other deprecated
      features when upgrading to newer API versions.

.. _Graph API Changelog: https://developers.facebook.com/docs/graph-api/changelog


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)

- Add the Facebook Canvas Application backend to your ``AUTHENTICATION_BACKENDS`` setting::

    AUTHENTICATION_BACKENDS = (
        ...
        'social_core.backends.facebook.FacebookAppOAuth2',
        ...
    )

- 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`_.

.. _Facebook development resources: http://developers.facebook.com/docs/authentication/
.. _Facebook App Creation: https://developers.facebook.com/apps/
.. _Facebook Canvas Application Authentication: http://www.ikrvss.ru/2011/09/22/django-social-auth-and-facebook-canvas-applications/