Skip to content

Authentication & Authorization via external HTTP server¤

If clients accessing the broker are managed by another application, it can implement API endpoints that respond with information about client authentication and/or topic-level authorization.

  • amqtt.contrib.http.UserAuthHttpPlugin (client authentication)
  • amqtt.contrib.http.TopicAuthHttpPlugin (topic authorization)

Configuration of these plugins is identical (except for the uri name) so that they can be used independently, if desired.

User Auth¤

See the Request and Response Modes section below for details on params_mode and response_mode.

browser-based mqtt over websockets

One of the primary use cases for this plugin is to enable browser-based applications to communicate with mqtt over websockets.

Warning

Care must be taken to make sure the mqtt password is secure (encrypted).

For more implementation information:

recipe for authentication

Provide the client id and username when webpage is initially rendered or passed to the mqtt initialization from stored cookies. If application is secure, the user's password will already be stored as a hashed value and, therefore, cannot be used in this context to authenticate a client. Instead, the application should create its own encrypted key (eg jwt) which the server can then verify when the broker contacts the application.

mqtt in javascript

Example initialization of mqtt in javascript:

import mqtt from 'mqtt';
const url = 'https://path.to.amqtt.broker';
const options = {
  'myclientid',
  connectTimeout: 30000,
  username: 'myclientid',
  password: ''  // encrypted password
};
try {
  const clientMqtt = await mqtt.connect(url, options);

Config dataclass ¤

Bases: HttpConfig

Configuration for the HTTP Auth Plugin.

host instance-attribute ¤
host: str

hostname of the server for the auth & acl check

params_mode class-attribute instance-attribute ¤
params_mode: ParamsMode = JSON

send the request with JSON or FORM data. additional details below

port instance-attribute ¤
port: int

port of the server for the auth & acl check

request_method class-attribute instance-attribute ¤
request_method: RequestMethod = GET

send the request as a GET, POST or PUT

response_mode class-attribute instance-attribute ¤
response_mode: ResponseMode = JSON

expected response from the auth/acl server. STATUS (code), JSON, or TEXT. additional details below

superuser_uri class-attribute instance-attribute ¤
superuser_uri: str | None = None

URI to verify if the user is a superuser (e.g. '/superuser'), None if superuser is not supported

timeout class-attribute instance-attribute ¤
timeout: int = 5

duration, in seconds, to wait for the HTTP server to respond

user_agent class-attribute instance-attribute ¤
user_agent: str = 'amqtt'

the 'User-Agent' header sent along with the request

user_uri class-attribute instance-attribute ¤
user_uri: str = '/user'

URI of the auth check.

with_tls class-attribute instance-attribute ¤
with_tls: bool = False

http or https

Topic ACL¤

See the Request and Response Modes section below for details on params_mode and response_mode.

Config dataclass ¤

Bases: HttpConfig

Configuration for the HTTP Topic Plugin.

host instance-attribute ¤
host: str

hostname of the server for the auth & acl check

params_mode class-attribute instance-attribute ¤
params_mode: ParamsMode = JSON

send the request with JSON or FORM data. additional details below

port instance-attribute ¤
port: int

port of the server for the auth & acl check

request_method class-attribute instance-attribute ¤
request_method: RequestMethod = GET

send the request as a GET, POST or PUT

response_mode class-attribute instance-attribute ¤
response_mode: ResponseMode = JSON

expected response from the auth/acl server. STATUS (code), JSON, or TEXT. additional details below

superuser_uri class-attribute instance-attribute ¤
superuser_uri: str | None = None

URI to verify if the user is a superuser (e.g. '/superuser'), None if superuser is not supported

timeout class-attribute instance-attribute ¤
timeout: int = 5

duration, in seconds, to wait for the HTTP server to respond

topic_uri class-attribute instance-attribute ¤
topic_uri: str = '/acl'

URI of the topic check.

user_agent class-attribute instance-attribute ¤
user_agent: str = 'amqtt'

the 'User-Agent' header sent along with the request

with_tls class-attribute instance-attribute ¤
with_tls: bool = False

http or https

Request and Response Modes

Each URI endpoint will receive different information in order to determine authentication and authorization; format will depend on params_mode configuration attribute (json or form).:

For user authentication, the request will contain:

- username *(str)*
- password *(str)*
- client_id *(str)*

For acl check, the request will contain:

- username *(str)*
- client_id *(str)*
- topic *(str)*
- acc *(int)* : client can receive (1), can publish(2), can receive & publish (3) and can subscribe (4)

All endpoints should respond with the following, dependent on response_mode configuration attribute:

In status mode:

- status code: 2xx (granted) or 4xx(denied) or 5xx (noop)

5xx response

noop (no operation): plugin will not participate in the operation and will defer to another plugin to determine access. if there is no other auth/filtering plugin, access will be denied.

In json mode:

- status code: 2xx
- content-type: application/json
- response: {'ok': True } (granted)
            or {'ok': False, 'error': 'optional error message' } (denied)
            or { 'error': 'optional error message' } (noop)

excluded 'ok' key

noop (no operation): plugin will not participate in the operation and will defer to another plugin to determine access. if there is no other auth/filtering plugin, access will be denied.

In text mode:

- status code: 2xx
- content-type: text/plain
- response: 'ok' or 'error'

noop not supported

in text mode, noop (no operation) is not supported