Documentation

# Password Authentication Using MongoDB

This authenticator implements the password verification algorithm and uses MongoDB database as credential storage.

# Storage Schema

MongoDB authenticator supports storing credentials as MongoDB documents. A user provides the collection name and a filter template for selecting the relevant document.

The document should contain fields with values for password_hash, salt, and is_superuser. The field names are configurable. The value for password_hash is required, other values are optional. The absence of salt value is interpreted as empty salt (salt = ""); the absence of is_superuser is interpreted as its false value.

Example of adding a document for a user with username user123, password secret, prefixed salt salt, and is_superuser true:

> db.mqtt_user.insertOne(
  {
      "username": "user123",
      "s": "salt",
      "is": true,
      "ph": "bede90386d450cea8b77b822f8887065e4e5abf132c2f9dccfcc7fbd4cba5e35"
  }
);
{
  acknowledged: true,
  insertedId: ObjectId("6290aa4959fbb6cf748c0148")
}
1
2
3
4
5
6
7
8
9
10
11
12

The corresponding config parameters are:

password_hash_algorithm {
    name = sha256
    salt_position = prefix
}

collection = "mqtt_user"
filter { username = "${username}" }

password_hash_field = "ph"
salt_field = "s"
is_superuser_field = "is"
1
2
3
4
5
6
7
8
9
10
11

WARING

When there are a significant number of users in the system make sure that the collections used by the selector are optimized and that effective indexes are used. Otherwise connecting MQTT clients will produce excessive load on the database and on the EMQX itself.

# Configuration

MongoDB authentication is identified with mechanism = password_based and backend = mongodb.

The authenticator supports connecting to MongoDB running in three different modes:

  • Standalone MongoDB server:

    {
  mechanism = password_based
  backend = mongodb
  enable = true

  password_hash_algorithm {
    name = sha256
    salt_position = suffix
  }

  collection = "mqtt_user"
  filter { username = "${username}" }

  mongo_type = single
  server = "127.0.0.1:27017"

  database = "mqtt"
  username = "emqx"
  password = "secret"
}
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20

  • MongoDB ReplicaSet (opens new window):

    {
  mechanism = password_based
  backend = mongodb
  enable = true

  password_hash_algorithm {
    name = sha256
    salt_position = suffix
  }

  collection = "mqtt_user"
  filter { username = "${username}" }

  mongo_type = rs
  servers = "10.123.12.10:27017,10.123.12.11:27017,10.123.12.12:27017"
  replica_set_name = "rs0"

  database = "mqtt"
  username = "emqx"
  password = "secret"
}
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21

  • MongoDB Sharded Cluster (opens new window):

    {
  mechanism = password_based
  backend = mongodb
  enable = true

  password_hash_algorithm {
    name = sha256
    salt_position = suffix
  }

  collection = "mqtt_user"
  filter { username = "${username}" }

  mongo_type = sharded
  servers = "10.123.12.10:27017,10.123.12.11:27017,10.123.12.12:27017"

  database = "mqtt"
  username = "emqx"
  password = "secret"
}
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20

# Common Configuration Options

# password_hash_algorithm

Standard password hashing options.

# collection

Required string value with the name of MongoDB collection where authentication rules are stored.

# filter

A map interpreted as MongoDB selector for credential lookup. Supports placeholders.

# database

Required string value with MongoDB database name to use.

# username

Optional string value with MongoDB user.

# password

Optional string value with MongoDB user password.

# pool_size

Optional integer value defining the number of concurrent connections from an EMQX node to a MongoDB server. The default value is 8.

# ssl

Standard SSL options for secure connecting to MongoDB (opens new window).

# srv_record

Optional boolean value, the default value is false. If set to true, EMQX will try to fetch information about MongoDB hosts, replica_set_name (for rs type), and auth_source from DNS records of the specified server(s). See DNS Seed List Connection Format (opens new window).

# topology

An optional map of some fine-grained MongoDB driver settings.

  • pool_size — integer value, the initial size of the internal connection pool.
  • max_overflow — integer value, number of overflow workers be created, when all workers from the internal pool are busy.
  • overflow_ttl — duration, number of milliseconds for overflow workers to stay in the internal pool before terminating.
  • overflow_check_period — duration, overflow_ttl check period for workers (in milliseconds).
  • local_threshold_ms — ms duration, secondaries only which RTTs fit in the window from lower RTT to lower RTT + local_threshold_ms could be selected for handling user's requests.
  • connect_timeout_ms — ms duration, timeout for establishing TCP connections.
  • server_selection_timeout_ms — ms duration, max time appropriate server should be selected by.
  • wait_queue_timeout_ms — ms duration, max time for waiting for a worker to be available in the internal pool.
  • heartbeat_frequency_ms — ms duration, default delay between Topology rescans.
  • min_heartbeat_frequency_ms — ms duration, the minimum delay between Topology rescans.

# Standalone MongoDB Options

# server

MongoDB server address to connect or to us as a seed, required.

# w_mode

Write mode, unsafe (default) or safe. The safe mode makes a getLastError request after every write in the sequence. If the reply says it failed then the rest of the sequence is aborted. Alternatively, unsafe mode issues every write without confirmation, so if a write fails you won't know about it and the remaining operations will be executed. This is unsafe but faster because there is no round-trip delay.

# MongoDB ReplicaSet Options

# servers

MongoDB server addresses to connect or to us as seeds, required.

# w_mode

Write mode, the same as for Standalone MongoDB.

# r_mode

Read mode, master (default) or slave_ok. master means that every query in a sequence must read only fresh data (from a master/primary server). If the connected server is not a master then the first read will fail, and the remaining operations will be aborted. slave_ok means every query is allowed to read stale data from a slave/secondary (fresh data from a master is fine too).

# replica_set_name

Replica set name to use, required. Can be overwritten with seeds if srv_record is set to true.

# MongoDB Cluster Options

# servers

MongoDB server addresses to connect or to us as seeds, required.

# w_mode

Write mode, the same as for Standalone MongoDB.

← Password Authentication Using HTTP →

Edit this page
What’s on this page