Skip to content

Django Auth¤

amqtt.contrib.django provides an optional Django app and broker plugins for authenticating MQTT clients with Django-owned users. This is a way of enabling push notifications to web applications without the overhead of Channels & Daphne since MQTT protocol is supported over websockets. A django web application can send messages to one or more authenticated browser sessions and, when running with asgi, create a task for monitoring client-based published messages and handle accordingly.

If django is not already specified in your project's dependency configurations, install with 'amqtt[django]'

Add the app to INSTALLED_APPS and run migrations:

INSTALLED_APPS = [
    # ...
    "amqtt.contrib.django",
]

python manage.py migrate amqtt_django

Create MQTT tokens with the included model:

from amqtt.contrib.django.models import MqttToken

token, raw_key = MqttToken.issue(user)

Store raw_key securely and send it as the MQTT password. The database stores only a SHA-256 digest of the token.

The included concrete model is built from AbstractMqttToken, which projects can subclass when they need extra fields:

from django.db import models

from amqtt.contrib.django.models import AbstractMqttToken


class ProjectMqttToken(AbstractMqttToken):
    device_name = models.CharField(max_length=128, blank=True)

Use the custom model in your broker plugin config after creating migrations for your Django app.

Configure broker plugins with:

plugins:
  amqtt.contrib.django.plugins.DjangoAuthPlugin:
    token_model: amqtt_django.MqttToken
  amqtt.contrib.django.plugins.UserTopicACLPlugin:

Example Broker Config¤

broker_config = {
    "sys_interval": 0,
    "plugins": {
        "amqtt.contrib.django.plugins.DjangoAuthPlugin": {
            "token_model": "amqtt_django.MqttToken",
            "service_user_id": "service",
            "service_token": "shared-secret",
        },
        "amqtt.contrib.django.plugins.UserTopicACLPlugin": {},
    },
}

Config dataclass ¤

Configuration for Django-backed MQTT authentication.

service_token class-attribute instance-attribute ¤

service_token: str | None = None

Optional MQTT password for the privileged service publisher.

service_user_id class-attribute instance-attribute ¤

service_user_id: str | None = None

Optional MQTT username for a privileged service publisher.

token_model class-attribute instance-attribute ¤

token_model: str = DEFAULT_TOKEN_MODEL

Django model label used for MQTT token lookup.

By default, DjangoAuthPlugin uses amqtt_django.MqttToken. A project can provide its own compatible model in the plugin configuration:

broker_config = {
    "plugins": {
        "amqtt.contrib.django.plugins.DjangoAuthPlugin": {
            "token_model": "myapp.MqttToken",
        },
    },
}

The custom model must provide:

  • get_active_for_key(raw_key: str)
  • user_id
  • DoesNotExist

Subclassing AbstractMqttToken provides this contract automatically, but the plugin does not require inheritance.

Optional service publisher credentials are configured with the plugin's service_user_id and service_token options.

AbstractMqttToken ¤

Bases: Model

Abstract hashed bearer token model for authenticating MQTT clients.

Classes:

  • Meta –

    Django model metadata.

Meta ¤

Django model metadata.

MqttToken ¤

Bases: AbstractMqttToken

Concrete MQTT token model provided by the amqtt Django app.

Classes:

  • Meta –

    Django model metadata.

Meta ¤

Django model metadata.