search

Stormbase / django-otp-webauthn

Passkey support for Django. Currently in early stages of development and not ready for production use!
BSD 3-Clause "New" or "Revised" License
10 stars 2 forks source link
django django-otp passkeys webauthn webauthn-server

readme

Django OTP WebAuthn

Version License: BSD-3-Clause

All Contributors

This package provides an implementation of WebAuthn Passkeys for Django. It is written as a plugin for the Django OTP framework for multi-factor authentication. Under the hood, this package uses py_webauth to handle all cryptographic operations.

[!IMPORTANT] This package is in development not yet thoroughly tested and documented. The API is subject to change. If you are interested in using this package, please star this repository to show your interest. This will help me prioritize development. If you are interested in contributing, please see the DEVELOPMENT.md file.

Compatibility

Browser compatibility

Passkeys are supported in most modern browsers. Here is a list of browsers that support Passkeys:

For a complete list, see caniuse.com/webauthn.

Features

Quick start guide - how to use Passkeys in your Django project

To quickly start using Passkeys in your Django project, follow these steps:

  1. Install the package from PyPI:

    pip install django-otp-webauthn

  2. Add django_otp_webauthn to your INSTALLED_APPS in your Django settings:

    INSTALLED_APPS = [
   ...
   "django_otp_webauthn",
   ...
]

  3. Add the required URLs to your Django project:

    # urls.py

from django.urls import include, path

urlpatterns = [
   ...
   path("webauthn/", include("django_otp_webauthn.urls", namespace="otp_webauthn")),
   ...
]

  4. Add required settings to your Django settings. This example assumes you want to configure for localhost. You will need to adjust the settings for your production environment.

    # settings.py

# The name of the relying party (RP). This is sometimes shown to the user when they register a Passkey.
OTP_WEBAUTHN_RP_NAME = "My Website Inc."
# This is necessary to bind the Passkey to a specific domain. This should be the domain of your website.
OTP_WEBAUTHN_RP_ID = "your-domain.com"
# This is used to check the origin of the request and is used for security. It is similar to Django's CSRF_TRUSTED_ORIGINS setting.
# The origins must always be a subdomain of the RP ID or the RP ID itself.
OTP_WEBAUTHN_ALLOWED_ORIGINS = ["https://your-domain.com", "https://subdomain.your-domain.com"]

  5. Add django_otp_webauthn.backends.WebAuthnBackend to AUTHENTICATION_BACKENDS in your Django settings. This step is required to make 'passwordless authentication' work.

If you are exclusively using Passkeys as a secondary verification step, you don't have to add this backend.

```python
AUTHENTICATION_BACKENDS = [
    ...
    "django_otp_webauthn.backends.WebAuthnBackend",
    ...
]
```

  1. Add the registration code to your logged-in user template.

    <!-- logged_in_template.html -->
{% load otp_webauthn %}

{% comment %}
This template is displayed when WebAuthn registration is supported.
The template must contain a button with the id `passkey-register-button`. To display status and error messages, include an element with the id `passkey-register-status-message`.
{% endcomment %}
<template id="passkey-registration-available-template">
   <div>
       <button type="button" id="passkey-register-button">Register Passkey</button>
       <div id="passkey-register-status-message"></div>
   </div>
</template>

{% comment %}
This template is displayed when WebAuthn registration is not supported.
{% endcomment %}
<template id="passkey-registration-unavailable-template">
   <p>Sorry, your browser has no Passkey support</p>
</template>

{% comment %}
This placeholder element will be replaced with either the contents of the `passkey-registration-available-template` or the `passkey-registration-unavailable-template` template.
{% endcomment %}
<span id="passkey-registration-placeholder"></span>

{% comment %}
This template tag renders all the necessary <script> tags for the default registration implementation
{% endcomment %}
{% render_otp_webauthn_register_scripts %}

  2. On your login page, include the following to enable passwordless login:

    {% load otp_webauthn %}

<form method="post">
   {# Suppose there is an username field on your page that has CSS selector: input[name="username"] #}
   <label for="id_username">Username</label>
   <input id="id_username" type="text" name="username" autocomplete="username">
   {# Other fields omitted for brevity #}

   {# This placeholder element will be replaced with either the contents of the `passkey-verification-available-template` or the `passkey-verification-unavailable-template` template. #}
   <span id="passkey-verification-placeholder"></span>

   {% comment %}
   This template is displayed when WebAuthn authentication is supported. Typically, you would want to display a button that the user can click to authenticate using a Passkey.
   The template must contain a button with the id `passkey-verification-button`. To display status and error messages, include an element with the id `passkey-verification-status-message`.
   {% endcomment %}
   <template id="passkey-verification-available-template">
       <button type="button" id="passkey-verification-button">Login using a Passkey</button>
       <div id="passkey-verification-status-message"></div>
   </template>

   {% comment %}
   This template is displayed when WebAuthn is not supported.
   {% endcomment %}
   <template id="passkey-verification-unavailable-template">
       <p>Sorry, your browser has no Passkey support</p>
   </template>

   {% comment %}
   This template tag renders all the necessary <script> tags for the default verification implementation

   To make browsers automatically suggest a Passkey when you focus the username
   field, make sure `username_field_selector` is a valid CSS selector.

   The username_field_selector parameter is only required to make 'passwordless authentication' work.
   {% endcomment %}
   {% render_otp_webauthn_auth_scripts username_field_selector="input[name='username']" %}
</form>

  3. Don't forget to run migrations:

    python manage.py migrate

  4. That's it! You should now see a "Register Passkey" button on your logged-in user template. Clicking this button will start the registration process. After registration, you should see a "Login using a Passkey" button on your login page. Clicking this button will prompt you to use your Passkey to authenticate. Or if your browser supports it, you will be prompted to use your Passkey when you focus the username field.

What exactly is a Passkey?

Passkeys are a new way to authenticate on the web. Officially they are called 'WebAuthn credentials', but Passkeys are the more memorable, human-friendly name, that has been chosen to describe them. They allow users of your site to use their phone, laptop, security key, or other compatible device to authenticate without having to remember a password.

Passkeys follow the WebAuthn standard. The standard describes a way to use public-key cryptography to authenticate users.

How Passkeys work (in a nutshell)

Here is an (overly simplified) explanation of how Passkeys work. For a more detailed explanation, try Auth0's interactive WebAuthn demo. It has a very nice explanation of the WebAuthn flow! Or dive into the WebAuthn standard itself.

  1. An already authenticated user registers a Passkey with your site. A public-private key pair is generated on the user's device. The private key is stored securely and the public key is sent to the server and associated with the authenticated user. An additional piece of information is also stored on the server, called the 'credential ID'.
  2. When a user wants to authenticate, the server sends a challenge to the user's device. The user's device signs the challenge with the private key and sends the signature back to the server along with the credential ID.
  3. The server looks up the public key associated with the given credential ID and uses it to check the signature. Was this signature generated by the private key that belongs to the public key we have on file? If yes, the user must be in possession of the private key and is authenticated.

Why use Passkeys?

A note about security

Passkeys are sometimes claimed to be silver bullet for security. While they are more secure than passwords, they are not perfect.

You put trust in the user's device and its manufacturer. Most devices support some form of syncing Passkeys between devices, like through an iCloud or Google account. This means that if someone gains access to the users' iCloud or Google account, they could potentially access their Passkeys. Users that have poorly secured their account and devices are at risk. However, this is not unique to Passkeys. The same risks exists for password managers and other forms of Multi Factor Authentication that support syncing between devices. Passkeys improve over other methods by their resistance to phishing attacks, credential stuffing and their convenience.

It is the author's opinion that the benefits of Passkeys outweigh the risks. This section is here for your own consideration.

Who uses Passkeys?

Plenty of websites already support Passkeys. Here are some well known examples:

It is about time for your website to support Passkeys too!

Further reading

Here are some good resources to learn more about Passkeys:

Development

See DEVELOPMENT.md for information on how to develop and contribute to this project.

License

This project is licensed under the BSD 3-Clause License. See the LICENSE file for details.