Introduction

Publish/Subscribe ACL refers to permission control for PUBLISH/SUBSCRIBE operations. For example, the user name with the name Anna is prohibited to publish messages to open / elsa / door.

EMQ X supports the permission management of client through client publish/subscribe ACLs. This chapter describes the publish/subscribe ACLs supported by EMQ X and the configuration methods of corresponding plugins.

ACL Plugins

EMQ X supports the use of configuration files, external mainstream databases, and custom HTTP APIs as ACL data sources.

The data source connection and access control functions are implemented through plugins, and the corresponding plugins need to be enabled before use.

When a client subscribes to a topic or publishes a message, the plugin implements the management of publishing and subscription permissions for the client by checking whether the target topic is in the specified data source list.

Configuration file

The configuration file is used to provide an authentication data source, which is suitable for ACL management with less changes.

External Database

The external database can store a large amount of data and dynamically manage ACLs to facilitate integration with external device management systems.

Else

HTTP ACL enables complex ACL management.

TIP

The ACL function is included in the authentication plugin. After changing the plugin configuration, you need to restart the plugin to take effect.

Detailed Rules

ACL is a collection of allowing and denying conditions. The following elements are used in EMQ X to describe ACL rules:

  1. ## Allow-Deny Who Pub-Sub Topic
  3. "Allow/Deny"  "Who"  "Subscribe/Publish" "Topics"

When there are multiple ACL rules at the same time, EMQ X will merge them in order according to the rules. Taking the default ACL in ACL file as an example, it loads the rule from bottom to top:

  1. The first rule allows clients to publish and subscribe to all topics
  2. The second rule prohibits all clients from subscribing to the topics $SYS/# and #
  3. The third rule allows clients with IP address 127.0.0.1 to publish/subscribe to the topics $SYS/#and #, which makes a special case for the second rule
  4. The fourth rule allows clients with the username dashboard to subscribe to the topic $SYS/#, which makes a special case for the second rule
  1. {allow, {user, "dashboard"}, subscribe, ["$SYS/#"]}.
  3. {allow, {ipaddr, "127.0.0.1"}, pubsub, ["$SYS/#", "#"]}.
  5. {deny, all, subscribe, ["$SYS/#", {eq, "#"}]}.
  7. {allow, all}.

Authentication results

Any ACL authentication eventually returns a result:

  • Allow: Client operation is allowed after checking
  • Deny: Client operations are denied after inspection
  • Ignore: No ACL permission information was found, and the result could not be explicitly determined as allowed or denied. It will be determined by the next ACL plugin or the default ACL rule.

Global Configuration

In the default configuration, ACL is open for authentication, which means when the authentication result is ignore, the client is allowed to pass the authentication.

This property can be changed through the ACL configuration in etc / emqx.conf:

  1. # etc/emqx.conf
  3. ## Default authentication when ACLs do not match
  4. ## Value: allow | deny
  5. acl_nomatch = allow

Configure the default ACL file and use the file to define the default ACL rule:

  1. # etc/emqx.conf
  3. acl_file = etc/acl.conf

Configure the response action when ACL authentication is deny, the device will be disconnected if it is ignore:

  1. # etc/emqx.conf
  3. ## Value: ignore | disconnect
  4. acl_deny_action = ignore

TIP

In MQTT v3.1 and v3.1.1 protocols, the server returns without any packet error after the publishing operation is rejected, which is a flaw in the protocol design. However, a corresponding error message has been supported on the MQTT v5.0 protocol.

Superuser

Clients can have a “Superuser” identity, which has the highest permissions without being restricted by ACLs.

  1. After the superuser function is enabled in the authentication plugin, EMQ X will check whether the client has superuser identity first when publishing the subscription

  2. When the client is a super user, the authentication is passed and subsequent ACL checks are skipped

ACL Cache

ACL cache allows the client to cache an ACL rule into memory after hitting it, so that it can be used directly next time. Enabling ACL cache can improve the performance of ACL check when the client publishes and subscribes frequently.

You can configure the ACL cache size and cache time in etc / emqx.conf:

  1. # etc/emqx.conf
  3. ## Whether to enable
  4. enable_acl_cache = on
  6. ## Maximum number of cache rules per client
  7. acl_cache_max_size = 32
  9. ## Cache expiry time, cache will be cleared after timeout
  10. acl_cache_ttl = 1m

Clear cache

After updating the ACL rule, some clients cannot take effect immediately because the cache already exists. You need to manually clear all ACL caches to make them taking effect immediately :

Refer to HTTP API - CLear ACL cache

ACL Authentication Chain

When multiple ACL plugins are enabled at the same time, EMQ X will perform chain authentication in the order in which the plugins are opened:

  • -Once authentication passed, terminate the chain and allow clients to pass authentication
  • Once authorization fails, terminate the chain and deny clients from passing authentication
  • if keep failing until the last ACL plugin, judge according to the default authentication configuration
    • Allow client to pass authentication when default authentication is allow
    • Deny clients from passing authentication When default authentication is deny

_images/guide_3.png

TIP

Enabling only one ACL plugin at the time can improve client ACL checking performance.