You can get started by either downloading the complete project or if you would like to add Auth0 to an existing application you can follow the tutorial steps.

Before you start

This guide walks you through setting up authentication and authorization in your Django apps with Auth0. If you are new to Auth0 we suggest you check our Overview. For a complete picture of authentication and authorization for regular web apps, check our Single Sign-On for Regular Web Apps documentation.

Auth0 uses OAuth. If you want to learn more about the OAuth flows used by regular web apps, read about Authentication for Server-side Web Apps.

Get Your Application Keys

When you signed up for Auth0, you created a new client.

Your application needs some details about this client to communicate with Auth0. You can get these details from the Settings section for your client in the Auth0 dashboard.

You need the following information:

• Client ID
• Domain

Configure Callback URLs

A callback URL is a URL in your application where Auth0 redirects the user after they have authenticated.

You need to whitelist the callback URL for your app in the Allowed Callback URLs field in your Client Settings. If you do not set any callback URL, your users will see a mismatch error when they log in.

This guide will use social_django which is the Django implementation of Python Social Auth. It adds an OAuth stack to the user authentication & authorization system bundled by the Django Web Framework.

Install the Dependencies

Add the following dependencies to your requirements.txt:

django
social-auth-app-django
python-jose
six

Once the dependencies are listed in requirements.txt, run the following command:

pip install -r requirements.txt

Create a Django Project

This guide assumes you already have a Django application set up. If that is not the case, follow the steps in the Django Tutorial.

The sample project was created with the following commands:

$ django-admin startproject webappexample
$ cd webappexample
$ python manage.py startapp auth0login

Django Settings

The settings.py file contains the configuration of your Django project.

Add one entry for social_django and for your application into the INSTALLED_APPS entry.

# webappexample\settings.py

INSTALLED_APPS = [
    'social_django',
    '<your application name>'  # e.g. 'webappexample'
]

Add your Auth0 domain, the Client Id and the Client Secret. You can get this information the client settings in the Auth0 Dashboard.

# webappexample\settings.py

SOCIAL_AUTH_TRAILING_SLASH = False                    # Remove end slash from routes
SOCIAL_AUTH_AUTH0_DOMAIN = 'YOUR_AUTH0_DOMAIN'
SOCIAL_AUTH_AUTH0_KEY = 'YOUR_CLIENT_ID'
SOCIAL_AUTH_AUTH0_SECRET = 'YOUR_CLIENT_SECRET'

Set the SOCIAL_AUTH_AUTH0_SCOPE variable with the scopes the application will request when authenticating. Check the Scopes documentation for more information.

# webappexample\settings.py

SOCIAL_AUTH_AUTH0_SCOPE = [
    'openid',
    'profile'
]

Initialize the Database

The social_django application defined in INSTALLED_APPS requires a database. Run the following command to create all the required databases for the applications defined in INSTALLED_APPS:

$ python manage.py migrate

Create the Auth0 Authentication Backend

The social_django application is now configured. The next step is to create an authentication backend that bridges social_django with Auth0.

Create a file to implement the custom Auth0 authentication backend.

# auth0login/auth0backend.py

from six.moves.urllib import request
from jose import jwt
from social_core.backends.oauth import BaseOAuth2


class Auth0(BaseOAuth2):
    """Auth0 OAuth authentication backend"""
    name = 'auth0'
    SCOPE_SEPARATOR = ' '
    ACCESS_TOKEN_METHOD = 'POST'
    EXTRA_DATA = [
        ('picture', 'picture')
    ]
    
    def authorization_url(self):
        """Return the authorization endpoint."""
        return "https://" + self.setting('DOMAIN') + "/authorize"
    
    def access_token_url(self):
        """Return the token endpoint."""
        return "https://" + self.setting('DOMAIN') + "/oauth/token"
    
    def get_user_id(self, details, response):
        """Return current user id."""
        return details['user_id']
    
    def get_user_details(self, response):
        # Obtain JWT and the JWKS keys to validate the signature
        idToken = response.get('id_token')
        jwks = request.urlopen("https://" + self.setting('DOMAIN') + "/.well-known/jwks.json")
        issuer = "https://" + self.setting('DOMAIN') + "/"
        audience = self.setting('KEY') #CLIENT_ID

        # Decode the jwt to get the user information
        payload = jwt.decode(idToken, jwks.read(), algorithms=['RS256'], audience=audience, issuer=issuer)
        
        return {'username': payload['nickname'],
                'first_name': payload['name'],
                'picture': payload['picture'],
                'user_id': payload['sub']}

Register the authentication backends in settings.py. Add the custom backend for Auth0 and ModelBackend for users to be able to login with username/password method.

# webappexample\settings.py

AUTHENTICATION_BACKENDS = {
    'YOUR_DJANGO_APP_NAME.auth0backend.Auth0',
    'django.contrib.auth.backends.ModelBackend'
}

Configure the login, redirect login and redirect logout URLs as set below. The LOGIN_URL ends with auth0 as it needs to match the name property of the custom backend defined above.

# webappexample\settings.py

LOGIN_URL = "/login/auth0"
LOGIN_REDIRECT_URL = "/dashboard"
LOGOUT_REDIRECT_URL = "/"

Trigger Login with Social-Django

Add a handler for the index view in your views.py to render the index.html

# auth0login/views.py

def index(request):
    return render(request, 'index.html')

Add a link to /login/auth0 in the index.html template.

<!-- auth0login/templates/index.html -->

<div class="login-box auth0-box before">
    <img src="https://i.cloudup.com/StzWWrY34s.png" />
    <h3>Auth0 Example</h3>
    <p>Zero friction identity infrastructure, built for developers</p>
    <a class="btn btn-primary btn-lg btn-login btn-block" href="/login/auth0">Log In</a>
</div>

Access User Information

After the user is logged in, you can access the user information from the request.user property. Add a handler for the /dashboard endpoint in the views.py file.

# auth0login/views.py

from django.shortcuts import render
from django.contrib.auth.decorators import login_required
import json

@login_required
def dashboard(request):
    user = request.user
    auth0user = user.social_auth.get(provider="auth0")
    userdata = {
        'user_id': auth0user.uid,
        'name': user.first_name,
        'picture': auth0user.extra_data['picture']
    }
    
    return render(request, 'dashboard.html', {
        'auth0User': auth0user,
        'userdata': json.dumps(userdata, indent=4)
    })

Add the following snippet to dashboard.html to display the user information.

<!-- auth0login/templates/dashboard.html -->
<div class="logged-in-box auth0-box logged-in">
    <h1 id="logo"><img src="//cdn.auth0.com/samples/auth0_logo_final_blue_RGB.png" /></h1>
    <img class="avatar" src="{{ auth0User.extra_data.picture }}"/>
    <h2>Welcome {{ user.username }}</h2>
    <pre>{{ userdata }}</pre>
</div>

Logout

To log a user out, add a link to /logout in dashboard.html.

<!-- auth0login/templates/dashboard.html -->

<div class="logged-in-box auth0-box logged-in">
    <h1 id="logo"><img src="//cdn.auth0.com/samples/auth0_logo_final_blue_RGB.png" /></h1>
    <img class="avatar" src="{{ auth0User.extra_data.picture }}"/>
    <h2>Welcome {{ user.username }}</h2>
    <pre>{{ userdata }}</pre>
    <a class="btn btn-primary btn-lg btn-logout btn-block" href="/logout">Logout</a>
</div>

Add URL Mappings

In previous steps we added methods to the views.py file. We need to map those methods to URLs.

Django has a URL dispatcher that lets you map URL patterns to views.

Add mappings for the root folder, the dashboard folder, and the authentication applications in urls.py.

# auth0login\urls.py

urlpatterns = [
    url('^$', views.index),
    url(r'^dashboard', views.dashboard),
    url(r'^', include('django.contrib.auth.urls', namespace='auth')),
    url(r'^', include('social_django.urls', namespace='social')),
]