Skip to content
This repository

Django social authentication made simple

README.rst

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:

Dependencies

Dependencies that must be meet to use the app:

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

  • 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'])
    

    final user name will have an integer suffix in case it's already taken.

  • OAuth authentication will store access_token by default, set this value to False to avoid such behavior:

    SOCIAL_AUTH_EXTRA_DATA = False
    
  • 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 import FacebookBackend

def facebook_extra_values(sender, user, response, details):
    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:

SOCIAL_AUTH_CHANGE_SIGNAL_ONLY = False

is set to True.

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.

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 unregisterd applications.

Check next sections for details.

Twitter

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:

    TWITTER_CONSUMER_KEY
    TWITTER_CONSUMER_SECRET
    
  • You don't need to specify the URL callback

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 = [...]
    

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.

  • fill "Consumer Key" and "Consumer Secret" values:

    GOOGLE_CONSUMER_KEY
    GOOGLE_CONSUMER_SECRET
    

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:

  • caioariede (Caio Ariede):
    • Improvements and Orkut support
  • krvss (Stas Kravets):
    • Initial setup.py configuration
  • jezdez (Jannis Leidel):
    • Improvements and documentation update
  • alfredo (Alfredo Ramirez)
    • Facebook and Doc improvements
  • mattucf (Matt Brown)
    • Twitter and OAuth improvements

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.
    
Something went wrong with that request. Please try again.