The missing Django Allauth tutorial

This tutorial uses Django 1.8.4 and django allauth 0.24.1, and assumes that you have a basic familiarity with Django.

Django allauth is a powerful, easy-to-use authentication system, but the lack of official documentation can make it daunting, especially to beginners. Though there are several excellent third-party tutorials available, none were designed with Django 1.8 in mind. This tutorial aims to fill that gap.

In the interest of keeping things simple, I won’t go into social authentication, though that should be easy to set up once you have this running. In the next 400 words or so, I’ll explain:

If this gets enough views, I’ll add tutorials on the following:

Let’s get started!

Installation

You’re using a virtualenv, right? Allauth is in pypi, so installation is a cinch: just activate your virtualenv, and enter $ pip install django-allauth to install the latest version.

Settings

Your next step is to make a few changes to your settings.py file. Start by registering allauth in INSTALLED_APPS:

    INSTALLED_APPS = (
    ...
    'allauth',
    'allauth.account',
    ...
    ) 

Next, you need to manually set your SITE_ID variable in settings.py. Why? Because allauth uses this to fill in email and html templates with information about your site’s name and domain. First, add SITE_ID = 1 in settings.py.

Then run the localhost server and log in to your project’s admin at localhost:8000/admin. If you don’t yet have a superuser account yet you can create one by navigating to the root of your project and using the python manage.py createsuperuser command. Just follow the prompts to create a superuser.

After logging in to your admin you should see a Site section in the dashboard. Now you can change the site’s name and domain (unless your domain happens, through some freak accident, to be “example.com”).

Go back to settings.py, and add your authentication backends, like so:

AUTHENTICATION_BACKENDS = (
    # Needed to login by username in Django admin, regardless of `allauth`
    "django.contrib.auth.backends.ModelBackend",
    # `allauth` specific authentication methods, such as login by e-mail
    "allauth.account.auth_backends.AuthenticationBackend"
)

Last but not least, let’s tell allauth which url to route to when login is successful. Add LOGIN_REDIRECT_URL = '/awesome-page/' to your settings.py, and change ‘awesome-page’ to whatever page you want to redirect to after users successfully log in.

Routing

Now let’s focus on configuring our routers. Go to urls.py and add the following to your urlpatterns to register the allauth urls:

    urlpatterns = [
        ...
        #You don't have to use "accounts," but I recommend it to keep 
        #authentication separate from the rest of your app.  
        url(r'^accounts/', include('allauth.urls')), 
        ...
    ]

Now would be a good time to familiarize yourself with all the free urls that allauth comes with. These urls are a map of the fairy dreamland of easy password resets and email confirmations that allauth provides.

As a quick sanity check, let’s fire up our server and see if everything is working smoothly. Navigate back to your root directory, run python manage.py runserver and go to localhost:8000/accounts/login. You should see allauth’s hideous stock login form. Don’t worry - it’s easy to prettify these templates.

Custom Templates

Setting up allauth with custom templates is easy. Simply add an accounts directory to the templates directory in your app. To override an allauth template, just create a new .html file with the same name. In this case, you can create one for login.html.

You can use the login template in allauth.templates.account as an example. Just remember: if you’re copying allauth’s templates, you need to write a base.html to inherit from!

Success

You have your nice custom login page set up, right? If so, congrats! Try logging in with the superuser you already created, and see if it redirects to the LOGIN_REDIRECT_URL you specified in settings.py. That’s all there is to it!

Actually that’s not all there is to it - check out the list of configuration options in the allauth docs to see all the ways you can bend allauth to your will. You’ll probably need to use at least one or two of these to fit your use case.

If you’ve followed along this far, you should be good to go. Now sit back and watch as millions upon millions of users (or, let’s be honest, dozens) register with your beautiful, easy-to-use authentication system.