The missing Django Allauth tutorial12 Jan 2016
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:
- How to install allauth
- How to configure your settings and urlconf
- How to get a simple sign-up and login page running using allauth’s stock templates
- How to override the allauth templates with your own (prettier) custom templates
If this gets enough views, I’ll add tutorials on the following:
- How to create a custom sign-up form with new fields
- How to use allauth with a custom User model
Let’s get started!
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.
Your next step is to make a few changes to your
settings.py file. Start by registering allauth in INSTALLED_APPS:
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
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:
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.
Now let’s focus on configuring our routers. Go to
urls.py and add the following to your urlpatterns to register the 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.
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!
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.