Adding Social Authentication to Django

by Real Python Nov 10, 2014 django python

Python Social Auth is a library that provides “an easy-to-setup social authentication / registration mechanism with support for several frameworks and auth providers”. In this tutorial, we’ll detail how to integrate this library into a Django project to provide user authentication.

What we’re using:

  • Django==1.7.1
  • python-social-auth==0.2.1

Django Setup

If you already have a project set up and ready to go, feel free to skip this section.

Create and activate a virtualenv, install Django, and then start a new Django project:

$ startproject django_social_project
$ cd django_social_project
$ python startapp django_social_app

Set up the initial tables and add a superuser:

$ python migrate
Operations to perform:
  Apply all migrations: admin, contenttypes, auth, sessions
Running migrations:
  Applying contenttypes.0001_initial... OK
  Applying auth.0001_initial... OK
  Applying admin.0001_initial... OK
  Applying sessions.0001_initial... OK

$ python createsuperuser
Username (leave blank to use 'michaelherman'): admin
Email address:
Password (again):
Superuser created successfully.

Create a new directory in the Project root called “templates”, and then add the correct path to the file:

    os.path.join(BASE_DIR, 'templates'),

Run the development server to ensure all is in order and then navigate to http://localhost:8000/. You should see the “It worked!” page.

Your project should look like this:

└── django_social_project
    ├── db.sqlite3
    ├── django_social_app
    │   ├──
    │   ├──
    │   ├── migrations
    │   │   └──
    │   ├──
    │   ├──
    │   └──
    ├── django_social_project
    │   ├──
    │   ├──
    │   ├──
    │   └──
    └── templates

Python Social Auth Setup

Follow the steps below and/or the official installation guide to install and setup the basic configuration.


Install with pip:

$ pip install python-social-auth==0.2.1


Update to include/register the library in our project:




Once registered, update the database:

$ python makemigrations
Migrations for 'default':
    - Alter field user on usersocialauth

$ python migrate
Operations to perform:
  Apply all migrations: admin, default, contenttypes, auth, sessions
Running migrations:
  Applying default.0001_initial... OK
  Applying default.0002_auto_20141109_1829... OK

Update the Project’s urlpatterns in to include the main auth URLs:

urlpatterns = patterns(
    url(r'^admin/', include(,
    url('', include('social.apps.django_app.urls', namespace='social')),

Next, you need to grab the required authentication keys form each social application that you want to include. The process is similar for many of the popular social networks - like Twitter, Facebook, and Google. Let’s look at Twitter as an example…

Twitter Authentication Keys

Create a new application at and make sure to use a callback url of

In the “django_social_project” directory, add a new file called Grab the Consumer Key (API Key) and the Consumer Secret (API Secret) from Twitter under the “Keys and Access Tokens” tab and add them to the config file like so:


Let’s also add the following URLs to to specify the login and redirect URLs (after a user authenticates):


Add the following import to

from config import *

Make sure to add to your .gitignore file, as you do not want this file added to version control since it contains sensitive information.

For more info, check the official docs.

Sanity Check

Let’s test this out. Fire up the server and navigate to, authorize the app, and if all works out, you should be redirected to (the URL associated with SOCIAL_AUTH_LOGIN_REDIRECT_URL). You should see a 404 error since we do not have a route, view, or template set up yet.

Let’s do that now…

Friendly Views

For now, we just need two views - login and home.


Update the URL patterns in

urlpatterns = patterns(
    url(r'^admin/', include(,
    url('', include('social.apps.django_app.urls', namespace='social')),
    url(r'^$', 'django_social_app.views.login'),
    url(r'^home/$', 'django_social_app.views.home'),
    url(r'^logout/$', 'django_social_app.views.logout'),

Besides the / and home/ routes, we also added the logout/ route.


Next, add the following view functions:

from django.shortcuts import render_to_response, redirect, render
from django.contrib.auth import logout as auth_logout
from django.contrib.auth.decorators import login_required
# from django.template.context import RequestContext

def login(request):
    # context = RequestContext(request, {
    #     'request': request, 'user': request.user})
    # return render_to_response('login.html', context_instance=context)
    return render(request, 'login.html')

def home(request):
    return render_to_response('home.html')

def logout(request):
    return redirect('/')

In the login() function, we grab the logged in user with the RequestContext. For your reference, the more explicit method of achieving this is commented out.


Add two templates home.html and login.html.


<p><a href="/logout">Logout</a>


{% if user and not user.is_anonymous %}
  <a>Hello, {{ user.get_full_name }}!</a>
  <a href="/logout">Logout</a>
{% else %}
  <a href="{% url 'social:begin' 'twitter' %}?next={{ request.path }}">Login with Twitter</a>
{% endif %}

Your project should now look like this:

└── django_social_project
    ├── db.sqlite3
    ├── django_social_app
    │   ├──
    │   ├──
    │   ├── migrations
    │   │   └──
    │   ├──
    │   ├──
    │   └──
    ├── django_social_project
    │   ├──
    │   ├──
    │   ├──
    │   ├──
    │   └──
    └── templates
        ├── home.html
        └── login.html

Test it out again. Fire up the server. Make sure to first logout, since a user should already be logged in from the last test, and then test logging in and logging out. After login, the user should be redirected to /home.

Next Steps

At this point, you’ll probably want to add a few more authentication providers - like Facebook and Google. The workflow is simple for adding a new social auth provider:

  1. Create a new application on the provider’s website.
  2. Set the callback URL.
  3. Grab the keys/tokens and add them to
  4. Add the new provider to the AUTHENTICATION_BACKENDS tuple in
  5. Update the login template by adding the new URL like so - <a href="{% url 'social:begin' 'ADD AUTHENTICATION PROVIDER NAME' %}?next={{ request.path }}">Login with AUTHENTICATION PROVIDER NAME</a>.

Please review the official docs for more information. Leave comments and questions below. Thanks for reading!

Oh—and be sure to grab the code from the repo.

🐍 Python Tricks 💌

Get a short & sweet Python Trick delivered to your inbox every couple of days. No spam ever. Unsubscribe any time. Curated by the Real Python team.

Python Tricks Dictionary Merge

What do you think?

Real Python Comment Policy: The most useful comments are those written with the goal of learning from or helping out other readers—after reading the whole article and all the earlier comments. Complaints and insults generally won’t make the cut here.

Keep Reading