Django Social Auth
Django Social Auth is an easy to setup social authentication/authorization
mechanism for Django projects.
Crafted using base code from django-twitter-oauth and django-openid-auth,
implements a common interface to define new authentication providers from
third parties.
Demo
There’s a demo at http://social.matiasaguirre.net/, it lacks Orkut support
at the moment.
Features
This application provides user registration and login using social sites
credentials, some features are:
Registration and Login using social sites using the following providers
at the moment:
Some contributions added support for:
Basic user data population and signaling, to allows custom fields values
from providers response
Multiple social accounts association to single users
Custom User model override if needed (auth.User by default)
Dependencies
Dependencies that must be meet to use the application:
Installation
From pypi:
$ pip install django-social-auth
or:
$ easy_install django-social-auth
or clone from github:
$ git clone git://github.com/omab/django-social-auth.git
and add social_auth to PYTHONPATH:
$ export PYTHONPATH=$PYTHONPATH:$(pwd)/django-social-auth/
or:
$ cd django-social-auth
$ sudo python setup.py install
Configuration
Add social_auth to PYTHONPATH and installed applications:
INSTALLED_APPS = (
...
'social_auth'
)
Add desired authentication backends to AUTHENTICATION_BACKENDS setting:
AUTHENTICATION_BACKENDS = (
'social_auth.backends.twitter.TwitterBackend',
'social_auth.backends.facebook.FacebookBackend',
'social_auth.backends.google.GoogleOAuthBackend',
'social_auth.backends.google.GoogleBackend',
'social_auth.backends.yahoo.YahooBackend',
'social_auth.backends.contrib.LiveJournalBackend',
'social_auth.backends.contrib.orkut.OrkutBackend',
'social_auth.backends.OpenIDBackend',
'django.contrib.auth.backends.ModelBackend',
)
Note: this was introduced in a recent change and it’s not backward
compatible, take into account that saved sessions won’t be able to login
because the backend string stored in session (like backends.TwitterBackend)
won’t match the new paths.
The application will try to import custom backends from the sources defined in:
SOCIAL_AUTH_IMPORT_BACKENDS = (
'myproy.social_auth_extra_services',
)
This way it’s easier to add new providers, check the already defined ones
in social_auth.backends for examples.
Take into account that backends must be defined in AUTHENTICATION_BACKENDS
or Django won’t pick them when trying to authenticate the user.
Setup Twitter, Facebook, Orkut and Google OAuth keys (see OAuth section
for details):
TWITTER_CONSUMER_KEY = ''
TWITTER_CONSUMER_SECRET = ''
FACEBOOK_APP_ID = ''
FACEBOOK_API_SECRET = ''
ORKUT_CONSUMER_KEY = ''
ORKUT_CONSUMER_SECRET = ''
GOOGLE_CONSUMER_KEY = ''
GOOGLE_CONSUMER_SECRET = ''
Setup login URLs:
LOGIN_URL = '/login-form/'
LOGIN_REDIRECT_URL = '/logged-in/'
LOGIN_ERROR_URL = '/login-error/'
Check Django documentation at Login URL and Login redirect URL
In case of authentication error, the message can be stored in session
if the following setting is defined:
SOCIAL_AUTH_ERROR_KEY = 'social_errors'
This defines the desired session key where last error message should be
stored. It’s disabled by default.
Configure authentication and association complete URL names to avoid
possible clashes:
SOCIAL_AUTH_COMPLETE_URL_NAME = 'complete'
SOCIAL_AUTH_ASSOCIATE_URL_NAME = 'associate_complete'
Add URLs entries:
urlpatterns = patterns('',
...
url(r'', include('social_auth.urls')),
...
)
Sync database to create needed models:
./manage syncdb
Not mandatory, but recommended:
SOCIAL_AUTH_DEFAULT_USERNAME = 'new_social_auth_user'
or:
import random
SOCIAL_AUTH_DEFAULT_USERNAME = lambda: random.choice(['Darth Vader', 'Obi-Wan Kenobi', 'R2-D2', 'C-3PO', 'Yoda'])
or:
from django.template.defaultfilter import slugify
SOCIAL_AUTH_USERNAME_FIXER = lambda u: slugify(u)
in case your user layout needs to purify username on some weird way.
Final user name will have an integer suffix in case it’s already taken.
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.
Session expiration time is an special value, it’s recommended to define:
SOCIAL_AUTH_EXPIRATION = 'expires'
to and use such setting name where expiration times are returned. View that
completes login process will set session expiration time to this value if
it’s present.
It’s possible to override the used User model if needed:
SOCIAL_AUTH_USER_MODEL = 'myapp.CustomUser'
This class must have a custom Model Manager with a create_user method
that resembles the one on auth.UserManager.
Also, it’s highly recommended that this class define the following fields:
username = CharField(...)
last_login = DateTimeField(blank=True)
is_active = BooleanField(...)
and the method:
is_authenticated():
...
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.
Signals
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:
from social_auth.signals import pre_update
from social_auth.backends.facebook import FacebookBackend
def facebook_extra_values(sender, user, response, details, **kwargs):
user.gender = response.get('gender')
return True
pre_update.connect(facebook_extra_values, sender=FacebookBackend)
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.
OpenId
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,
pettributeExchange 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:
<uppercase backend name>_SREG_EXTRA_DATA
<uppercase backend name>_AX_EXTRA_DATA
Example:
GOOGLE_SREG_EXTRA_DATA = [(..., ...)]
GOOGLE_AX_EXTRA_DATA = [(..., ...)]
Settings must be a list of tuples mapping value name in response and value
alias used to store.
OAuth
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.
Facebook
Facebook works similar to Twitter but it’s simpler to setup and
redirect URL is passed as a parameter when issuing an authorization.
Further documentation at Facebook development resources:
Register a new application at Facebook App Creation, and
fill “App Id” and “App Secret” values in values:
FACEBOOK_APP_ID
FACEBOOK_API_SECRET
also it’s possible to define extra permissions with:
FACEBOOK_EXTENDED_PERMISSIONS = [...]
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 or use dnsmasq.
Orkut
Orkut offers per application keys named “Consumer Key” and
“Consumer Secret”. To enable Orkut these two keys are needed.
Check Google support and Orkut API for details on getting
your consumer_key and consumer_secret keys.
fill “Consumer Key” and “Consumer Secret” values:
ORKUT_CONSUMER_KEY
ORKUT_CONSUMER_SECRET
add any needed extra data to:
ORKUT_EXTRA_DATA = ''
configure extra scopes in:
ORKUT_EXTRA_SCOPES = [...]
Google OAuth
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.
Check Google OAuth and make your choice.
anonymous values will be used if not configured as described in their
OAuth reference
configure the display name to be used in the “grant permissions” dialog
that Google will display to users in:
GOOGLE_DISPLAY_NAME = ''
shows ‘Social Auth’ by default, but that might not suite your application.
setup any needed extra scope in:
GOOGLE_OAUTH_EXTRA_SCOPE = [...]
check which Apps are included in their Google Data Protocol Directory
Bugs
Maybe several, please create issues in github
Contributors
Attributions to whom deserves:
Copyrights
Base work is copyrighted by:
django-twitter-oauth:
Original Copyright goes to Henrik Lied (henriklied)
Code borrowed from https://github.com/henriklied/django-twitter-oauth
django-openid-auth:
django-openid-auth - OpenID integration for django.contrib.auth
Copyright (C) 2007 Simon Willison
Copyright (C) 2008-2010 Canonical Ltd.