django-duo-auth 0.1.5

A Django middleware that adds 2-factor authentication via Duo.

A Django middleware that adds 2-factor authentication via Duo.

django-duo-auth is designed to be easily integrated into an existing Django project to quickly add 2-factor authentication. It supports one or more Duo applications and uses the configured AUTHENTICATION_BACKENDS to select which users it should authenticate under which circumstance.

Installation

django-duo-auth can be installed from PyPI, and only depends on duo-web.

?> pip install django-duo-auth

Configuration

To enable Duo authentication, first add the following to settings.py:

# Add duo_auth to the list of installed apps
INSTALLED_APPS = [
    # ...
    'duo_auth',
]

# The DuoAuthMiddleware requires and must come after the SessionMiddleware
# and AuthenticationMiddleware
MIDDLEWARE = [
    # ...
    'duo_auth.middleware.DuoAuthMiddleware',
]

DUO_CONFIG = {
    'DEFAULT': {
        'HOST': '<api-host-url>',
        'IKEY': '<integration_key>',
        'AKEY': '<app_secret_key>',
        'SKEY': '<secret_key>',
        'FIRST_STAGE_BACKENDS': [
            'django.contrib.auth.backends.ModelBackend',
        ]
    }
}

Then include the URLs in urls.py:

from django.urls import path, include

urlpatterns = [
    # ...
    path('duo/',  include('duo_auth.urls')),
]

First Stage Backends

The FIRST_STAGE_BACKENDS key for each entry in DUO_CONFIG should be a list of the authentication backends that the Duo application should act as a second factor for. If an authentication backend isn’t listed in any FIRST_STAGE_BACKENDS list, then Duo is disabled.

Username Remapping

If it is necessary to remap a user’s name to a different name in Duo, you can add the USERNAME_REMAPPER key to a Duo Config entry. The value of USERNAME_REMAPPER should be a function, callable object, or a string containing the dotted path to a callable which accepts an HttpRequest object and returns a username string, which will be used in the Duo signing request instead of the name as it appears in request.user.username.

Overloading the Default Template

The Duo login view loads a template named duo_auth_form.html which must minimally include the following to properly render the Duo I-Frame:

<form method="POST" id="duo_form">
  {% csrf_token %}
  {% if next %}
    <input type="hidden" name="next" value="{{ next }}"/>
  {% endif %}
  {% if app_name %}
    <input type="hidden" name="app_name" value="{{ app_name }}"/>
  {% endif %}
 </form>

 <link rel="stylesheet" type="text/css" href="{{ duo_css_src }}">
 <script src="{{ duo_js_src }}"></script>
 <iframe id="duo_iframe"
         title="Two-Factor Authentication"
         frameborder="0"
         data-host="{{ duo_host }}"
         data-sig-request="{{ sig_request }}"
         data-post-action="{{ post_action }}"
         >
 </iframe>