MongoDB ACL

For MongoDB ACL, an external MongoDB database is used to store ACL rules, which can store a large amount of data and dynamically manage ACLs for easy integration with external device management systems

Plugin:

  1. emqx_auth_mongo

TIP

The emqx_auth_mongo plugin also includes authentication, which can be disabled via comments

MongoDB connection information

MongoDB basic connection information needs to ensure that all nodes in the cluster can be accessed.

  1. # etc/plugins/emqx_auth_mongo.conf
  3. ## MongoDB Architecture type
  4. ##
  5. ## Value: single | unknown | sharded | rs
  6. auth.mongo.type = single
  8. ## rs mode needs to set rs name
  9. ## auth.mongo.rs_set_name =
  11. ## Server list, separated by comma in cluster mode
  12. ## Examples: 127.0.0.1:27017,127.0.0.2:27017...
  13. auth.mongo.server = 127.0.0.1:27017
  15. auth.mongo.pool = 8
  17. auth.mongo.login =
  19. auth.mongo.password =
  21. ## auth.mongo.auth_source = admin
  23. auth.mongo.database = mqtt
  25. auth.mongo.query_timeout = 5s
  27. ## SSL option
  28. # auth.mongo.ssl = false
  30. ## auth.mongo.ssl_opts.keyfile =
  32. ## auth.mongo.ssl_opts.certfile =
  34. ## auth.mongo.ssl_opts.cacertfile =
  36. ## MongoDB write mode.
  37. ##
  38. ## Value: unsafe | safe
  39. ## auth.mongo.w_mode =
  41. ## Mongo read mode.
  42. ##
  43. ## Value: master | slave_ok
  44. ## auth.mongo.r_mode =
  46. ## MongoDB topology configuration, generally not used, see MongoDB website documentation for details
  47. auth.mongo.topology.pool_size = 1
  48. auth.mongo.topology.max_overflow = 0
  49. ## auth.mongo.topology.overflow_ttl = 1000
  50. ## auth.mongo.topology.overflow_check_period = 1000
  51. ## auth.mongo.topology.local_threshold_ms = 1000
  52. ## auth.mongo.topology.connect_timeout_ms = 20000
  53. ## auth.mongo.topology.socket_timeout_ms = 100
  54. ## auth.mongo.topology.server_selection_timeout_ms = 30000
  55. ## auth.mongo.topology.wait_queue_timeout_ms = 1000
  56. ## auth.mongo.topology.heartbeat_frequency_ms = 10000
  57. ## auth.mongo.topology.min_heartbeat_frequency_ms = 1000

Default data structure

In the default configuration of MongoDB authentication, you need to ensure that the following collections are included in the database:

Authentication / Super Collection

  1. {
  2.   username: "user",
  3.   password: "password hash",
  4.   salt: "password salt",
  5.   is_superuser: false,
  6.   created: "2020-02-20 12:12:14"
  7. }

Sample data:

  1. use mqtt
  3. db.mqtt_user.insert({
  4.   "username": "emqx",
  5.   "password": "efa1f375d76194fa51a3556a97e641e61685f914d446979da50a551a4333ffd7",
  6.   "is_superuser": false,
  7.   "salt": ""
  8. })

ACL rule collection

  1. {
  2.     username: "username",
  3.     clientid: "clientid",
  4.     publish: ["topic1", "topic2", ...],
  5.     subscribe: ["subtop1", "subtop2", ...],
  6.     pubsub: ["topic/#", "topic1", ...]
  7. }

MongoDB ACL rule defines the publish, subscribe, and publish/subscribe information, and all allow lists are included in the rule.

Rule field description:

  • username: the user name of the connected client
  • clientid: the Client ID of the connected client
  • publish: the number of topics allowed to be published, supports wildcards
  • subscribe: the number of topics allowed to be subscribed to, supports wildcards
  • pubsub: the number of topics allowed to be published and subscribed to, supports wildcards

TIP

Wildcards can be used for topic, and placeholders can be added to the topic to match client information. For example, the topic will be replaced with the client ID of the current client when matching t/%c.

  • %u：user name
  • %c：Client ID

Sample data in the default configuration:

  1. use mqtt
  3. ## All users cannot subscribe and publish system topics
  4. ## Clients are allowed to subscribe to the topic of /smarthome/${clientid}/temperature with their own Client ID
  6. db.mqtt_acl.insert({
  7.   username: "$all",
  8.   clientid: "$all",
  9.   publish: ["#"],
  10.   subscribe: ["/smarthome/%c/temperature"]
  11. })

After enabling MongoDB ACL and successfully connecting with the username emqx, the client should have the appropriate topic permissions for the data.

super_query

When performing ACL authentication, EMQX Broker will use the current client information to execute a user-configured superuser query to query whether the client is a superuser. ACL queries are skipped when the client is a superuser.

  1. # etc/plugins/emqx_auth_mongo.conf
  3. ## Enable superuser
  4. auth.mongo.super_query = on
  6. ##collections for super queries
  7. auth.mongo.super_query.collection = mqtt_user
  9. ##Field for super user
  10. auth.mongo.super_query.super_field = is_superuser
  12. ## Superuser query selector, commas can be used to separate multiple conditions
  13. #auth.mongo.super_query.selector = username=%u, clientid=$all
  14. auth.mongo.super_query.selector = username=%u

MongoDB and query is used in the actual query under multiple conditions of the same selector:

  1. db.mqtt_user.find({
  2.   "username": "wivwiv"
  3.   "clientid": "$all"
  4. })

You can use the following placeholders in your query conditions, and EMQX Broker will automatically populate with client information when executed:

  • %u：user name
  • %c：Client ID

You can adjust the super user query according to business to achieve more business-related functions, such as adding multiple query conditions and using database preprocessing functions. However, in any case, the superuser query needs to meet the following conditions:

  1. The query result must include the is_superuser field, which should be explicitly true

TIP

If superuser functionality is not needed, it can be more efficient when commenting and disabling this option

acl_query

When performing ACL authentication, EMQX Broker will use the current client information to execute the user-configured superuser query. If superuser query is not enabled or the client is not a superuser, ACL query will be used to find out the ACL rules of client in the database.

  1. # etc/plugins/emqx_auth_mongo.conf
  3. auth.mongo.acl_query = on
  5. auth.mongo.acl_query.collection = mqtt_acl
  7. ## Query selector, commas can be used to separate multiple conditions
  8. ## auth.mongo.acl_query.selector = username=%u,clientid=%c
  9. auth.mongo.acl_query.selector = username=%u
  11. ## Using multiple query selectors
  12. ## auth.mongo.acl_query.selector.1 = username=$all
  13. ## auth.mongo.acl_query.selector.2 = username=%u

MongoDB and query is used in the actual query under multiple conditions of the same selector:

  1. db.mqtt_acl.find({
  2.   "username": "emqx"
  3.   "clientid": "$all"
  4. })

MongoDB or query is used in actual query under multiple selectors:

  1. db.mqtt_acl.find({
  2.   "$or": [
  3.     {
  4.       "username": "$all"
  5.     },
  6.     {
  7.       "username": "emqx"
  8.     }
  9.   ]
  10. })

You can use the following placeholders in ACL queries, and EMQX Broker will automatically populate with client information when executed:

  • %u：username
  • %c：Client ID

TIP

MongoDB ACL rules need to use the above data structures strictly.

All rules added in MongoDB ACL are allow rules. i.e. a whitelist.

When a client’s rules list is empty, EMQX continues to check the next auth/ACL plugin. Otherwise the check returns immediately without proceeding to the next auth/ACL plugins.

When the rule is non-empty and does not match the corresponding pub/sub permission, an ath/ACL failure will be returned (the corresponding pub/sub behavior will be denied) and the auth/ACL chain will be terminated.

When more than one auth/ACL plugins are in use, it is recommended to position MongoDB ACL after other auth/ACL plugins in the enabled plugins list.