172 lines
4.3 KiB
Markdown
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:
|
|
|
|
|
|
|
|
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
|
|
```
|