django-sqrl-2/README.md

172 lines
4.3 KiB
Markdown

# SQRL for Django
This package allows for developers to easily create SQRL-aware websites with a
few simple steps.
**(This document was written for the future. Things that are not yet implemented
will be ~~struck out~~. Non-functional code snippets will be `#commented out`)**
This is a reboot of [Miki725's django-sqrl](https://github.com/miki725/django-sqrl),
updated for Python 3.7 and Django 2.2. The vast majority of the code is unchanged,
so all credit for this working belongs with them.
* Free software: MIT license
* GitHub: https://gitlab.com/WolfgangAxel/django-sqrl-2
* ~~Documentation: https://django-sqrl-2.readthedocs.org~~
* What is SQRL?: https://sqrl.grc.com/pages/what_is_sqrl/
* SQRL documentation: https://www.grc.com/sqrl/sqrl.htm
## Installing
### SQRL Package
First step is to install `django-sqrl-2` which is easies to do using pip:
```
$ #python3 -m pip install django-sqrl-2
```
### Django settings
Once installed there are a few required changes in Django settings:
* Make sure that some required Django apps are used:
```
INSTALLED_APPS = [
...,
'sqrl',
'django.contrib.auth',
'django.contrib.sessions',
'django.contrib.staticfiles',
]
```
* Make sure that some required Django middleware are used:
```
MIDDLEWARE_CLASSES = [
...
'django.contrib.sessions.middleware.SessionMiddleware',
'django.contrib.auth.middleware.AuthenticationMiddleware',
]
```
* Change `AUTHENTICATION_BACKENDS` to use SQRL backend vs Django's
`ModelBackend` (default):
```
AUTHENTICATION_BACKENDS = [
'sqrl.backends.SQRLModelBackend',
]
```
* If you are using Django admin, following are required:
* Make sure that `sqrl` is listed before `admin` in the `INSTALLED_APPS`.
This allows Django to prioritize `sqrl` templates since `django-sqrl`
overwrites some of them.
```
INSTALLED_APPS = [
...,
'sqrl',
'django.contrib.admin',
...
]
```
* Make sure to add a custom template directory in settings. `django-sqrl`
extends Django admin's `base.html` which by default causes infinite recursion.
To solve that, simply add a custom template directory which allows `django-sqrl`
to explicitly extend from `django.contrib.admin` `base.html` template:
```
import os
import django
TEMPLATE_DIRS = [
os.path.dirname(django.__file__),
]
```
## URLs
All of SQRL functionality is enabled by adding its URLs to the root URL config:
```
from django.urls import path, include
urlpatterns = [
...
path('sqrl/', include('sqrl.urls', namespace="sqrl")),
...
]
```
If you use Django admin, the `/admin/sqrl_manage` endpoint will be available to manage
your site's SQRL identities.
## Templates
Now that SQRL is installed in your Django project, you can use it on any login
page with three simple template tags:
```
{% load sqrl %}
{% sqrl as sqrl_session %}
{% sqrl_login_dropin sqrl_session [[a named redirect]] %}
```
The [[named redirect]] is the page that should be redirected to after logging
in. Any name that can be resolved by django's `reverse` function will work (i.e.
`path("scheme/", view, name="example")` in the app `app` with namespace "app"
could be selected as `app:example`).
These three tags will add a simple element to your login page:
![A very basic SQRL QR code](docs/example_dropin.png "example dropin")
If that doesn't suit your fancy, you may build your own template from the
following essential tags:
```
{% load sqrl %}
{% sqrl as sqrl_session %}
<a href="{{ sqrl_session.sqrl_url }}">
<div id="sqrl-qr" data-sqrl="{{ sqrl_session.sqrl_url }}"></div>
</a>
<script>SQRL_NEXT="{{ your desired redirect }}"; SQRL_CHECK_URL="{% sqrl_status_url_script_tag sqrl_session %}"</script>
<script type="application/javascript" src="{% static 'sqrl/sqrl.js' %}"></script>
```
## Management Command
SQRL uses server state to keep track of open SQRL transactions in order to
mitigate replay attacks. Since this state will constantly grow if not cleared,
`django-sqrl` provides a helper management command to clear expired states:
```
$ python3 manage.py clearsqrlnuts
```
It is recommended to run this command as repeating task. Here is an example
configuration for `cron`:
```
*/5 * * * * python manage.py clearsqrlnuts >/dev/null 2>&1
```
## ~~Testing~~
~~To run the tests, you need to install the testing requirements first:~~
```
$ #make install
```
~~Then to run the tests, you can use use the Makefile command:~~
```
$ #make test
```