Introduction

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

    EMQX 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.

    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 EMQX to describe ACL rules:

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

    1. The second 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
    2. The third rule prohibits all clients from subscribing to the topics $SYS/# and #
    3. The fourth rule allows clients to publish and subscribe to all topics
    1. {allow, {user, "dashboard"}, subscribe, ["$SYS/#"]}.
    3. {allow, {ipaddr, "127.0.0.1"}, pubsub, ["$SYS/#", "#"]}.
    5. {deny, all, subscribe, ["$SYS/#", {eq, "#"}]}.
    7. {allow, all}.

    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:

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

    1. # etc/emqx.conf

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

    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.

    1. After the superuser function is enabled in the authentication plugin, EMQX 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
    10. acl_cache_ttl = 1m

    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

    When multiple ACL plugins are enabled at the same time, EMQX 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
      • Deny clients from passing authentication When default authentication is deny

    TIP

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