social_auth_by_name_backends:
Adds a social_auth dict where each key is a provider name and its value
is a UserSocialAuth instance if user has associated an account with that
provider, otherwise None.

social_auth_backends:
Adds a social_auth dict with keys are associated,
not_associated and backends. associated key is a list of
UserSocialAuth instances associated with current user.
not_associated is a list of providers names that the current user
doesn’t have any association yet. backends holds the list of backend
names supported.

social_auth_by_type_backends:
Simiar to social_auth_backends but each value is grouped by backend
type openid, oauth2 and oauth.

social_auth_login_redirect:
For man in the middle redirects (ie authenticating via a login
required decorator), a convenince query string can be added to your context
for templates. On your login options page:

Final user name will have a random UUID-generated suffix in case it’s already
taken. The UUID token max length can be changed with the setting:

SOCIAL_AUTH_UUID_LENGTH = 16

Backends will store extra values from response by default, set this to False
to avoid such behavior:

SOCIAL_AUTH_EXTRA_DATA = False

Also more extra values will be stored if defined, details about this setting
are listed below on OpenId and OAuth sections.

The update_user_details pipeline processor will set certain fields on user
objects, such as email. Set this to a list of fields you only want to
set for newly created users:

SOCIAL_AUTH_PROTECTED_USER_FIELDS = [‘email’,]

Session expiration time is an special value, it’s recommended to define:

SOCIAL_AUTH_EXPIRATION = 'expires'

and use such setting name where expiration times are returned. View that
completes login process will set session expiration time using this name if
it’s present or expires by default. Expiration configuration can be
disabled with setting:

These are needed to ensure a better django-auth integration, in other
case login_required won’t be usable. A warning is displayed if any of
these are missing. By default auth.User is used.

Check example application for implementation details, but first, please take
a look to User Profiles, it might be what you were looking for.

It’s possible to disable user creations by django-social-auth with:

SOCIAL_AUTH_CREATE_USERS = False

It is also possible to associate multiple user accounts with a single email
address, set value as True to enable, otherwise set as False to disable.
This behavior is disabled by default (False) unless specifically set:

SOCIAL_AUTH_ASSOCIATE_BY_MAIL = True

You can send extra parameters on auth process by defining settings per
provider, example to request Facebook to show Mobile authorization page,
define:

FACEBOOK_AUTH_EXTRA_ARGUMENTS = {'display': 'touch'}

For other providers, just define settings in the form:

<uppercase backend name>_AUTH_EXTRA_ARGUMENTS = {...}

Also, you can send extra parameters on request token process by defining
settings per provider in the same way explained above but with this other
suffix:

<uppercase backend name>_REQUEST_TOKEN_EXTRA_ARGUMENTS = {...}

By default the application doesn’t make redirects to different domains, to
disable this behavior:

SOCIAL_AUTH_SANITIZE_REDIRECTS = False

Inactive users can be redirected to a different page if this setting is
defined:

SOCIAL_AUTH_INACTIVE_USER_URL = '...'

Defaults to LOGIN_ERROR_URL.

The application catches any exception and logs errors to logger or
django.contrib.messagess application by default. But it’s possible to
override the default behavior by defining a function to process the
exceptions using this setting:

The function parameters will request holding the current request object,
backend with the current backend and err which is the exception
instance.

Recently this set of exceptions were introduce to describe the situations
a bit more than the old ValueError usually raised:

AuthException - Base exception class
AuthFailed - Authentication failed for some reason
AuthCanceled - Authentication was canceled by the user
AuthUnknownError - An unknown error stoped the authentication
process
AuthTokenError - Unauthorized or access token error, it was
invalid, impossible to authenticate or user
removed permissions to it.
AuthMissingParameter - A needed parameter to continue the process was
missing, usually raised by the services that
need some POST data like myOpenID

These are a subclass of ValueError to keep backward compatibility.

Having tracebacks is really useful when debugging, for that purpose this
setting was defined:

SOCIAL_AUTH_RAISE_EXCEPTIONS = DEBUG

It’s default value is DEBUG, so you need to set it to False to avoid
tracebacks when DEBUG = True.

When your project is behind a reverse proxy that uses HTTPS the redirect URIs
can became with the wrong schema (http:// instead of https://), and
might cause errors with the auth process, to force HTTPS in the final URIs
define this setting:

SOCIAL_AUTH_REDIRECT_IS_HTTPS = True

The name of the last backend used to login is stored as a string in the
session under the key social_auth_last_login_backend, the key can be
customized by defining this setting:

SOCIAL_AUTH_LAST_LOGIN = 'social_auth_last_login_backend'

Any urllib2.urlopen call will be performed with the default timeout
value, to change it without affecting the global socket timeout define this
setting (the value specifies timeout seconds):

SOCIAL_AUTH_URLOPEN_TIMEOUT = 30

urllib2.urlopen uses socket.getdefaulttimeout() value by default, so
setting socket.setdefaulttimeout(...) will affect urlopen when this
setting is not defined, otherwise this setting takes precedence. Also this
might affect other places in Django.

The ORM models can be replaced by providing the name of an alternate module
for the SOCIAL_AUTH_MODELS setting. The default is
'social_auth.db.django_models', which defines the Django ORM models that
were originally defined to implement Social Auth’s storage. The app provides
an example alternate based on MongoEngine. You can use it by setting:

The MongoEngine_ backend was developed and tested with version 0.6.10 of
MongoEngine_.

Alternate storage models implementations currently follow a tight pattern of
models that behave near or identical to Django ORM models. It is currently
not decoupled from this pattern by any abstraction layer. If you would like
to implement your own alternate, please see the
social_auth.db.django_models and social_auth.db.mongoengine_models
modules for guidance.

The final process of the authentication workflow is handled by a operations
pipeline where custom functions can be added or default items can be removed to
provide a custom behavior.

The default pipeline mimics the user creation and basic data gathering from
previous django-social-auth versions and a big set of settings (listed below)
that were used to alter the default behavior are now deprecated in favor of
pipeline overrides.

The default pipeline is composed by:

(
# Find UserSocialAuth object by backend and backend uid.
# Fail if UserSocialAuth already exists but not associated with
# the current user in the pipeline. Otherwise set the current user
# in the pipeline to be the user associated with UserSocialAuth
'social_auth.backends.pipeline.social.social_auth_user',
# Try to find an existing user that has the email address provided
# by the authentication backend. Fail if email addr. is not unique
'social_auth.backends.pipeline.associate.associate_by_email',
# If no user is found so far, generate a unique username based on
# configured settings
'social_auth.backends.pipeline.user.get_username',
# Depends on get_username. If no user is found so far, then create
# a new user based on the username returned by get_username
# If new user is created, set the current user in the pipeline to be
# the newly created user and set the is_new arg to be true and
# sends the socialauth_not_registered signal
'social_auth.backends.pipeline.user.create_user',
# If no instance of UserSocialAuth is found so far (through social_auth_user)
# create a new UserSocialAuth instance associated with the given user
'social_auth.backends.pipeline.social.associate_user',
# Take the extra data given by backend and store them in the
# UserSocialAuth instance's extra_data field, updating existing values
# Depends on an instance of UserSocialAuth to exist of course
'social_auth.backends.pipeline.social.load_extra_data',
# Update fields on the user object based on details provided by the
# authentication backend, skipping sensative fields such as username,
# id, pk, (and other provided in SOCIAL_AUTH_PROTECTED_USER_FIELDS if a
# user is already registered)
# Fires the pre_update signal before updating and socialauth_registered
# signal if is_new flag is set (by create_user pipeline)
'social_auth.backends.pipeline.user.update_user_details'
)

But it’s possible to override it by defining the setting
SOCIAL_AUTH_PIPELINE, for example a pipeline that won’t create users, just
accept already registered ones would look like this:

It’s possible to cut the pipeline process to return to the user asking for more
data and resume the process later, to accomplish this add the entry
social_auth.backends.pipeline.misc.save_status_to_session (or a similar
implementation) to the pipeline setting before any entry that returns an
HttpResponse instance:

When it’s time to resume the process just redirect the user to
/complete/<backend>/ view. By default the pipeline will be resumed in the
next entry after save_status_to_session but this can be modified by setting
the following setting to the import path of the pipeline entry to resume
processing:

User creation setting should be avoided and remove the entry create_user
from pipeline instead:

SOCIAL_AUTH_CREATE_USERS

Automatic data update should be stopped by overriding update_user_details
pipeline entry instead of using this setting:

SOCIAL_AUTH_CHANGE_SIGNAL_ONLY

Extra data retrieval from providers should be stopped by removing
load_extra_data from pipeline instead of using this setting:

SOCIAL_AUTH_EXTRA_DATA

Automatic email association should be avoided by removing
associate_by_email pipeline entry instead of using this setting:

SOCIAL_AUTH_ASSOCIATE_BY_MAIL

Associate URLs are deprecated since the login ones can handle the case, this
avoids issues where providers check the redirect URI and redirects to the
configured value in the application. So, from now on a single entry point is
recommended being:

A pre_update signal is sent when user data is about to be updated with new
values from authorization service provider, this apply to new users and already
existent ones. This is useful to update custom user fields or User Profiles,
for example, to store user gender, location, etc. Example:

New data updating is made automatically but could be disabled and left only to
signal handler if this setting value is set to True:

SOCIAL_AUTH_CHANGE_SIGNAL_ONLY = False

Take into account that when defining a custom User model and declaring
signal handler in models.py, the imports and handler definition must be
made after the custom User model is defined or circular imports issues will
be raised.

Also a new-user signal (socialauth_registered) is sent when new accounts
are created:

Almost every service covered provide some kind of API that is protected with
access_token or token pairs (like Twitter OAuth keys). These tokens are
gathered by the authentication mechanism and stored in
UserSocialAuth.extra_data.

UserSocialAuth has a property named tokens to easilly access this
useful values, it will return a dictionary containing the tokens values.
A simple usage example:

OpenId support is simpler to implement than OAuth. Google and Yahoo
providers are supported by default, others are supported by POST method
providing endpoint URL.

OpenId backends can store extra data in UserSocialAuth.extra_data field
by defining a set of values names to retrieve from any of the used schemas,
AttributeExchange and SimpleRegistration. As their keywords differ we
need two settings.

Settings is per backend, so we have two possible values for each one. Name
is dynamically checked using uppercase backend name as prefix:

Settings must be a list of tuples mapping value name in response and value
alias used to store. A third value (boolean) is supported to, it’s purpose is
to signal if the value should be discarded if it evaluates to False, this
is to avoid replacing old (needed) values when they don’t form part of current
response. If not present, then this check is avoided and the value will replace
any data.

OAuth communication demands a set of keys exchange to validate the client
authenticity prior to user approbation. Twitter, Facebook and Orkut
facilitates these keys by application registration, Google works the same,
but provides the option for unregistered applications.

Check next sections for details.

OAuth backends also can store extra data in UserSocialAuth.extra_data
field by defining a set of values names to retrieve from service response.

Settings is per backend and it’s name is dynamically checked using uppercase
backend name as prefix:

<uppercase backend name>_EXTRA_DATA

Example:

FACEBOOK_EXTRA_DATA = [(..., ...)]

Settings must be a list of tuples mapping value name in response and value
alias used to store. A third value (boolean) is supported to, it’s purpose is
to signal if the value should be discarded if it evaluates to False, this
is to avoid replacing old (needed) values when they don’t form part of current
response. If not present, then this check is avoided and the value will replace
any data.

Google provides Consumer Key and Consumer Secret keys to registered
applications, but also allows unregistered application to use their
authorization system with, but beware that this method will display a security
banner to the user telling that the application is not trusted.

Recently Google launched OAuth2 support following the definition at OAuth2
draft. It works in a similar way to plain OAuth mechanism, but developers
must register an application and apply for a set of keys. Check Google
OAuth2 document for details.

Note:

This support is experimental as Google implementation may change and OAuth2
is still a draft.

To enable OAuth2 support:

fill Client ID and Client Secret settings, these values can be
obtained easily as described on OAuth2 Registering doc:

GOOGLE_OAUTH2_CLIENT_ID = ''
GOOGLE_OAUTH2_CLIENT_SECRET = ''

previous name GOOGLE_OAUTH2_CLIENT_KEY is supported for backward
compatibility.

Instagram only allows one callback url so you’ll have to change your
urls.py to accomodate both /complete and /associate routes, for
example by having a single /associate url which takes
a ?complete=true parameter for the cases when you want to complete
rather than associate.

Currently there are 2 backends for Yandex, one is Yaru to log in using Ya.ru
service and another one is YandexOAuth that could use service API from
settings. Use YANDEX_OAUTH2_API_URL to set up which service to use.

Join to django-social-auth discussion list and bring any questions or
suggestions that would improve this application. Convore discussion group is
deprecated since the service is going to be shut down on April 1st.

If defining a custom user model, do not import social_auth from any
models.py that would finally import from the models.py that defines
your User class or it will make your project fail with a recursive import
because social_auth uses get_model() to retrieve your User.

There’s an ongoing movement to create a list of third party backends on
djangopackages.com, so, if somebody doesn’t want it’s backend in the
contrib directory but still wants to share, just split it in a separated
package and link it there.

Seems that this bug described in StackOverflow hits users using
django-social-auth with Python versions 2.7.2rev4 and 2.7.3 (so far) and
Facebook backend. The bug report #315 explains it a bit more and shows
a workaround fit avoid it.