Django Two-Factor Authentication Documentation¶

Complete Two-Factor Authentication for Django. Built on top of the one-time password framework django-otp and Django’s built-in authentication framework django.contrib.auth for providing the easiest integration into most Django projects. Inspired by the user experience of Google’s Two-Step Authentication, allowing users to authenticate through call, text messages (SMS) or by using a token generator app like Google Authenticator.

Contents:

Requirements¶

Django¶

Modern Django versions are supported. Currently this list includes Django 2.2, 3.0, and 3.1.

Python¶

The following Python versions are supported: 3.5, 3.6, 3.7 and 3.8 with a limit to what Django itself supports. As support for older Django versions is dropped, the minimum version might be raised. See also What Python version can I use with Django?.

django-otp¶

This project is used for generating one-time passwords. Version 0.8.x and above are supported.

django-formtools¶

Formerly known as django.contrib.formtools, it has been separated from Django 1.8 into a new package. Version 1.0 is supported.

Installation¶

You can install from PyPI using pip to install django-two-factor-auth and its dependencies:

$ pip install django-two-factor-auth

This project uses django-phonenumber-field which requires either phonenumbers or phonenumberslite to be installed. Either manually install a supported version using pip or install django-two-factor-auth with the extras specified as in the below examples:

$ pip install django-two-factor-auth[phonenumbers]

OR

$ pip install django-two-factor-auth[phonenumberslite]

Setup¶

Add the following apps to the INSTALLED_APPS:

INSTALLED_APPS = (
    ...
    'django_otp',
    'django_otp.plugins.otp_static',
    'django_otp.plugins.otp_totp',
    'two_factor',
)

Add the django-otp middleware to your MIDDLEWARE. Make sure it comes after AuthenticationMiddleware:

MIDDLEWARE = (
    ...
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django_otp.middleware.OTPMiddleware',
    ...
)

Point to the new login pages in your settings.py:

LOGIN_URL = 'two_factor:login'

# this one is optional
LOGIN_REDIRECT_URL = 'two_factor:profile'

Add the routes to your project url configuration:

from two_factor.urls import urlpatterns as tf_urls
urlpatterns = [
   path('', include(tf_urls)),
    ...
]

Warning

Be sure to remove any other login routes, otherwise the two-factor authentication might be circumvented. The admin interface should be automatically patched to use the new login method.

Yubikey Setup¶

In order to support Yubikeys, you have to install a plugin for django-otp:

$ pip install django-otp-yubikey

Add the following app to the INSTALLED_APPS:

INSTALLED_APPS = (
    ...
    'otp_yubikey',
)

This plugin also requires adding a validation service, through which YubiKeys will be verified. Normally, you’d use the YubiCloud for this. In the Django admin, navigate to YubiKey validation services and add an item. Django Two-Factor Authentication will identify the validation service with the name default. The other fields can be left empty, but you might want to consider requesting an API ID along with API key and using SSL for communicating with YubiCloud.

You could also do this using Django’s manage.py shell:

$ python manage.py shell

>>> from otp_yubikey.models import ValidationService
>>> ValidationService.objects.create(
...     name='default', use_ssl=True, param_sl='', param_timeout=''
... )
<ValidationService: default>

Configuration¶

General Settings¶

TWO_FACTOR_PATCH_ADMIN (default: True)

Whether the Django admin is patched to use the default login view.

Warning

The admin currently does not enforce one-time passwords being set for admin users.

TWO_FACTOR_CALL_GATEWAY (default: None)

Which gateway to use for making phone calls. Should be set to a module or object providing a make_call method. Currently two gateways are bundled:

'two_factor.gateways.twilio.gateway.Twilio' for making real phone calls using Twilio.
'two_factor.gateways.fake.Fake' for development, recording tokens to the default logger.

TWO_FACTOR_SMS_GATEWAY (default: None)

Which gateway to use for sending text messages. Should be set to a module or object providing a send_sms method. Currently two gateways are bundled:

'two_factor.gateways.twilio.gateway.Twilio' for sending real text messages using Twilio.
'two_factor.gateways.fake.Fake' for development, recording tokens to the default logger.

LOGIN_URL

Should point to the login view provided by this application as described in setup. This login view handles password authentication followed by a one-time password exchange if enabled for that account. This can be a URL path or URL name as defined in the Django documentation.

Twilio Gateway¶

To use the Twilio gateway, you need first to install the Twilio client:

$ pip install twilio

Next, add additional urls to your config:

# urls.py
from two_factor.gateways.twilio.urls import urlpatterns as tf_twilio_urls
urlpatterns = [
    path('', include(tf_twilio_urls)),
    ...
]

Additionally, you need to enable the ThreadLocals middleware:

MIDDLEWARE = (
    ...

    # Always include for two-factor auth
    'django_otp.middleware.OTPMiddleware',

    # Include for twilio gateway
    'two_factor.middleware.threadlocals.ThreadLocals',
)

class two_factor.gateways.twilio.gateway.Twilio¶

Gateway for sending text messages and making phone calls using Twilio.

All you need is your Twilio Account SID and Token, as shown in your Twilio account dashboard.

TWILIO_ACCOUNT_SID: Should be set to your account’s SID.
TWILIO_AUTH_TOKEN: Should be set to your account’s authorization token.
TWILIO_CALLER_ID: Should be set to a verified phone number. Twilio differentiates between numbers verified for making phone calls and sending text messages.
TWILIO_MESSAGING_SERVICE_SID: Can be set to a Twilio Messaging Service for SMS. This service can wrap multiple phone numbers and choose one depending on the destination country. When left empty the TWILIO_CALLER_ID will be used as sender ID.

Fake Gateway¶

class two_factor.gateways.fake.Fake¶

Prints the tokens to the logger. You will have to set the message level of the two_factor logger to INFO for them to appear in the console. Useful for local development. You should configure your logging like this:

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'console': {
            'level': 'DEBUG',
            'class': 'logging.StreamHandler',
        },
    },
    'loggers': {
        'two_factor': {
            'handlers': ['console'],
            'level': 'INFO',
        }
    }
}

Remember Browser¶

During a successful login with a token, the user may choose to remember this browser. If the same user logs in again on the same browser, a token will not be requested, as the browser serves as a second factor.

The option to remember a browser is deactived by default. Set TWO_FACTOR_REMEMBER_COOKIE_AGE to activate.

The browser will be remembered as long as

the cookie that authorizes the browser did not expire,
the user did not reset the password, and
the device initially used to authorize the browser is still valid.

The browser is remembered by setting a signed ‘remember cookie’.

In order to invalidate remebered browsers after password resets, the package relies on the password field of the User model. Please consider this in case you do not use the password field e.g. [django-auth-ldap](https://github.com/django-auth-ldap/django-auth-ldap)

TWO_FACTOR_REMEMBER_COOKIE_AGE

Age in seconds to remember the browser. The remember cookie will expire after the given time interval and the server will not accept this cookie to remember this browser, user and device any longer.

If this is set to a positive int the user is presented the option to remember the browser when entering the token. If the age is None, the user must authenticate with a token option during each login, if a device is setup.

Default: None

TWO_FACTOR_REMEMBER_COOKIE_PREFIX

Prefix of the remember cookie. It prefixes a uuid4 to allow multiple remember cookies on the same browser for multiple users.

Default: ‘remember-cookie_’

TWO_FACTOR_REMEMBER_COOKIE_DOMAIN

The domain to be used when setting the remember cookie.