diff --git a/apps/emqx/src/emqx_schema.erl b/apps/emqx/src/emqx_schema.erl
index 4b1f0c55f..5958167cd 100644
--- a/apps/emqx/src/emqx_schema.erl
+++ b/apps/emqx/src/emqx_schema.erl
@@ -1355,11 +1355,12 @@ str(S) when is_list(S) ->
     S.
 
 authentication(Desc) ->
-    #{ type => hoconsc:union([typerefl:map(), hoconsc:array(typerefl:map())])
-     , desc => [Desc, "<br>", """
+    #{ type => hoconsc:lazy(hoconsc:union([typerefl:map(), hoconsc:array(typerefl:map())]))
+     , desc => iolist_to_binary([Desc, "<br>", """
 Authentication can be one single authenticator instance or a chain of authenticators as an array.
 The when authenticating a login (username, client ID, etc.) the authenticators are checked
-in the configured order.
-"""
-               ]
+in the configured order.<br>
+EMQ X comes with a set of pre-built autenticators, for more details, see
+<code>authenticator_config</code>.
+"""])
      }.
diff --git a/apps/emqx_authn/src/emqx_authn_schema.erl b/apps/emqx_authn/src/emqx_authn_schema.erl
index c0f16b3f3..b36e88ebf 100644
--- a/apps/emqx_authn/src/emqx_authn_schema.erl
+++ b/apps/emqx_authn/src/emqx_authn_schema.erl
@@ -23,8 +23,10 @@
         , fields/1
         ]).
 
-%% just a stub, never used at root level
-roots() -> [].
+%% only for doc generation
+roots() -> [{authenticator_config,
+             #{type => hoconsc:union(config_refs([Module || {_AuthnType, Module} <- emqx_authn:providers()]))
+               }}].
 
 fields(_) -> [].
 
@@ -35,3 +37,6 @@ common_fields() ->
 enable(type) -> boolean();
 enable(default) -> true;
 enable(_) -> undefined.
+
+config_refs(Modules) ->
+    lists:append([Module:refs() || Module <- Modules]).
diff --git a/apps/emqx_authn/src/simple_authn/emqx_authn_http.erl b/apps/emqx_authn/src/simple_authn/emqx_authn_http.erl
index c99806341..ceb4b30a8 100644
--- a/apps/emqx_authn/src/simple_authn/emqx_authn_http.erl
+++ b/apps/emqx_authn/src/simple_authn/emqx_authn_http.erl
@@ -40,12 +40,11 @@
 %% Hocon Schema
 %%------------------------------------------------------------------------------
 
-namespace() -> "authn-password_based-http_server".
+namespace() -> "authn-http".
 
 roots() ->
-    [ {config, {union, [ hoconsc:ref(?MODULE, get)
-                       , hoconsc:ref(?MODULE, post)
-                       ]}}
+    [ {config, hoconsc:mk(hoconsc:union(refs()),
+                          #{})}
     ].
 
 fields(get) ->
@@ -61,8 +60,8 @@ fields(post) ->
     ] ++ common_fields().
 
 common_fields() ->
-    [ {mechanism,       'password-based'}
-    , {backend,         'http'}
+    [ {mechanism,       hoconsc:enum(['password-based'])}
+    , {backend,         hoconsc:enum(['http'])}
     , {url,             fun url/1}
     , {body,            fun body/1}
     , {request_timeout, fun request_timeout/1}
diff --git a/apps/emqx_authn/src/simple_authn/emqx_authn_jwt.erl b/apps/emqx_authn/src/simple_authn/emqx_authn_jwt.erl
index 1b7c5b87d..c4e04eac3 100644
--- a/apps/emqx_authn/src/simple_authn/emqx_authn_jwt.erl
+++ b/apps/emqx_authn/src/simple_authn/emqx_authn_jwt.erl
@@ -40,10 +40,9 @@
 namespace() -> "authn-jwt".
 
 roots() ->
-    [ {config, {union, [ hoconsc:mk('hmac-based')
-                       , hoconsc:mk('public-key')
-                       , hoconsc:mk('jwks')
-                       ]}}
+    [ {config, hoconsc:mk(hoconsc:union(refs()),
+                          #{}
+                         )}
     ].
 
 fields('hmac-based') ->
diff --git a/apps/emqx_authn/src/simple_authn/emqx_authn_mnesia.erl b/apps/emqx_authn/src/simple_authn/emqx_authn_mnesia.erl
index 095dc6ef8..d1fc121ca 100644
--- a/apps/emqx_authn/src/simple_authn/emqx_authn_mnesia.erl
+++ b/apps/emqx_authn/src/simple_authn/emqx_authn_mnesia.erl
@@ -80,7 +80,7 @@ mnesia(boot) ->
 %% Hocon Schema
 %%------------------------------------------------------------------------------
 
-namespace() -> "authn-password_based-builtin_db".
+namespace() -> "authn-builtin_db".
 
 roots() -> [config].
 
diff --git a/apps/emqx_authn/src/simple_authn/emqx_authn_mongodb.erl b/apps/emqx_authn/src/simple_authn/emqx_authn_mongodb.erl
index 7b986e6f9..ce5d3d8ee 100644
--- a/apps/emqx_authn/src/simple_authn/emqx_authn_mongodb.erl
+++ b/apps/emqx_authn/src/simple_authn/emqx_authn_mongodb.erl
@@ -39,13 +39,11 @@
 %% Hocon Schema
 %%------------------------------------------------------------------------------
 
-namespace() -> "authn-password_based-mongodb".
+namespace() -> "authn-mongodb".
 
 roots() ->
-    [ {config, {union, [ hoconsc:mk(standalone)
-                       , hoconsc:mk('replica-set')
-                       , hoconsc:mk('sharded-cluster')
-                       ]}}
+    [ {config, hoconsc:mk(hoconsc:union(refs()),
+                          #{})}
     ].
 
 fields(standalone) ->
diff --git a/apps/emqx_authn/src/simple_authn/emqx_authn_mysql.erl b/apps/emqx_authn/src/simple_authn/emqx_authn_mysql.erl
index cd658e6f1..9df50cf8f 100644
--- a/apps/emqx_authn/src/simple_authn/emqx_authn_mysql.erl
+++ b/apps/emqx_authn/src/simple_authn/emqx_authn_mysql.erl
@@ -39,7 +39,7 @@
 %% Hocon Schema
 %%------------------------------------------------------------------------------
 
-namespace() -> "authn-password_based-mysql".
+namespace() -> "authn-mysql".
 
 roots() -> [config].
 
diff --git a/apps/emqx_authn/src/simple_authn/emqx_authn_pgsql.erl b/apps/emqx_authn/src/simple_authn/emqx_authn_pgsql.erl
index 5f1005e9f..4086f4b22 100644
--- a/apps/emqx_authn/src/simple_authn/emqx_authn_pgsql.erl
+++ b/apps/emqx_authn/src/simple_authn/emqx_authn_pgsql.erl
@@ -40,7 +40,7 @@
 %% Hocon Schema
 %%------------------------------------------------------------------------------
 
-namespace() -> "authn-password_based-postgresql".
+namespace() -> "authn-postgresql".
 
 roots() -> [config].
 
diff --git a/apps/emqx_authn/src/simple_authn/emqx_authn_redis.erl b/apps/emqx_authn/src/simple_authn/emqx_authn_redis.erl
index cb04b0274..3ae333d12 100644
--- a/apps/emqx_authn/src/simple_authn/emqx_authn_redis.erl
+++ b/apps/emqx_authn/src/simple_authn/emqx_authn_redis.erl
@@ -39,13 +39,11 @@
 %% Hocon Schema
 %%------------------------------------------------------------------------------
 
-namespace() -> "authn-password_based-redis".
+namespace() -> "authn-redis".
 
 roots() ->
-    [ {config, {union, [ hoconsc:mk(standalone)
-                       , hoconsc:mk(cluster)
-                       , hoconsc:mk(sentinel)
-                       ]}}
+    [ {config, hoconsc:mk(hoconsc:union(refs()),
+                          #{})}
     ].
 
 fields(standalone) ->
diff --git a/apps/emqx_machine/src/emqx_machine_schema.erl b/apps/emqx_machine/src/emqx_machine_schema.erl
index ee317d1bf..a67b0ceeb 100644
--- a/apps/emqx_machine/src/emqx_machine_schema.erl
+++ b/apps/emqx_machine/src/emqx_machine_schema.erl
@@ -45,6 +45,7 @@
         [ emqx_bridge_schema
         , emqx_retainer_schema
         , emqx_statsd_schema
+        , emqx_authn_schema
         , emqx_authz_schema
         , emqx_auto_subscribe_schema
         , emqx_modules_schema