Access Control
This section introduces authentication and authorization-related settings.
Example Configuration
auth {
allow_anonymous = true # Allow clients to connect without providing username/password
no_match = allow # Default action if no ACL rules match
deny_action = ignore # Action to take if an ACL check rejects an operation
cache = {
max_size = 32 # Maximum number of ACL entries to cache for a client
ttl = 1m # Time after which an ACL cache entry will be deleted
}
password = {include "/etc/nanomq_pwd.conf"} # Path to the password configuration file
acl = {include "/etc/nanomq_acl.conf"} # Path to the ACL configuration file
}
Configuration Items
allow_anonymous
: Specifies whether clients are allowed to connect without providing a username and password. Default:true
no_match
: Specifies the default action (allow or deny) if no ACL rules match the client's operation. Default:allow
deny_action
: Specifies the action to take if an ACL check rejects an operation. Default:ignore
; supported options areignore
: do nothingdisconnect
: disconnect the client
cache
(optional): Contains settings related to the ACL cache:max_size
: Specifies the maximum number of ACL entries that can be cached for a client. Older records are evicted from the cache when the specified number is exceeded. Default: 32ttl
: Specifies the time after which an ACL cache entry will be deleted. Default: 1m
ACL can use separate configuration files (specified by the include
method). And below are the explanation of each configuration file.
nanomq_pwd.conf
Write the username and password in this format username:password
and save it to the nanomq_pwd.conf
file.
Example:
"admin": "public" # Username and password for the admin user
"client": "public" # Username and password for a client user
nanomq_acl.conf
rules = [
# # Allow MQTT client using username "dashboard" to subscribe to "$SYS/#" topics
{"permit": "allow", "username": "dashboard", "action": "subscribe", "topics": ["$SYS/#"]}
# # Deny "All Users" subscribe to "$SYS/#" "#" Topics
# {"permit": "deny", "username": "#", "action": "subscribe", "topics": ["$SYS/#", "#"]}
# # Allow any other publish/subscribe operation
{"permit": "allow"}
]
rules
: An array of ACL rules. Each rule is an object with the following properties:
permit
: Specifies whether the operation is toallow
ordeny
.username
: Specifies the username to which the rule applies. "#
" means all usersaction
: Specifies the MQTT operation (likepublish
,subscribe
orpubsub
) to which the rule applies.topics
: Specifies the MQTT topics to which the rule applies.clientid
: Specifies the clientID to which the rule applies. "#
" means all client IDs.and
: AND operationor
: OR operation
Each rule is processed in order, and processing stops at the first match. If no rules match, the action specified by the no_match
configuration item is applied.
HTTP Authentication
This section outlines the configuration for HTTP authentication, which allows the MQTT broker to authenticate clients using HTTP requests. It includes settings for authentication requests (auth_req
), superuser requests (super_req
), and Access Control List requests (acl_req
).
Example Configuration
http_auth = {
auth_req {
url = "http://127.0.0.1:80/mqtt/auth" # HTTP URL API path for Auth Request
method = "POST" # HTTP Request Method for Auth Request
headers.content-type = "application/x-www-form-urlencoded" # HTTP Request Headers for Auth Request
params = {clientid = "%c", username = "%u", password = "%P"} # Parameters to construct request body
}
super_req {
url = "http://127.0.0.1:80/mqtt/superuser" # HTTP URL API path for SuperUser Request
method = "POST" # HTTP Request Method for SuperUser Request
headers.content-type = "application/x-www-form-urlencoded" # HTTP Request Headers for SuperUser Request
params = {clientid = "%c", username = "%u", password = "%P"} # Parameters to construct request body
}
acl_req {
url = "http://127.0.0.1:8991/mqtt/acl" # HTTP URL API path for ACL Request
method = "POST" # HTTP Request Method for ACL Request
headers.content-type = "application/x-www-form-urlencoded" # HTTP Request Headers for ACL Request
params = {clientid = "%c", username = "%u", access = "%A", ipaddr = "%a", topic = "%t", mountpoint = "%m"} # Parameters used to construct the request body
}
auth.http.super_req.url = "http://127.0.0.1:80/mqtt/superuser" # HTTP URL API path for SuperUser Request
timeout = 5s # Time-out time for the request
connect_timeout = 5s # Connection time-out time
pool_size = 32 # Connection process pool size
}
Configuration Items
auth_req
url
: Specifies the HTTP URL API path for the corresponding request. Example: http://127.0.0.1:80/mqtt/authmethod
: Specifies the HTTP request method for the corresponding request. This could be eitherPOST
orGET
. Default:POST
headers.<Any>
: Specify the data in the HTTP request header. <Key> Specify the field name in the HTTP request header, and the value of this configuration item is the corresponding field value. <Key> can be the standard HTTP request header field. User can also customize the field to configure multiple different request header fields. Example as follows:headers.content-type
: Specifies the HTTP request headers for the corresponding request. The content-type header is used to indicate the media type of the resource that the request sends to the server. You can keep specifying other headers of HTTP here as followingheaders.accept
:headers.accept
: Specifies the value for theAccept
header in the HTTP request sent for authentication. Other headers likecookie
anddate
follows same rule.params
: Specifies the parameters used to construct the request body or query string parameters.- When using the GET method, the value will be converted into
k=v
key-value pairs separated by&
and sent as query string parameters. All placeholders will be replaced by run-time data. - When using the POST method, the value will be converted into
k=v
key-value pairs separated by&
and sent in the form of Request Body. All placeholders will be replaced by run-time data.
Option values include:
%u
: Username%c
: MQTT Client ID%a
: Client's network IP address%r
: The protocol used by the client can be:mqtt, mqtt-sn, coap, lwm2m and stomp%P
: Password%p
: Server port for client connection%C
: Common Name in client certificate%d
: Subject in client certificate
- When using the GET method, the value will be converted into
super_req
TIP
The super_req
configuration refers to the Superuser, who has the privilege to bypass all other access control rules. It shares identical configuration items in their setups except the URL path.
url
: For example, http://127.0.0.1:80/mqtt/superusermethod
:Specifies the HTTP request method for the corresponding request. This could be eitherPOST
orGET
. Default:POST
headers.<Any>
: Specify the data in the HTTP request header. <Key> Specify the field name in the HTTP request header, and the value of this configuration item is the corresponding field value. <Key> can be the standard HTTP request header field. User can also customize the field to configure multiple different request header fields. Example as follows:headers.content-type
:Specifies the HTTP request headers for the corresponding request. The content-type header is used to indicate the media type of the resource that the request sends to the server. You can keep specifying other headers of HTTP here as followingheaders.accept
:headers.accept
: Specifies the value for theAccept
header in the HTTP request sent for authentication. Accept header is used by HTTP clients to tell the server which type of content they expect/prefer as response.
params
: Specifies the parameters used to construct the request body or query string parameters.- When using the GET method, the value will be converted into
k=v
key-value pairs separated by&
and sent as query string parameters. All placeholders will be replaced by run-time data. - When using the POST method, the value will be converted into
k=v
key-value pairs separated by&
and sent in the form of Request Body. All placeholders will be replaced by run-time data.
Option values are identical with the that in
auth_req
- When using the GET method, the value will be converted into
acl_req
url
: Specifies the HTTP URL API path for the corresponding request.method
: Specifies the HTTP request method for the corresponding request. This could be eitherPOST
orGET
. Default:POST
headers.<Any>
: Specify the data in the HTTP request header. <Key> Specify the field name in the HTTP request header, and the value of this configuration item is the corresponding field value. <Key> can be the standard HTTP request header field. User can also customize the field to configure multiple different request header fields. Example as follows:headers.content-type: Specifies the HTTP request headers for the corresponding request. The content-type header is used to indicate the media type of the resource that the request sends to the server. You can keep specifying other headers of HTTP here as following
headers.accept`:headers.accept
:Specifies the value for theAccept
header in the HTTP request sent for authentication.params
: Specifies the parameters used to construct the request body or query string parameters:- When using the GET method, the value will be converted into
k=v
key-value pairs separated by&
and sent as query string parameters. - When using the POST method, the value will be converted into
k=v
key-value pairs separated by&
and sent in the form of Request Body. All placeholders will be replaced by run-time data ,
These parameters can include variables like:
%A
: Permission to be verified:1
for subscription and2
for publish%u
: Username%c
: MQTT Client ID%a
: Client's network IP address%r
: The protocol used by the client can be:mqtt, mqtt-sn, coap, lwm2m and stomp%m
: Mount point%t
: Topic
- When using the GET method, the value will be converted into
General ACL configuration items
timeout
: Specifies the time-out duration for the request. This is the maximum time that the server will wait for a response after sending the request. 0s
means never timeout.
connect_timeout
: Specifies the connection time-out duration, which is the maximum time the client will wait while trying to establish a connection with the server.0s
means never timeout.
pool_size
: Specifies the size of the connection process pool, which is the maximum number of concurrent connections that can be established.
Upcoming Features
TLS-related configuration items will be supported for HTTP authentication, including acl_rep
, super_req
, and http_auth
in upcoming releases, please stay tuned.
tls {
keyfile="/etc/certs/key.pem"
certfile="/etc/certs/cert.pem"
cacertfile="/etc/certs/cacert.pem"
}