betagouv / django-magicauth

Password-less authentication for Django. An email with a magic link allows a secure login

Django Magicauth

Django Magicauth brings password-less authentication to your project.

How it works

• The user inputs their email address (and optionnally an OTP).
• An email is sent to the user with a link that contains a one-time token.
• Once they click on this link, they are logged in to the service.

For a detailed step-by-step with screenshots of the default templates, see Step-by-step in pictures.

Fonctionnement (FR)

Authentifiez vos utilisateurs sans mot de passe avec Django Magicauth.

Comment ça marche

• Les utilisateurs renseignent leur adresse email (et en option un OTP).
• Ils reçoivent alors un email avec un lien de connexion.
• Lorsqu'ils cliquent sur le lien, ils sont authentifiés et redirigés sur le service.

Pour un détail du fonctionnement en image, voir le déroulé en images.

Installations and testing instructions

Quick start

1. Install Magicauth

pip install git+https://github.com/betagouv/django-magicauth.git

2. Add "magicauth" to your INSTALLED_APPS in settings.py

INSTALLED_APPS = [
    # all your apps
    "magicauth",
]

2. Include the magicauth URLconf in your app's url.py

# After your previous imports
from magicauth import views as magicauth_views
from magicauth.urls import urlpatterns as magicauth_urls

urlpatterns = [
    # here are your URL patterns
]

urlpatterns.extend(magicauth_urls)

3. Add the following items in your project's settings.py`

MAGICAUTH_FROM_EMAIL = '[email protected]'
MAGICAUTH_LOGGED_IN_REDIRECT_URL_NAME = 'home'

4. Run python manage.py migrate to create the polls models.

5. Setup your mailer in settings.py In dev mode, you can use a console mailer

6. Make sure you have the following middlewares

MIDDLEWARE = [
    # [...] other middleware you may have
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django.contrib.sites.middleware.CurrentSiteMiddleware",
]

Two-Factor Authentication (2FA) using One Time Passwords (OTP)

Two-Factor Authentication means you ask for two different passwords from your user : their normal password and an OTP. (See https://en.wikipedia.org/wiki/Multi-factor_authentication) They will get the magic link only if the two are valid, else they get an error and the link is not sent.

What is a OTP ? It is a short code (6 to 8 digits), usually generated by a dedicated app on a user's device (smartphone, hardware). See https://en.wikipedia.org/wiki/Time-based_One-time_Password_algorithm

How to enable OTPs

We use the django-otp package. You must have it installed and configured in your project.

1. install django_otp : pip install django_otp (or whatever package manager you use)
2. add the required apps in INSTALLED_APPS : 'django_otp', 'django_otp.plugins.otp_totp'
3. run the migrations in your project : python manage.py migrate
4. Set MAGICAUTH_ENABLE_2FA = True in your settings.py

If you use the default login template, an OTP input will show up in the login page, below the Email. (To check your install has worked, you can revert to the default template and see if the field appears : remove your MAGICAUTH_LOGIN_VIEW_TEMPLATE var.)

If you have a custom login template, you will have to add the field for entering OTPs, in an OTP_form. See the default login template for an example : templates/magicauth/login.html`

For testing purposes, you can generate OTPs for a given user from the command line :

• Add 'django_otp.plugins.otp_static' to INSTALLED_APPS.
• Then you can use addstatictoken from command line. E.g : python manage.py addstatictoken -t 123456 "[email protected]"

Contribute to Magicauth

To contribute to Magicauth, you can install the package in the "editable" mode

pip uninstall django-magicauth  # just in case...
pip install -e git+https://github.com/betagouv/django-magicauth.git#egg=django-magicauth

You can also install a specific branch, for instance for testing a PR. To install branch my-branch:

pip install -e git+https://github.com/betagouv/django-magicauth.git@my-branch#egg=django-magicauth

Django-magicauth is now a dependency of your project, and you can edit the code located here:

cd src/django-magicauth

run tests

Create a virtual env for the project or reuse one and source it.

Install dependencies and run tox

cd src/django-magicauth
pip install -r -U dev-requirements.txt
tox

We use pre-commit to ensure code correctness. You should install it:

pre-commit install

Release process

The follwing dependencies need to be installed: pip setuptools wheel twine:

python -m pip install --upgrade pip setuptools wheel twine

First, ensure code is clean:

pip install -U pre-commit
pre-commit install
pre-commit autoupdate
pre-commit

1. Create a new MD file under docs/releases named after the new version and fill the file with the changes
2. Change the version in pyproject.toml
3. Create a commit named Release version
4. Open and merge the PR for that release
5. Create a new release at https://github.com/betagouv/django-magicauth/releases/new
6. Publish the new version on PyPI:

    python setup.py sdist bdist_wheel
    twine upload dist/*

Projects using Magicauth

https://github.com/betagouv/e-controle/ https://github.com/betagouv/Aidants_Connect https://github.com/betagouv/peps https://github.com/betagouv/urbanvitaliz-django

Join us !

Step-by-step in pictures

Note : the screenshots below use the default templates, which don't look very nice. It is expected that you replace them with your own better-looking ones.

Step 1 : the user goes to the login page. (see LoginView in magicauth/views.py)

Step 2 : The user inputs their email address in the login page.

Step 3 : The user sees a confirmation page (EmailSentView), explaining that an email has been sent.

An email is sent to the user with a link that contains a one-time token.

The link looks something like this :

Step 4 : once they click on the button and follow the link, the user is directed to a wait page (this is optional) (WaitView)

Step 5 : the user is logged in to the service (ValidateTokenView) and redirected to the landing page.

django-magicauth's Issues

Refactor the way email are sent

Details in here: #16 (comment)

Make the token not found warning configurable

Currently the message text is hard-coded which is a problem if someone wants to change the language. It would be better if the text was a variable in settings.py.

django-magicauth/magicauth/views.py

Lines 148 to 153 in 5baa9ce

	messages.warning(
	self.request,
	"Ce lien de connexion ne fonctionne plus. "
	"Pour en recevoir un nouveau, nous vous invitons à renseigner "
	"votre email ci-dessous puis à cliquer sur valider.",
	)

MAGICAUTH_EMAIL_FIELD needs to be set

Hi,

Thanks for this nice building block!
Just a quick note: if you don't set the MAGICAUTH_EMAIL_FIELD settings, you won't get any lookup working.
Maybe it would be nice to add a default value or explicitly add that to the docs?

Cheers,

Guillaume

"e-contrôle notification" as title in the html email template

The default template for the html-version of the email (found here) has e-contrôle notification as the title.

<title>e-contrôle notification</title>

Note that this is a minor issue since the title is rarely seen in emails (except for when the users click on "view online" or in certain versions of Android).

An alternative would be to have a generic title, maybe something like Accéder à {{ site.domain }} or use the email subject as the html title.

Another option (perhaps overkill), would be to incorporate a setting to specify it.

Which option would you prefer? I could try to prepare a PR if needed.

Contact Info

Hi there,

Hope you're having a wonderful day. Might I suggest adding a security policy, including a contact for people wanting to submit a security issue? After all, this is an authentication related package. It would be a shame if someone couldn't properly disclose an issue.

Best
Joe

Ajout Licence

Je recommande une MIT qui permet une large réutilisation du code.

Support Django 4

All is in the title. For now, I'm not really sure django-magicauth supports Django 4. That need investigation. Here is the liste of the removed features. the most notable is the disappearance of django.utils.translation.ugettext*().

LOGGED_IN_REDIRECT_URL_NAME is sometimes a url, sometimes a url name

When we create the email link, we fill in the "next" value here :
https://github.com/betagouv/django-magicauth/blob/master/magicauth/views.py#L41-L44

By default, the "next" query_param will be "/" + LOGGED_IN_REDIRECT_URL_NAME + "/". If you are actually using a url name, not a url, then that breaks the redirect.

Example using the default config :
LOGGED_IN_REDIRECT_URL_NAME = 'control-detail' (with associated url "/accueil")
The emailed link is :
https://<server>/code/<token key>/?next=/control-detail/
So that the login process ends up redirecting on
https://<server>/control-detail, which doesn't exist (the associated url which exists is /accueil)

Expected final redirect :https://<server>/accueil
(the email link itself could be https://<server>/code/<token key>/?next=control-detail or https://<server>/code/<token key>/?next=/accueil, whatever works)

Edit : second problem (I think it's separate but I could be wrong) : email.txt contains a different link from email.html.
https://github.com/betagouv/django-magicauth/blob/master/magicauth/templates/magicauth/email.html#L312 : no next_view
https://github.com/betagouv/django-magicauth/blob/master/magicauth/templates/magicauth/email.txt#L3 : has next_view