Django

masks.django adds masks to a Django app. Python apps explains the settings, the handshake, sessions, and privileges that every framework shares.

Setting up

Install the package with the django extra:
Terminal window
```
pip install "masks-client[django]"
```
Set MASKS in your settings to a dict of Config settings, or to a Config. A dict leaves out secret to use SECRET_KEY. A Config needs its own secret.
```
MASKS = {
    "issuer": os.environ["MASKS_ISSUER"],
    "resource": "https://app.example.com",
    "name": "Catalog",
}
```

Add the middleware after Django’s own:

MIDDLEWARE = [
    ...,
    "django.middleware.csrf.CsrfViewMiddleware",
    "masks.django.middleware.MasksMiddleware",
]

Include the routes at the root of your URLs. Their paths already start with /auth.

from django.urls import include, path

urlpatterns = [
    path("", include("masks.django.urls")),
    ...
]

Guard a view with a decorator:

from masks.django import login_required

@login_required()
def settings(request):
    return render(request, "settings.html", {"actor": request.masked})

request.masked is the actor on every request. The decorators take privileges.

masks’ own routes check that a form came from this site, so Django’s CSRF check is off for them, and a sign-out form needs no {% csrf_token %}.

An async session store or store raises ImproperlyConfigured. Use a synchronous one.

Reference

masks.django exports these:


`request.masked`	The actor on every request.
`@login_required(*privileges, tokens=False)`	Needs a sign-in holding each privilege. With `tokens=True`, it checks a token when the request has an `Authorization` header or no session.
`@token_required(*privileges)`	Needs an access token holding each privilege.
`client(request)`	A `masks.Client` with the app’s credentials.
`start_delegation(request, provider, prompt=None, max_age=None)`	Starts a delegation. Returns the redirect.
`finish_delegation(request)`	Finishes it. Returns a `masks.HeldConnection`.
`login_url(return_to="", organization="", privilege=())`	A link that starts a sign-in.
`registered(request)`	Whether masks still knows the app.
`connected(request)`	Whether the app holds credentials.
`actor(request)`	The actor, the same as `request.masked`.
`engine()`	The shared engine built from `MASKS`.