User email authentication application for Django

pip install django-emailauth==0.1


Django user email authentication

This is a Django application providing all essentials for authenticating users based on email addresses instead of usernames.

This application can operate in a traditional one user - one email mode as well as one user - many emails mode.

This application consists of:

  • UserEmail model
  • Views and forms:
    • Login;
    • Password reset;
    • Account management:
      • User registration and email confirmation;
      • Adding and removing emails to/from existing user accounts;
      • Changing default emails
      • Changing email (for single email mode)
  • Authentication backends:
    • Email backend for authenticating users who has UserEmail object (regular site users);
    • Fallback backend for users without such objects (most likely that will be site administration)

Motivation for this application

For some reason I was lucky to work on projects which required email-based authentication, and one of these projects could benefit if users could have several emails.

To solve basic authentication problem I quickly came up with this:

That trick works but it has several drawbacks:

  • It breaks standard Django tests, so when you run python test on your project you'll have to filter out error messages from broken Django tests. Not good.
  • Standard Django login view can't handle long (longer than 30 characters) email addresses.
  • If you put email verification status and all such into UserProfile class you tie code working with emails to your project impairing code reuse.

To solve above problems I decided to create this application. It stores all email-specific data into UserEmail model (verification code, code creation date, verification status etc.) So this application manages all email-related data, not messing with UserProfile and saves application user from reinventing the wheel.

Example project

To see this application in action:

cd emailauth/example
python syncdb
python runserver

Please bear in mind that all emails sent by example project are not actually sent but printed to stdout instead.

To see how traditional one user - one email mode works:

cd emailauth/example
python syncdb
python runserver --settings=settings_singleemail

Installation and configuration


First you need to somehow obtain 'emailauth' package.

Place 'emailauth' directory somewhere on your PYHTONPATH, for example in your project directory, next to your -- that's the same place where python startapp creates applications.

If you are using some kind of isolated environment, like virtualenv, you can just perform a regular installation:

python install


pip install django-emailauth


easy_install django-emailauth


Now you need to make several changes to your

  • Add 'emailauth' to your INSTALLED_APPS

  • Plug emailauth's authentication backends:

  • Configure LOGIN_REDIRECT_URL and LOGIN_URL. Emailauth's default expects them to be like this:

    LOGIN_REDIRECT_URL = '/account/'
    LOGIN_URL = '/login/'
  • Optionally change a life time of email verification codes by changing EMAILAUTH_VERIFICATION_DAYS (default value is 3).

  • Optionally set EMAILAUTH_USE_SINGLE_EMAIL = False if you want to use emailauth in "multiple-emails mode".

Now include emailauth's from your site's Of course you may opt for not including whole emailauth.urls, and write your own configuration, but if you decide to use the provided, it will look like this:

urlpatterns = patterns('',
    (r'', include('emailauth.urls')),


By default emailauth uses automatic maintenance - it deletes expired UserEmail objects when a new unverified email is created.

If you for some reason want to deactivate it and perform such maintenance manually you can do it:


  • Run cleanupemailauth management command when you want to perform the cleanup:

    python clenupemailauth

Template customization

Emailauth comes with a set of templates that should get you started, however they won't be integrated with your site's templates - they don't extend the right template and use wrong block for main content.

Don't worry, it's very easy to fix. All emailauth's templates extend emailauth/base.html and use emailauth_content block for content, so all you need, is to modify emailauth/base.html and make it extend right template and place emailauth_content block into right block specifc to your site.

For example if your site's main template is mybase.html and you place all content into mycontent block, you need to make following emailauth/base.html:

{% extends "mybase.html" %}

{% block mycontent %}
    {% block emailauth_content %}
    {% endblock %}
{% endblock %}

That's all

By this point, if you started a new project and followed all the above instructions above you should have a working instance of emailauth application.

To test it, start a server:

python runserver

And open a registration page in your browser: - it should display a registration page.