-wip

Author: savonarola

en_US/security/authn/authn.md

@@ -1,17 +1,36 @@
 # Introduction
 
-Authentication is an important part of most applications. MQTT protocol supports username/password authentication. Enabling authentication can effectively prevent illegal client connections.
+Authentication is an important part of most applications. MQTT protocol supports username/password authentication as
+well as some enhanced methods, like SCRAM authentication. Enabling authentication can effectively prevent illegal client connections.
 
-Authentication in EMQX Broker means that when a client connects to EMQX Broker, the server configuration  is used to control the client's permission to connect to the server.
+Authentication in EMQX Broker means that when a client connects to EMQX Broker, the server configuration is used to control the client's permission to connect to the server.
 
 EMQX Broker's authentication support includes two levels:
 
-- The MQTT protocol specifies the user name and password in the CONNECT packet by itself. EMQX Broker supports multiple forms of authentication based on Username, ClientID, HTTP, JWT, LDAP, and various databases such as MongoDB, MySQL, PostgreSQL, Redis through plugins.
+- The MQTT protocol itself specifies authentication primitives. EMQX Broker supports multiple variants of MQTT-level authentication:
+  * username/password authentication with various backends (MongoDB, MySQL, PostgreSQL, Redis and built-in database);
+  * SCRAM authentication with built-in database;
+  * JWT authentication;
+  * authentication via custom HTTP API.
 - At the transport layer, TLS guarantees client-to-server authentication using client certificates and ensures that the server verifies the server certificate to the client. PSK-based TLS/DTLS authentication is also supported.
 
-This authentication methods supported by EMQX and the configuration methods of the corresponding plugins are introduced in this article.
+In this article we describe EMQX authentication and its configuration concepts.
 
-## Authentication method
+## Authentication sources and authentication chains
+
+Authentication source is an EMQX module that implements authentication. The following authentication sources are
+available by default:
+
+| mechanism        | backend            | description |
+| ----             | ------------------ | ----------- |
+| password_based   | built_in_database  |
+| password_based   | mysql              |
+| password_based   | postgresql         |
+| password_based   | mongodb            |
+| password_based   | redis              |
+| password_based   | http               |
+| jwt              |                    |
+| scram            | built_in_database  |
 
 EMQX supports the use of built-in data sources (files, built-in databases), JWT, external mainstream databases, and custom HTTP APIs as authentication data sources.
 
@@ -218,7 +237,7 @@ The cipher list supported by the server needs to be specified explicitly. The de
 listener.ssl.external.ciphers = ECDHE-ECDSA-AES256-GCM-SHA384,ECDHE-RSA-AES256-GCM-SHA384,ECDHE-ECDSA-AES256-SHA384,ECDHE-RSA-AES256-SHA384,ECDHE-ECDSA-DES-CBC3-SHA,ECDH-ECDSA-AES256-GCM-SHA384,ECDH-RSA-AES256-GCM-SHA384,ECDH-ECDSA-AES256-SHA384,ECDH-RSA-AES256-SHA384,DHE-DSS-AES256-GCM-SHA384,DHE-DSS-AES256-SHA256,AES256-GCM-SHA384,AES256-SHA256,ECDHE-ECDSA-AES128-GCM-SHA256,ECDHE-RSA-AES128-GCM-SHA256,ECDHE-ECDSA-AES128-SHA256,ECDHE-RSA-AES128-SHA256,ECDH-ECDSA-AES128-GCM-SHA256,ECDH-RSA-AES128-GCM-SHA256,ECDH-ECDSA-AES128-SHA256,ECDH-RSA-AES128-SHA256,DHE-DSS-AES128-GCM-SHA256,DHE-DSS-AES128-SHA256,AES128-GCM-SHA256,AES128-SHA256,ECDHE-ECDSA-AES256-SHA,ECDHE-RSA-AES256-SHA,DHE-DSS-AES256-SHA,ECDH-ECDSA-AES256-SHA,ECDH-RSA-AES256-SHA,AES256-SHA,ECDHE-ECDSA-AES128-SHA,ECDHE-RSA-AES128-SHA,DHE-DSS-AES128-SHA,ECDH-ECDSA-AES128-SHA,ECDH-RSA-AES128-SHA,AES128-SHA
 ```
 
-## PSK authentication 
+## PSK authentication
 If you want to use PSK authentication, you need to comment out `listener.ssl.external.ciphers` in [TLS Authentication](#auth-tls), and then configure ` listener.ssl.external.psk_ciphers`:
 
 ```bash

en_US/security/blacklist.md

@@ -1,4 +1,4 @@
-# Blacklisting/Banning ClientID, user name or IP
+# Blacklisting/Banning ClientDI, user name or IP
 
 EMQX Broker provides users with a blacklisting/banning functionality.
 
@@ -7,14 +7,14 @@ to deny access of the client.
 
 In addition to the client identifier, it also supports direct ban of user names or source IP addresses.
 
-For specific usage of the HTTP API, see  the `/banned` API document.
-
 ::: tip
 The blacklist is only applicable to a small number of client bans.
 If there are a large number of clients requiring authentication management,
-please use the [authentication](./authn/authn.md)  function.。
+please use the [authentication](./authn/authn.md)  function.
 :::
 
+## Flapping Clients
+
 Based on the blacklist function, EMQX supports automatic banning of clients that are frequently
 logged in for a short period of time, and rejects these clients for a period of time
 to prevent such clients from consuming server resources which in turn may affect other clients.
@@ -23,21 +23,103 @@ It should be noted that the automatic ban only bans the client identifier,
 not the user name and IP address.
 That is to say, a malicious client may still able to attack if they change client identifier for each attempt.
 
-This feature is disabled by default, set `enable_flapping_detect` configuration item to `on` in `emqx.conf` to enable it.
+This feature is disabled by default, set `enable` for `flapping_detect` section to `true` in `emqx.conf` to enable it.
 
 ```bash
-zone.external.enable_flapping_detect = off
+flapping_detect {
+
+  enable = false
+
+}
 ```
 
 The user can adjust the trigger threshold and the ban time with below configs
 
 ```bash
-flapping_detect_policy = "30, 1m, 5m"
+flapping_detect {
+
+  enable = true
+
+  ## The max disconnect allowed of a MQTT Client in `window_time`
+  max_count = 15
+
+  ## The time window for flapping detect
+  window_time = 1m
+
+  ## How long the clientid will be banned
+  ban_time = 5m
+
+}
+```
+
+These settings may be specified individually for each zone.
+
+## HTTP API
+
+Ban user:
+
+```shell
+## Request
+curl -i \
+--basic \
+-u admin:public \
+-X POST \
+-H "Content-Type: application/json" \
+-d '{"as": "clientid", "who": "malicious_client"}' \
+http://localhost:18083/api/v5/banned
+
+## Return
+{
+    "as":"clientid",
+    "at":"2022-05-17T17:07:24+03:00",
+    "by":"mgmt_api",
+    "reason":"",
+    "until":"2022-05-17T17:12:24+03:00",
+    "who":"malicious_client"
+}
+```
+
+List banned users:
+
+```shell
+## Request
+curl -i \
+--basic \
+-u admin:public \
+-X GET \
+http://localhost:18083/api/v5/banned?page=1&count=10
+
+## Return
+{
+    "data": [
+        {
+            "as":"clientid",
+            "at":"2022-05-17T17:07:24+03:00",
+            "by":"mgmt_api",
+            "reason":"",
+            "until":"2022-05-17T17:12:24+03:00",
+            "who":"malicious_client"
+        }
+    ],
+    "meta": {
+        "count":1,
+        "limit":100,
+        "page":1
+    }
+}
+```
+
+Remove banned user:
+
+```shell
+## Request
+curl -i \
+--basic \
+-u admin:public \
+-X DELETE \
+http://localhost:18083/api/v5/banned/clientid/malicious_client
+
+## Response: HTTP 204
 ```
 
-The value of this configuration item is separated by `,`,
-which repectively indicates the number of times that the client is offline,
-the detection time range, and the ban time.
 
-In the above example, the config means that if a client goes offline 30 times in 1 minute,
-then this client identifie is banned for 5 minutes.

run

@@ -0,0 +1,3 @@
+docker run --rm --name emqx -p 18083:18083 -p 1883:1883 \
+    --sysctl net.core.somaxconn=1024 \
+    emqx/emqx:latest