amqtt/docs/contrib_plugins.md

Contributed Plugins

Plugins that are not part of the core functionality of the aMQTT broker or client, often requiring additional dependencies.

Authentication & Topic Access via external HTTP server

amqtt.contrib.http.HttpAuthACLPlugin

If clients accessing the broker are managed by another application, implement API endpoints that allows the broker to check if a client is authenticated and what topics that client is authorized to access.

Configuration

• host *(str) hostname of the server for the auth & acl check
• port *(int) port of the server for the auth & acl check
• user_uri *(str) uri of the topic check (e.g. '/user')
• acl_uri *(str) uri of the topic check (e.g. '/acl')
• request_method *(RequestMethod) send the request as a GET, POST or PUT
• params_mode *(ParamsMode) send the request with json or form data
• response_mode *(ResponseMode) expected response from the auth/acl server. STATUS (code), JSON, or TEXT.
• user_agent *(str) the 'User-Agent' header sent along with the request

Each endpoint (uri) will receive the information needed to determine authentication and authorization (in either json or form data format, based on the params_mode)

For user authentication (user_uri), the http server will receive in json or form format the following: - username (str) - password (str) - client_id (str)

For superuser validation (superuser_uri), the http server will receive in json or form format the following: - username (str)

For acl check (acl_uri), the http server will receive in json or form format the following: - username (str) - client_id (str) - topic (str) - acc (int) client can receive (1), can publish(2), can receive & publish (3) and can subscribe (4)

The HTTP endpoints can respond in three different ways, depending on response_mode:

1. STATUS - allowing access should respond with a 2xx status code. rejection is 4xx. if a 5xx is received, the plugin will not participate in the filtering operation and will defer to another topic filtering plugin to determine access
2. JSON - response should be {'ok':true|false|null, 'error':'optional reason for false or null response'}. true allows access, false denies access and null the plugin will not participate in the filtering operation
3. TEXT - ok allows access, any other message denies access. non-participation not supported with this mode.