Adding Two-Factor Authentication to Django (with django-allauth)

Patrick Cloke

• Lead Software Engineer @ Percipient Networks working on Strongarm (https://strongarm.io)
• Mozillian (Instantbird & Mozilla Thunderbird instant messaging)
• github.com/clokep / bitbucket.com/clokep
• @clokep on Twitter
• http://patrick.cloke.us

Two-factor / mutli-factor / 2FA:

Requiring a login to have multiple pieces of evidence that a user owns an account.

Requires two pieces of evidence:

1. Knowledge (something the user knows): e.g. a password, passphrase, PIN.
2. Possession (something the user has): e.g. RSA SecureID, mobile devices / soft token, smart cards.
3. Inherence (something the user is): e.g. biometrics: fingerprint, retina, or voice.

Generally the second factor is a user's phone via one of two mechanisms:

• TOTP (Time-based One-Time Password Algorithm) [3], e.g. Google Authenticator, Microsoft Authenticator, Facebook Code Generator, etc. (See RFC 6238.)
• SMS / Text message

A reusable Django [5] package to work with authentication, registration, account management, and social authentication. [6]

• Supports both local (i.e. django.contrib.auth) and "social" accounts (e.g. OpenID, OAuth, OAuth2 providers)

  • Many social providers come pre-packaged (e.g. GitHub, Amazon, Twitter)

• Customizable (e.g. you can add custom providers, customize the "adapter")

• Supports multiple providers in the same Django application

• Supports multiple options for account verification (e.g. email)

A reusable package that adds two-factor authentication to django-allauth. It provides the glue between django-otp [8] and django-allauth.

• Views and middleware to modify the login workflow.
• Views for enabling/disabling two-factor authentication.
• Support for "backup" codes.
• Works with Django 1.8, 1.9, 1.10, and master.

A user enters their username & password, like normal.

• The user is prompted for their two-factor token.
• If successful, they are logged in as normal!

• Users are presented with a QR code for enabling two-factor authentication.
• This supports devices which can take a picture of the QR code (e.g. Google Authenticator, Microsoft Authenticator).

Once a user has two-factor enabled, they can:

• Disable it
• Create backup codes

• Backup codes are displayed if they've been generated.
• Each backup code can only be used once.

Install the package via pip [9].

pip install django-allauth-2fa

• Add django-allauth-2fa to the list of installed apps in settings.py.
• (Also add django-allauth, django-otp, and their dependencies.)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

INSTALLED_APPS = (
    'django.contrib.sites',  # Required by allauth.
    'django.contrib.auth',  # Configure Django auth package.
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'allauth',  # Enable allauth.
    'allauth.account',
    'django_otp',  # Configure the django-otp package.
    'django_otp.plugins.otp_totp',
    'django_otp.plugins.otp_static',
    'allauth_2fa',  # Enable two-factor auth.
)

Enable the django-allauth-2fa middleware in settings.py. [10]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

MIDDLEWARE_CLASSES = (
    # Configure Django auth package.
    'django.contrib.auth.middleware.AuthenticationMiddleware',

    # Configure the django-otp package. Note this must be after the
    # AuthenticationMiddleware.
    'django_otp.middleware.OTPMiddleware',

    # Reset login flow middleware. If this middleware is included, the login
    # flow is reset if another page is loaded between login and successfully
    # entering two-factor credentials.
    'allauth_2fa.middleware.AllauthTwoFactorMiddleware',
)

Configure django-allauth to use the django-allauth-2fa adapter in settings.py. (This enables the two-factor authentication login workflow.)

1
2
3
4
5
6

# Set the allauth adapter to be the 2FA adapter.
ACCOUNT_ADAPTER = 'allauth_2fa.adapter.OTPAdapter'

# Configure your default site. See
# https://docs.djangoproject.com/en/dev/ref/settings/#sites.
SITE_ID = 1

Include the django-allauth-2fa URLs/views.

1
2
3
4
5
6
7

from django.conf.urls import include, url

urlpatterns = [
    # Include the allauth and 2FA urls from their respective packages.
    url(r'^accounts/', include('allauth_2fa.urls')),
    url(r'^accounts/', include('allauth.urls')),
]

• You'll need to migrate your models before using django-allauth-2fa.
• django-allauth-2fa doesn't include models or migrations, but django-allauth and django-otp do.

1

python manage.py migrate

• More testing needed (different configurations, interaction with social accounts)
• Support for more device types (e.g. HOTP, YubiKey, Twilio)
• Support for multiple devices per user
• Improving the documentation (e.g. add a quickstart document)
• Setting up and adding translations
• Any other feedback you might have!

https://github.com/percipient/django-allauth-2fa/

https://pypi.python.org/pypi/django-allauth-2fa/

Please reach out if you have any questions!

Patrick Cloke

patrick@strongarm.io

Additionally, we're hiring!

https://strongarm.io/careers/

Slides available at https://github.com/percipient/talks/