Quick start

First, you’ll need to install django-latch. If you haven’t already done it, see the installation options.

Obtain Latch credentials

Then, the next steps consist on getting the required parameters to connect to Latch: an application identifier and a secret key. For that, you need to sign up on the Latch Developer Portal or take on their services. Follow the instructions on the My Applications dashboard to create a new application and obtain the credentials.

Configure the required settings

Once you have the Latch application’s credentials, you’ll need to configure your Django project. The modifications on your settings module are:

  1. Add "django_latch" to the INSTALLED_APPS list.

  2. Include the settings LATCH_APP_ID and LATCH_SECRET_KEY.

  3. Add a subclass of LatchModelBackendMixin to the AUTHENTICATION_BACKENDS list.

Apart from these changes on the settings module, you also have to create some templates and set up some URLs.

Latch credentials

In order to connect the Django application to the Latch API, django-latch need the two parameters obtained in the step for creating an application in the Latch site; that is, the application id and its secret key. django-latch get these settings from the settings module from the attributes LATCH_APP_ID and LATCH_SECRET_KEY.

To set these two parameters, I recommend you using environment variables or a remote credential service, like HashiCorp Vault or any other from some cloud provider (no, they didn’t pay me anything).

For example, to set these parameters using environment variables you need first to the session where the application will run

export LATCH_APP_ID = "<your-app-id>"
export LATCH_APP_SECRET = "<you-app-secret>"

$env:LATCH_APP_ID = "<your-app-id>"
$env:LATCH_APP_SECRET = "<you-app-secret>"

or, even better, write those in an .env file, which should have those permissions to be read only by the OS user who will run the web server (or the run_server command, in case of still developing the application):

LATCH_APP_ID=<your-app-id>
LATCH_APP_SECRET=<you-app-secret>

To load those values from the .env file, you also need to install the python-dotenv package:

python -m pip install python-dotenv

py -m pip install python-dotenv

Then, you just need to get those variables from add to your setting module:

# Beginning of the settings.py module
from dotenv import load_dotenv
load_dotenv("<name-of-your-.env-file")
...
LATCH_APP_ID = os.getenv("LATCH_APP_ID")
LATCH_APP_SECRET = os.getenv("LATCH_APP_SECRET")

For more information about security during the development and deployment of a Django application, I recommend reading the security section of the Django documentation You would have committed a war crime if you haven’t already done it. (really, just read it).

Setting up the authentication backend

Now, in order to let Latch block or allow the access to your users, you need to modify your authentication backends.

If you are using the Django’s default authentication process, then you must substitute, or add if it is not specified in your settings module, the ModelBackend for LatchDefaultModelBackend in the AUTHENTICATION_BACKENDS list:

AUTHENTICATION_BACKENDS = ["django_latch.backends.LatchDefaultModelBackend"]

If you have implemented a custom authentication process which uses a different authentication backend, you can also add to it the Latch check by creating an inherited class from the LatchModelBackendMixin and your custom backend:

from django.contrib.auth.backends import BaseBackend

from django_latch.backend.LatchModelBackendMixin

# Your custom backend
class YourCustomAuthBackend(BaseBackend):
    ...

class LatchYourCustomAuthBackend(LatchModelBackendMixin, YourCustomBackend):
    pass

or simply by inheriting directly from LatchModelBackendMixin:

from django.contrib.auth.backends import BaseBackend

from django_latch.backend.LatchModelBackendMixin

# Your custom backend
class LatchYourCustomAuthBackend(LatchModelBackendMixin, BaseBackend):
    ...

Then, it must be added to your settings module:

AUTHENTICATION_BACKENDS = ["path.to.your.backends.LatchYourCustomAuthBackend"]

Important

Using more than one authentication backend

In order to block or allow all the requested attempts from authenticated users, the authentication backend that is subclass of LatchModelBackendMixin must be the first one in the AUTHENTICATION_BACKENDS list.

In case your are using a remote authentication service you will have to implement the Latch access from that remote service.

Check the authentication backends section for a more detailed information about using backends.

Setting up URLs

django-latch includes a Django URLconf that sets up URL patterns for the required views. For example, the URLs can be placed under the prefix /accounts/ by adding the following to your project’s root URLconf:

from django.urls import include, path

urlpatterns = [
    ...
    path("accounts/", include("django_latch.urls")),
    ...
]

Then, authenticated users would be able to pair or unpair their latch by visiting the URLs /accounts/pair-latch/ and /accounts/unpair-latch/.

The following URL names are defined in django_latch.urls:

  • django_latch_pair is the view for pairing the authenticated user’s latch.

  • django_latch_pair_complete is the post-pairing success view.

  • django_latch_unpair is the view for unpairing the authenticated user’s latch.

  • django_latch_unpair_complete is the post-unpairing success view.

Create the required templates

Lastly, you also need to create some templates required by the django-latch views. The required templates are the following:

django_latch/pair_account_form.html

Used to show the pairing form. It has the following context:

form

The pairing form. It asks the user for the Latch token generated on the Latch mobile app.

django_latch/pair_complete.html

Used after successfully paired the authenticated user with the Latch service. It should inform the user that it can now block or allow the access to the Django application by using the Latch mobile app.

django_latch/unpair_account.html

Used to ask the user for confirming that it really wants to unpair its latch. It has the following context:

unpair_error

If the user confirmed the unpairing via HTTP POST but the unpairing operation failed in the Latch service, this variable will be present and will contain a dict with information about the error: a message ('message'), an error code ('code') and extra parameters ('params').

django_latch/unpair_complete.html

Used after successfully unpaired the authenticated user with Latch. It should inform the user that it can no longer block or allow the access to the Django application by using the Latch mobile app.

Finally

The last step would be to run the command in your Django root directory:

python manage.py migrate

py manage.py migrate