Migrate Django users to Auth0

• Free software: ISC license

This is alpha quality software. It was written to migrate some users from a Django 1.4 project onto Auth0 but it is unlikely to get much love beyond this singular task; nonetheless others may find it useful.

Auth0 is a login as a service provider which at it's simplest will offload the login process from your django based website and provide additional protections and external database backed authentication for your django project.

The primary goals of this project are:

• provide a simple user friendly method for migrating existing django users to Auth0 database authentication for legacy and recent django projects (I am working with Django 1.4)
• handle username or email as username django user models
• migrate a django username login to an email backed Auth0 login

A non-goal is to handle existing or proposed social authentication in User migration or to provide signup workflows. It you are not migrating users then the backend in this project defeats the benefits of Auth0's ratelimiting and DDOS mitigation.

Auth0 already provides a progressive migration path from your existing project as long as your django passwords are upgraded to bcrypt. If you want to go that route Auth0 document that method, but that route might require subscription to a premium plan and will still require progressive upgrading of all local passwords to use bcrypt first which defeats the potential benefits of this approach.

The path this project takes will be to retain your existing login method, views and templates but with the additional auth0db MigrateToAuth0Backend backend inserted ahead of your current backend which will allow you to use their free or other plans as appropriate.

The migration process is as follows:

• User authenticates against the MigrateToAuth0Backend backend. If that fails the user is authenticated against your existing backend and a new Auth0 user created if they are authenticated on your current backend.
• If the user authenticates against Auth0 they will be created in django if they don't exist locally.
• A local Auth0User model holds the Auth0 user_id and has a one to one relationship with the new or existing User to allow tracking of migration.
• If a current django user needs to reset their password (usually via email) then a replacement SetPassword form can be passed into the standard django auth password_reset_confirm view that simply sets a new password on the Auth0 user if they exist and the local User.
• An auth0_migrated management command will show what percentage have been migrated

The end game in your migration will be switching over to your own new templates which use the Auth0 lock login widgets and sending password reset emails to any remaining active but in-frequent django based users you might have that don't have a corresponding Auth0User record.

To avoid any potential disruption for your users any methods that create or update a password on Auth0 should also update the local user model until the switchover is complete at which point you can safely remove the MigrateToAuth0Backend.

The other caveat is that in the event that multiple django usernames share a single email address, the first successful authenticated username will be migrated but the following ones never will, so you will need a plan to deal with these.

To get started you will need your Auth0 domain, client id, and connection to the database that will hold your users. You will also need a JSON web token (jwt):

• Login to auth0.com
• Go to their management api documentation (https://auth0.com/docs/api/v2)
• Add scopes for the actions and entities you wish to access via api (eg create, read, update, and delete actions for the users entity)
• Copy the generated jwt.
• Go to the dashboard and get (or setup) your client id, domain, db connection for your test app.

Install auth0db. :

$ pip install auth0db 

Add auth0db to your INSTALLED_APPS django setting, and auth0db.backends.MigrateToAuth0Backend as your first authentication backend. :

AUTHENTICATION_BACKENDS = [
'auth0db.backends.MigrateToAuth0Backend',
'django.contrib.auth.backends.ModelBackend'
] 

You can use alternative backends to the ModelBackend as the backend you are migrating from so long as they support either email or username as their username, return a user instance with an email and take a password as an argument.

In your django settings file you'll also need the following settings:

# Mandatory settings
AUTH0_DOMAIN = "YOURAPP.XX.auth0.com"  #
AUTH0_CLIENT_ID = "Your_Auth0_Client_ID"
AUTH0_USER_JWT = 'jwt with CRU permissions on Users'
AUTH0_CONNECTION = "Username-Password-Authentication"  # or whatever yours is called

# Optional
AUTH_USER_MODEL = "auth.User"  # default 
AUTH0_REQUIRE_USERNAME = False  # default - to match the CONNECTION setting

# Not required for Django >= 1.5, optional for Django pre 1.5
# If your legacy User model has a different username field...   
USERNAME_FIELD = "username"  # default

Since we need to dynamically set a foreign key to the User model you'll need to create a package folder in your project and use the appropriate migration setting to point to it for the database migration. I suggest putting it with your other local apps and giving it a name that can't clash when South/Django is locating all the migration folders. In this case our project folder is djangoproject so we'll create 'djangoproject.auth0db_migrations' with __init__.py in it. :

# Django pre 1.7 with South installed
SOUTH_MIGRATION_MODULES = {
    'auth0db': 'djangoproject.auth0db_migrations',
}

# Django >= 1.7
MIGRATION_MODULES = {
    'auth0db': 'djangoproject.auth0db_migrations',
}

Now create initial migration of the auth0db and migrate it. :

# Django pre 1.7 with South installed
./manage.py schemamigration --initial auth0db

# Django >= 1.7
./manage.py makemigration auth0db

Your migrations folder should now have the initial migration in it. :: # Migrate the app! ./manage.py migrate auth0db

Once migrated, the Auth0User model holds the user id and their corresponding auth0_id that can be used to track the migration.

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.