MongoDB

MongoDB authentication uses an external MongoDB database as the authentication data source, which can store a large amount of data and facilitate integration with external device management systems.

Plugin:

  1. emqx_auth_mongo

TIP

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

To enable MongoDB authentication, you need to configure the following in etc/plugins/emqx_auth_mongo.conf :

MongoDB Connection information

For MongoDB basic connection information, it needs to ensure that all nodes in the cluster can access.

  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, which is 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, which is not used generally. See MongoDB official ##website documentation
  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 database has the following collections:

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

The sample data in the default configuration is as follows:

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

After MongoDB authentication is enabled, you can connect with username: emqx, password: public.

TIP

This is the collection structure used by default configuration. After being familiar with the use of the plugin, you can use any collection that meets the conditions for authentication.

Salting rules and hash methods

MongoDB authentication support to configure Salting rules and hash methods：

  1. # etc/plugins/emqx_auth_mongo.conf
  3. auth.mongo.password_hash = sha256

auth_selector

During authentication, EMQX Broker will use the current client information to populate and execute the user-configured authentication SQL to query the client’s authentication data in the database.

MongoDB supported configuration collection name, password field, and selector command

  1. # etc/plugins/emqx_auth_mongo.conf
  3. auth.mongo.auth_query.collection = mqtt_user
  5. ## If salting is enabled, it needs to be configured as password,salt
  6. ## Value:  password | password,salt
  7. auth.mongo.auth_query.password_field = password
  9. auth.mongo.auth_query.selector = username=%u

You can use the following placeholders in the selector, and EMQX Broker will be automatically populated with client information when executed:

  • %u：Username
  • %c：Client ID
  • %C：TLS certificate common name (the domain name or subdomain name of the certificate), valid only for TLS connections
  • %d：TLS certificate subject, valid only for TLS connections

You can adjust the authentication 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 authentication query must meet the following conditions:

  1. The query result must include the password field, which is used by EMQX Broker to compare with the client password
  2. If the salting configuration is enabled, the query result must include the salt field, which is used by EMQX Broker as the salt value
  3. MongoDB uses the findOne query command to ensure that the query results you expect are shown in the first data