日本語

How to use an MQTT broker with authorization

Overview

This page describes how to connect from SINETStream to an MQTT broker that requires authorization.

Note: An MQTT broker does not return authorization errors to clients. Therefore, SINETStream cannot detect authorization errors.

The description will be made in the following order.

1. Prerequisites
2. Configurations on the MQTT broker (server side)
3. Configurations on SINETStream (client side)
4. Behavior on authorization errors

Prerequisites

Though the configuration and setting of an MQTT broker may vary, the following conditions are assumed for simplicity in this document.

• Mosquitto is used as the MQTT broker
• The MQTT broker has been configured to use password authentication (*1)
• The MQTT broker has been configured to use SSL/TLS connection (*1)
• The target user of an access control list (ACL) has been registered (*1)

(*1) Refer to How to use an MQTT broker with password authentication for configuring authentication.

The following values are used in the examples.

In practice, use appropriate values for your environment.

• MQTT broker
  • Hostname
    • broker.example.org
  • Port
    • 8884
  • Installed directory
    • /srv/mqtt
  • Username/password
    • user01/user01-pass
      • Permission: write
    • user02/user02-pass
      • Permission: read
    • user03/user03-pass
      • Permission: read, write
  • Configuration file path
    • /etc/mosquitto/mosquitto.conf
  • ACL file path
    • /etc/mosquitto/aclfile
• Certificate (client side)
  • CA certificate
    • /opt/certs/cacert.pem

Configurations on the MQTT broker (server side)

The following procedure is needed for the MQTT broker to perform authorization.

1. Edit the MQTT broker’s configuration file
2. Add settings in the ACL file
3. Reload the configuration file

Edit the MQTT broker’s configuration file

Add the following lines to the MQTT broker’s configuration file /etc/mosquitto/mosquitto.conf.

acl_file /etc/mosquitto/aclfile
allow_anonymous false

The meanings of the above settings are:

• acl_file
  • Specify the ACL file path.
• allow_anonymous
  • Whether to allow anonymous users to connect.

Add settings in the ACL file

In this example, the procedure to grant the following permissions is shown.

Username	Permission
user01	write
user02	read
user03	read, write

Add the following lines to the ACL file.

user user01
topic write #

user user02
topic read #

user user03
topic readwrite #

The meanings of the above settings are:

• user <username>
  • Specify the target user name.
• topic [read|write|readwrite] <topic>
  • Set permission for a topic.
  • Permission can be read, write, or readwrite (default).
  • Specify the topic name in <topic>, which can also be # (multi-level wild card) or + (single-level wild card).

Refer to mosquitto.conf man page for details on how to set ACLs.

Reload the configuration file

Send a SIGHUP signal to reload the ACL file.

$ sudo killall -HUP mosquitto

Configurations on SINETStream (client side)

The following procedure is needed for SINETStream to connect to the MQTT broker with authorization.

1. Prepare certificate
2. Edit the SINETStream’s configuration file
3. Create a program that uses SINETStream

Prepare certificate

The following certificate is required on the client side to use SSL/TLS connection.

• A CA certificate

Deploy the certificate to your convenient location. SINETStream reads the certificate from the path specified in the configuration file.

Edit the SINETStream’s configuration file

To connect to the MQTT broker with authorization, some configurations are required to determine the subject of authorization.

An example of SINETStream’s configuration file is shown below.

This is identical to the configuration for password authentication.

service-mqtt:
  brokers: broker.example.org:8884
  type: mqtt
  topic: topic-001
  consistency: AT_LEAST_ONCE
  tls:
    ca_certs: /opt/certs/cacert.pem
  username_pw_set:
    username: user03
    password: user03-pass

The settings for brokers, type, topic, consistency, tls are identical to those without authentication. Settings related to password authentication are under username_pw_set:.

The meanings of the above settings are:

• username
  • User name
• password
  • Password

Create a program that uses SINETStream

Your program will be identical with or without authorization. For example, a program that uses MessageWriter of the SINETStream’s Python API is shown below.

with sinetstream.MessageWriter(service='service-mqtt') as writer:
    writer.publish(b'message 001')

As you see, no code is written for authorization.

Behavior on authorization errors

An MQTT broker does not return authorization errors to clients. Therefore, SINETStream does not raise any exception when an authorization error should occur.