# 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:

emqx_auth_mongo
1

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.

# etc/plugins/emqx_auth_mongo.conf

## MongoDB Architecture type
##
## Value: single | unknown | sharded | rs
auth.mongo.type = single

##rs mode needs to set rs name
## auth.mongo.rs_set_name =

## Server list, which is separated by comma in cluster mode
## Examples: 127.0.0.1:27017,127.0.0.2:27017...
auth.mongo.server = 127.0.0.1:27017

auth.mongo.pool = 8

auth.mongo.login =

auth.mongo.password =

## auth.mongo.auth_source = admin

auth.mongo.database = mqtt

auth.mongo.query_timeout = 5s

## SSL option
# auth.mongo.ssl = false

## auth.mongo.ssl_opts.keyfile =

## auth.mongo.ssl_opts.certfile =

## auth.mongo.ssl_opts.cacertfile =

## MongoDB write mode.
##
## Value: unsafe | safe
## auth.mongo.w_mode =

## Mongo read mode.
##
## Value: master | slave_ok
## auth.mongo.r_mode =

## MongoDB topology configuration, which is not used generally. See MongoDB official ##website documentation
auth.mongo.topology.pool_size = 1
auth.mongo.topology.max_overflow = 0
## auth.mongo.topology.overflow_ttl = 1000
## auth.mongo.topology.overflow_check_period = 1000
## auth.mongo.topology.local_threshold_ms = 1000
## auth.mongo.topology.connect_timeout_ms = 20000
## auth.mongo.topology.socket_timeout_ms = 100
## auth.mongo.topology.server_selection_timeout_ms = 30000
## auth.mongo.topology.wait_queue_timeout_ms = 1000
## auth.mongo.topology.heartbeat_frequency_ms = 10000
## auth.mongo.topology.min_heartbeat_frequency_ms = 1000

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

# Default data structure

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

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

The sample data in the default configuration is as follows:

use mqtt

db.mqtt_user.insert({
  "username": "emqx",
  "password": "efa1f375d76194fa51a3556a97e641e61685f914d446979da50a551a4333ffd7",
  "is_superuser": false,
  "salt": ""
})
1
2
3
4
5
6
7
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

# etc/plugins/emqx_auth_mongo.conf

auth.mongo.password_hash = sha256
1
2
3

# auth_selector

During authentication, EMQ X 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

# etc/plugins/emqx_auth_mongo.conf

auth.mongo.auth_query.collection = mqtt_user

## If salting is enabled, it needs to be configured as password,salt
## Value:  password | password,salt
auth.mongo.auth_query.password_field = password

auth.mongo.auth_query.selector = username=%u
1
2
3
4
5
6
7
8
9

You can use the following placeholders in the selector, and EMQ X 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 EMQ X 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 EMQ X 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