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
  2. ## MongoDB Architecture type
  3. ##
  4. ## Value: single | unknown | sharded | rs
  5. auth.mongo.type = single
  6. ##rs mode needs to set rs name
  7. ## auth.mongo.rs_set_name =
  8. ## Server list, which is separated by comma in cluster mode
  9. ## Examples: 127.0.0.1:27017,127.0.0.2:27017...
  10. auth.mongo.server = 127.0.0.1:27017
  11. auth.mongo.pool = 8
  12. auth.mongo.login =
  13. auth.mongo.password =
  14. ## auth.mongo.auth_source = admin
  15. auth.mongo.database = mqtt
  16. auth.mongo.query_timeout = 5s
  17. ## SSL option
  18. # auth.mongo.ssl = false
  19. ## auth.mongo.ssl_opts.keyfile =
  20. ## auth.mongo.ssl_opts.certfile =
  21. ## auth.mongo.ssl_opts.cacertfile =
  22. ## MongoDB write mode.
  23. ##
  24. ## Value: unsafe | safe
  25. ## auth.mongo.w_mode =
  26. ## Mongo read mode.
  27. ##
  28. ## Value: master | slave_ok
  29. ## auth.mongo.r_mode =
  30. ## MongoDB topology configuration, which is not used generally. See MongoDB official ##website documentation
  31. auth.mongo.topology.pool_size = 1
  32. auth.mongo.topology.max_overflow = 0
  33. ## auth.mongo.topology.overflow_ttl = 1000
  34. ## auth.mongo.topology.overflow_check_period = 1000
  35. ## auth.mongo.topology.local_threshold_ms = 1000
  36. ## auth.mongo.topology.connect_timeout_ms = 20000
  37. ## auth.mongo.topology.socket_timeout_ms = 100
  38. ## auth.mongo.topology.server_selection_timeout_ms = 30000
  39. ## auth.mongo.topology.wait_queue_timeout_ms = 1000
  40. ## auth.mongo.topology.heartbeat_frequency_ms = 10000
  41. ## 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
  2. db.mqtt_user.insert({
  3. "username": "emqx",
  4. "password": "efa1f375d76194fa51a3556a97e641e61685f914d446979da50a551a4333ffd7",
  5. "is_superuser": false,
  6. "salt": ""
  7. })

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
  2. 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
  2. auth.mongo.auth_query.collection = mqtt_user
  3. ## If salting is enabled, it needs to be configured as password,salt
  4. ## Value: password | password,salt
  5. auth.mongo.auth_query.password_field = password
  6. 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