Package: django-duo-universal-auth
django-duo-universal-authA lightweight middleware application that adds a layer on top of any number of existing authentication backends, enabling 2FA with the user's Duo account using theUniversal Promptafter signing in with your Django application.Note:In order to interface this middleware with Duo, you must create a newDuo Web SDKapplication from within your organization's Duo Admin Portal and enable the "Show new Universal Prompt" setting. You will acquire a Client ID, Client Secret, and API Hostname, of which you will include in yoursettings.pyfile in the format listed below. It is strongly recommended not to hardcode these values in the settings file itself.FromDuo's documentation for protecting applications:Treat your Secret key or Client ID like a passwordThe security of your Duo application is tied to the security of your Secret key (skey) or Client secret (client_secret). Secure it as you would any sensitive credential. Don't share it with unauthorized individuals or email it to anyone under any circumstances!InstallationTo install the middleware application, use the followingpipcommand (or equivalent for your package manager application):pipinstalldjango-duo-universal-authSample Configuration (in yoursettings.pyfile)First, add the package to yourINSTALLED_APPSlist variable:INSTALLED_APPS=[# ...'duo_universal_auth',# Add this!]Next, add the path for the middleware application to theMIDDLEWARElist variable:MIDDLEWARE=[# ...'duo_universal_auth.middleware.DuoUniversalAuthMiddleware',# Add this!]Then, add a newDUO_UNIVERSAL_AUTHconfiguration variable:DUO_UNIVERSAL_AUTH={'MAIN':{'DUO_HOST':'<api_hostname>','CLIENT_ID':'<client_id>','CLIENT_SECRET':'<client_secret>','AUTH_BACKENDS':['django.contrib.auth.backends.ModelBackend',],'FAIL_ACTION':'CLOSED'}}Duo API Callback SetupNote:This step allows the application to communicate with Duo. If the view is not registered, the application will raise aNoReverseMatcherror upon starting the Duo authentication flow.To create the callback for the API to communicate with, you must add an entry to yoururlpatternsvariable from within your application'surls.pyfile (with any prepending path you choose):fromdjango.urlsimportpath,includeurlpatterns=[# ...path('duo/',include('duo_universal_auth.urls')),# Add this!]Configuration DocsConfigurations for each Duo application are specified within individual dictionary objects inside a parentDUO_UNIVERSAL_AUTHdictionary each containing the following values:DUO_HOSTRequired: TrueRepresents the API Hostname for your organization's Duo API.'DUO_HOST':'api-XXXXXXX.duosecurity.com'CLIENT_IDRequired: TrueRepresents the Client ID for your application registered from within the Duo Admin Portal.'CLIENT_ID':'DIXXXXXXXXXXXXXXXXXX'CLIENT_SECRETRequired: TrueRepresents the Client Secret for your application registered from within the Duo Admin Portal.'CLIENT_SECRET':'deadbeefdeadbeefdeadbeefdeadbeefdeadbeef'AUTH_BACKENDSRequired: TrueA list of authentication backends that the middleware will work with for the specific application. The Duo authentication middleware will only execute upon a successful authentication result from one of these backends.'AUTH_BACKENDS':['django.contrib.auth.backends.ModelBackend',]FAIL_ACTIONRequired: False (Default:'CLOSED')How the middleware should respond should the Duo authentication server be unavailable (from failing the preliminary health check).'CLOSED': Log out the user and return to the login page, disallowing any authentication while Duo servers are unavailable.'OPEN': Temporarily bypass Duo authentication until the Duo servers become available upon a future authentication attempt.'FAIL_ACTION':'CLOSED'USERNAME_REMAP_FUNCTIONRequired: FalseAn optional one-argument function that takes in the current DjangoHttpRequestobject and returns the current authenticated user's username to send for Duo authentication. If unspecified, the username fromHttpRequest.userwill be used.'USERNAME_REMAP_FUNCTION':lambdar:r.user.username# Mimics default behaviorPost-Authentication RedirectOnce successfully authenticated with Duo, the middleware will automatically redirect the user to the path specified in theDUO_NEXT_URLsession variable, falling back to theLOGIN_REDIRECT_URLsettings variable if it is not present. This value is automatically assigned in the middleware before redirecting to Duo.