dj-authentication 0.2.0

Nice HTTP authentication support for Django

Nice authentication support for Django

This is a simple, ready-to-use module for handling any standard kind of authentication in Django apps, without writing any code. However - if you have greater needs - this is also a uniform, configurable and extensible framework you can use to do whatever you need.

Features

• Per-request authentication: common base for supporting any number of standard HTTP auth methods, and HTTP Basic and OAuth Bearer Token auth methods included
• OpenID Connect module: support for OpenID Connect token verification and issuance.
• Modular, uniform architecture: you can mix and match different auth mechanisms, and everything will just work!

We are only getting started. More generic auth mechanisms are going to be added in the future (see Planned features).

Requirements

• Django 2.0+

Installation

pip install dj-authentication

settings.py

• Add 'dj_authentication' to the list of INSTALLED_APPS.
• Remove 'django.contrib.auth.middleware.AuthenticationMiddleware' from the list of MIDDLEWAREs.
• Add dj_authentication.request_http_auth.HTTPAuthMiddleware to the list of MIDDLEWAREs.
• Choose backends used for determining request.user, for example:

REQUEST_USER_BACKENDS = [
    'dj_authentication.methods.basic', # HTTP Basic Auth
    'dj_authentication.methods.bearer', # OAuth Bearer Token Auth
    'django.contrib.auth',
]

Per-request auth methods

Basic auth

This method checks the provided username and password against configured Django authentication backends.

Tips

To trigger an authentication dialog in a browser, if the user is not authenticated:

if not request.user.is_authenticated:
    return HttpResponse(status=401)

Bearer auth

This method checks the provided bearer token against the OpenID Connect module, described below.

openid module - OpenID Connect / OAuth support

dj_authentication includes an implementation of OpenID Connect / OAuth token verification and issuance.

You can configure the list of trusted OpenID Providers by providing their URLs thru (*_)AUTH_URL environment variables, like:

• GOOGLE_AUTH_URL=https://[e-mail]
• FACEBOOK_AUTH_URL=facebook+https://[e-mail]

All conforming OpenID Providers are supported; some other services too - see the list at python-openid-connect. However, only conforming OpenID Providers that issue id_tokens are supported automatically in the Bearer auth.

Token verification

You can verify tokens using:

• dj_authentication.openid.verify() function - on the OAuth callback URL, you should pass all the GET parameters you've received to this function. Some of the understood parameters are id_token, iss (for non-OpenID OAuth servers, for example https://facebook.com), token_type, access_token. Note that providing the iss parameter is required for legacy OAuth servers.
• dj_authentication.methods.bearer request.user backend - you can pass id_tokens returned by the OpenID Providers in the Authorization: Bearer header, and this backend will automatically verify them to provide request.user.

How it works?

• For OpenID Providers, id_tokens are verified against the jwks_uri.
• For supported legacy OAuth servers, access_tokens are used to access userinfo endpoints and obtain user information.

User mapping

By default, dj_authentication.methods.bearer sets the request.user to a dict with the data decoded from the id_token, with is_authenticated = True property added.

To have it automatically map the ID data to a true user object, set the MAP_ID_TO_USER_FUNC variable. dj_authentication provides two ready-to-use functions:

• 'dj_authentication.user_mappings:map_email' - it looks up the users by the email address
• 'dj_authentication.user_mappings:map_sub_to_username' - it looks up the users using OpenID token subject as the username

Issuing your own tokens

You can also issue and verify your own JWT id_tokens - just set OPENID_PROVIDER = 'dj_authentication.openid:SimpleDjangoProvider' in the settings.py file and use the dj_authentication.openid.issue() function. They will be signed with the Django SECRET_KEY.

Example configurations

App that supports session-less HTTP Basic auth in addition to standard Django sessions

REQUEST_USER_BACKENDS = [
    'dj_authentication.methods.basic',
    'django.contrib.auth',
]

Session-less app that supports only Google id_tokens passed as Bearer tokens

AUTHENTICATION_BACKENDS = [] # Fully disable session-based auth; you may choose to delete django.contrib.auth from INSTALLED_APPS too.

REQUEST_USER_BACKENDS = [
    'dj_authentication.methods.bearer',
]

os.environ['GOOGLE_AUTH_URL'] = 'https://[e-mail]'

App that supports both email-based, Google and Facebook login

REQUEST_USER_BACKENDS = [
    'django.contrib.auth',
]

OPENID_PROVIDER = 'dj_authentication.openid:SimpleDjangoProvider' # for tokens sent in email verification messages

os.environ['GOOGLE_AUTH_URL'] = 'https://[e-mail]'
os.environ['FACEBOOK_AUTH_URL'] = 'facebook+https://[e-mail]'

App that supports both email-based, Google and Facebook login; and session-less Google id_tokens passed as Bearer tokens

REQUEST_USER_BACKENDS = [
    'dj_authentication.methods.bearer',
    'django.contrib.auth',
]

OPENID_PROVIDER = 'dj_authentication.openid:SimpleDjangoProvider' # for tokens sent in email verification messages

MAP_ID_TO_USER_FUNC = 'dj_authentication.user_mappings:map_email'

os.environ['GOOGLE_AUTH_URL'] = 'https://[e-mail]'
os.environ['FACEBOOK_AUTH_URL'] = 'facebook+https://[e-mail]'

Planned features

• Verification of access_token and code against at_hash and c_hash - to return them from verify()
• Support for opaque id_tokens verified against a single configured OAuth/OIDC auth server thru Introspection Endpoint
• Support for opaque id_tokens verified against the Django session system (aka sending the session key as the Bearer token)
• Support for client certificates (see also OAuth 2.0 Mutual TLS)
• Support for OIDC private_key_jwt scheme
• Support for asymmetric signing methods for the issued tokens