Authentication Engines

This page documents the inner API of the AuthEngine[T] interface, and its default implementations. It contains the following modules

  1. .engine.abstract - Module responsible for the abstract authentication engine interface

  2. .engine.acquire - Module responsible for the classical authentication engine with an acquire view

  3. .engine.refresh - Module responsible for refreshable authentication engine with an acquire and a refresh view

Module .engine.abstract

This module contains a single class, the abstract authentication engine. The purpose of an authentication engine is to define properly how to encode the different tokens.

class AuthEngine[T]

This class implements the default functions an authentication engine should provide, as well as different tools to generate the tokens properly.

constructor __init__(self, keyname, scheme, algorithms)

This constructor defines an authentication engine by providing the key name, linking it through the configuration. One also needs to provide the algorithms used to encode and decode the tokens, the first element of this list being how it is encoded. All of them are used to decode the tokens. By default it is [ 'RS256' ]. Finally, one needs to provide the scheme used to transform the data into json, it needs to be an AuthWire[T]

property key

Returns the key used for encrypting / decrypting the tokens. By default, goes through the configuration to retrieve the key from its name, and if it has been set, the key will be the one provided to bypass configuration.

property urlpatterns

Defines a set of urls used for authentication. For example, it can be used to acquire a token or to refresh it.

method headers(self, data)

Defines a way for sub classes to define the JWS headers. By default, return {}.

method payload_from_wired(self, wired)

Defines how to go from the encoded value (wired) to the payload, allows the sub class to add custom properties to the payload. By default, returns wired.

method wired_from_payload(self, payload)

Defines how to go from the payload to the encoded value (wired), allows the sub class to remove the custom properties it has added. By default, returns payload.

method validate_payload (self, payload)

This method is to validate the payload, for example if it had a timeout, it returns whether the deadline isn’t yet over. By default, returns True.

method encode(self, data)

Encodes the data of type T into a signed json web token by first transforming it into its wired form and then its payload form.

method decode(self, token, verify, return_payload)

Decodes the data by first verifying its signature and that the payload is valid.

  1. By default verify is True, and any error raise JWSError, otherwise in case of an error it returns None.

  2. By default return_payload is False, and it only checks the signature and returns the payload if it is True.

Module .engine.acquire

This module defines the class AcquireEngine[T]. It takes in its constructor the same data as the abstract authentication engine and a function that takes the same arguments as a django view but should return either None or an object of type T. This view represents how a user acquires an authentication token with type T. It then implements the true django view acquire_view that wraps your view, and define a urlpattern at acquire/ that you can find in the urlpatterns method.

Module .engine.refresh

This module defines the class RefreshEngine[T], which is equivalent in behaviour as AcquireEngine[T], except that every token has a short time expiration date, and a long time expiration date, that you can configure with the two parameters at the end of the constructor in this order.

The payload is considered valid if the short expiration date hasn’t yet expired. It defines a new view refresh_view allowing you to refresh the short time and long time expiration dates if the long one hasn’t expired. This view is exposed at the url refresh/ in urlpatterns. The class also overrides the wired_from_payload and payload_from_wired methods.