django-social-auth python

Django social authentication made simple


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.

You can check this documentation on Read the Docs_ too.


There’s a demo at Note: It lacks some backends support at the moment.


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:

    • Google OpenID_
    • Google OAuth_
    • Google OAuth2_
    • Yahoo OpenID_
    • OpenId_ like myOpenID_
    • Twitter OAuth_
    • Facebook OAuth_

Some contributions added support for:

* `LiveJournal OpenID`_
* `Orkut OAuth`_
* `Linkedin OAuth`_
* `Foursquare OAuth2`_
* `GitHub OAuth`_
* `Dropbox OAuth`_
* `Flickr OAuth`_
  • 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 that must be meet to use the application:

  • OpenId_ support depends on python-openid_

  • OAuth_ support depends on python-oauth2_

  • Several backends demands application registration on their corresponding sites.


From pypi_::

$ pip install django-social-auth


$ easy_install django-social-auth

or clone from github_::

$ git clone git://

and add social_auth to PYTHONPATH::

$ export PYTHONPATH=$PYTHONPATH:$(pwd)/django-social-auth/


$ cd django-social-auth
$ sudo python install


  • Add social_auth to PYTHONPATH and installed applications::

    INSTALLED_APPS = ( … ‘social_auth’ )

  • Add desired authentication backends to AUTHENTICATIONBACKENDS setting::

    AUTHENTICATION_BACKENDS = ( ‘social_auth.backends.twitter.TwitterBackend’, ‘social_auth.backends.facebook.FacebookBackend’, ‘’, ‘’, ‘’, ‘’, ‘social_auth.backends.contrib.linkedin.LinkedinBackend’, ‘social_auth.backends.contrib.livejournal.LiveJournalBackend’, ‘social_auth.backends.contrib.orkut.OrkutBackend’, ‘social_auth.backends.contrib.foursquare.FoursquareBackend’, ‘social_auth.backends.contrib.github.GithubBackend’, ‘social_auth.backends.contrib.dropbox.DropboxBackend’, ‘’, ‘social_auth.backends.OpenIDBackend’, ‘django.contrib.auth.backends.ModelBackend’, )

  • 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 AUTHENTICATIONBACKENDS or Django won’t pick them when trying to authenticate the user.

  • Define desired backends for your site::

    SOCIAL_AUTH_ENABLED_BACKENDS = (‘google’, ‘google-oauth’, ‘facebook’, …)

All backends are enabled by default.

  • Setup needed OAuth keys (see OAuth_ section for details)::


  • 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_

If a custom redirect URL is needed that must be different to LOGIN_URL, define the setting::

SOCIAL_AUTH_LOGIN_REDIRECT_URL = '/another-login-url/'

A different URL could be defined for newly registered users::

SOCIAL_AUTH_NEW_USER_REDIRECT_URL = '/new-users-redirect-url/'

or for newly associated accounts::

SOCIAL_AUTH_NEW_ASSOCIATION_REDIRECT_URL = '/new-association-redirect-url/'

or for account disconnections::

SOCIAL_AUTH_DISCONNECT_REDIRECT_URL = '/account-disconnected-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 = ‘socialauth_complete’ SOCIAL_AUTH_ASSOCIATE_URL_NAME = ‘socialauth_associate_complete’

  • Add URLs entries::

    urlpatterns = patterns(”, … url(r”, include(‘social_auth.urls’)), … )

All django-social-auth URLs names have socialauth_ prefix.

  • Define context processors if needed::

    TEMPLATE_CONTEXT_PROCESSORS = ( … ‘social_auth.context_processors.social_auth_by_type_backends’, )

check social_auth.context_processors.

  • Sync database to create needed models::

    ./ syncdb

  • Not mandatory, but recommended::

    SOCIAL_AUTH_DEFAULT_USERNAME = ‘new_social_auth_user’


import random
SOCIAL_AUTH_DEFAULT_USERNAME = lambda: random.choice(['Darth Vader', 'Obi-Wan Kenobi', 'R2-D2', 'C-3PO', 'Yoda'])


from django.template.defaultfilters 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 a random UUID-generated suffix in case it’s already taken. The UUID token max length can be changed with the setting::

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


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::


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::

  • 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::


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::


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

  • 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 = {...}
  • By default the application doesn’t make redirects to different domains, to disable this behavior::



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::


Take into account that when defining a custom User model and declaring signal handler in, 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::

from social_auth.signals import socialauth_registered 

def new_users_handler(sender, user, response, details, **kwargs):
    user.is_new = True
    return False

socialauth_registered.connect(new_users_handler, sender=None)


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::

<uppercase backend name>_SREG_EXTRA_DATA
<uppercase backend name>_AX_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_ 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


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

Settings must be a list of tuples mapping value name in response and value alias used to store.


Twitter offers per application keys named Consumer Key and Consumer Secret. To enable Twitter these two keys are needed. Further documentation at Twitter development resources_:

  • Register a new application at Twitter App Creation_,

  • mark the “Yes, use Twitter for login” checkbox, and

  • fill Consumer Key and Consumer Secret values::


  • You need to specify an URL callback or the application will be marked as Client type instead of the Browser. Almost any dummy value will work if you plan some test.


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::


  • also it’s possible to define extra permissions with::


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


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::


  • add any needed extra data to::


  • configure extra scopes in::


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.

  • fill Consumer Key and Consumer Secret values::


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::


shows ‘Social Auth’ by default, but that might not suite your application.

  • setup any needed extra scope in::


Check which applications can be included in their Google Data Protocol Directory_

Google OAuth2

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::


previous name GOOGLE_OAUTH2_CLIENT_KEY is supported for backward compatibility.

  • scopes are shared between OAuth mechanisms::


Check which applications can be included in their Google Data Protocol Directory_


LinkedIn setup is similar to any other OAuth service. To request extra fields using LinkedIn fields selectors_ just define the setting::


with the needed fields selectors, also define LINKEDIN_EXTRA_DATA properly, that way the values will be stored in UserSocialAuth.extra_data field.

By default id, first-name and last-name are requested and stored.


GitHub works similar to Facebook (OAuth).

  • Register a new application at GitHub Developers_, and

  • fill App Id and App Secret values in the settings::


  • also it’s possible to define extra permissions with::



Dropbox uses OAuth v1.0 for authentication.

  • Register a new application at Dropbox Developers_, and

  • fill App Key and App Secret values in the settings::



Flickr uses OAuth v1.0 for authentication.

  • Register a new application at the Flickr App Garden_, and

  • fill Key and Secret values in the settings::



To test the app just run::

./ test social_auth

This will run a bunch of tests, so far only login process is tested, more will come eventually.

User accounts on the different sites are needed to run tests, configure the credentials in the following way::

# twitter testing
TEST_TWITTER_USER = 'testing_account'
TEST_TWITTER_PASSWORD = 'password_for_testing_account'

# facebook testing
TEST_FACEBOOK_USER = 'testing_account'
TEST_FACEBOOK_PASSWORD = 'password_for_testing_account'

# google testing
TEST_GOOGLE_USER = '[email protected]'
TEST_GOOGLE_PASSWORD = 'password_for_testing_account'

There’s support for Selenium_ tests too on root contrib directory. To run install selenium::

$ pip install selenium

and create a copying and fill the needed account information. Then run::

cd contrib/tests


Join to django-social-auth_ community on Convore_ and bring any questions or suggestions that will improve this app.

South_ users should add this rule to enable migrations::

    import south
    from south.modelsinspector import add_introspection_rules
    add_introspection_rules([], ["^social_auth\.fields\.JSONField"])

If defining a custom user model, do not import social_auth from any that would finally import from the 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.


Maybe several, please create issues in github_


Attributions to whom deserves:

  • caioariede_ (Caio Ariede):

    • Improvements and Orkut support
  • krvss_ (Stas Kravets):

    • Initial configuration
  • jezdez_ (Jannis Leidel):

    • Improvements and documentation update
  • alfredo_ (Alfredo Ramirez)

    • Facebook and Doc improvements
  • mattucf_ (Matt Brown)

    • Twitter and OAuth improvements
  • Quard_ (Vadym Zakovinko)

    • LinkedIn support
  • micrypt_ (Seyi Ogunyemi)

    • OAuth2 migration
  • bedspax_

    • Foursquare support
  • revolunet_ (Julien Bouquillon)

    • GitHub support
  • danielgtaylor_ (Daniel G. Taylor)

    • Dropbox support
    • Flickr support
    • Provider name context processor


Base work is copyrighted by:

  • django-twitter-oauth::

    Original Copyright goes to Henrik Lied (henriklied) Code borrowed from

  • django-openid-auth::

    django-openid-auth - OpenID integration for django.contrib.auth Copyright © 2007 Simon Willison Copyright © 2008-2010 Canonical Ltd.

.. _Model Manager: .. _Login URL: .. _Login redirect URL: .. _AUTHENTICATION_BACKENDS: .. _auth.User: .. _auth.UserManager: .. _login_required: .. _User Profiles: .. _OpenId: .. _OAuth: .. _django-twitter-oauth: .. _django-openid-auth: .. _python-openid: .. _python-oauth2: .. _Twitter development resources: .. _Twitter App Creation: .. _dnsmasq: .. _Facebook development resources: .. _Facebook App Creation: .. _Google support: .. _Orkut API: .. _Google OpenID: .. _Google OAuth: .. _Google OAuth2: .. _OAuth2 Registering: .. _Google Data Protocol Directory: .. _OAuth2 draft: .. _OAuth reference: .. _Yahoo OpenID: .. _Twitter OAuth: .. _Facebook OAuth: .. _Linkedin OAuth: .. _Orkut OAuth: .. _myOpenID: .. _LiveJournal OpenID: .. _Foursquare OAuth2: .. _pypi: .. _github: .. _issues in github: .. _caioariede: .. _krvss: .. _jezdez: .. _alfredo: .. _mattucf: .. _Quard: .. _micrypt: .. _South: .. _bedspax: .. _django-social-auth: .. _Convore: .. _Selenium: .. _LinkedIn fields selectors: .. _Read the Docs: .. _revolunet: .. _GitHub OAuth: .. _GitHub Developers: .. .. _Dropbox OAuth: .. _Dropbox Developers: .. _Flickr OAuth: .. _Flickr App Garden: .. _danielgtaylor:

Related Repositories



Django social authentication made simple ...



An extension app for django-social-auth or django-allauth that fetches your friends from different social-networks. ...



Simple widget for django-social-auth ...



An extension to Django-Social-Auth which adds a backend for Tumblr ...



An extension to Django-Social-Auth which adds a backend for ...

Top Contributors

omab maraujop dokterbob danielgtaylor caioariede jezdez alexlovelltroy bernardokyotoku inve1 mattucf crodjer revolunet bedspax cassus JasonGiedymin roderyc micrypt georgedorn fcurella djm statico jkbrzt liorsion bashmish mzupan sidmitra


-   v0.5.13 zip tar
-   v0.5.12 zip tar
-   v0.5.11 zip tar
-   v0.5.9 zip tar
-   v0.5.8 zip tar
-   v0.5.7 zip tar
-   v0.5.6 zip tar
-   v0.5.5 zip tar
-   v0.5.4 zip tar
-   v0.5.3 zip tar
-   v0.5.2 zip tar
-   v0.5.1 zip tar
-   v0.5.0 zip tar
-   v0.4.2 zip tar
-   v0.4.1 zip tar
-   v0.4.0 zip tar
-   v0.3.20 zip tar
-   v0.3.19 zip tar
-   v0.3.18 zip tar
-   v0.3.17 zip tar
-   v0.3.16 zip tar
-   v0.3.15 zip tar
-   v0.3.14 zip tar
-   v0.3.13 zip tar
-   v0.3.12 zip tar
-   v0.3.11 zip tar
-   v0.3.10 zip tar
-   v0.3.9 zip tar
-   v0.3.8 zip tar
-   v0.3.7 zip tar