Merge pull request #125 from emqx/0129-provide-authn-authz-examples

feat: provide examples for authn and authz

.github/workflows/erlang.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
 
     container:
-      image: ghcr.io/emqx/emqx-builder/5.0-14:1.13.3-24.2.1-1-ubuntu20.04
+      image: ghcr.io/emqx/emqx-builder/5.3-2:1.15.7-26.2.1-2-ubuntu22.04
 
     steps:
     - uses: actions/checkout@v2

.github/workflows/release.yml

@@ -8,7 +8,7 @@ jobs:
   build_release:
     runs-on: ubuntu-latest
     container:
-      image: "ghcr.io/emqx/emqx-builder/5.0-14:1.13.3-24.2.1-1-ubuntu20.04"
+      image: ghcr.io/emqx/emqx-builder/5.3-2:1.15.7-26.2.1-2-ubuntu22.04
     steps:
       - uses: actions/checkout@v2
         with:

emqx-plugin.template

@@ -3,7 +3,7 @@
     {description, "Another amazing EMQX plugin."},
     {version, "1.0.0", "The release version of this plugin."},
     {app_vsn, "0.1.0", "The erlang application vsn value."},
-    {emqx_vsn, "v5.1.4", "EMQX version to use as a dependency."},
+    {emqx_vsn, "v5.4.1", "EMQX version to use as a dependency."},
     {license, "Apache-2.0", "Short identifier for license you want to distribute this plugin under."},
     {author_website, "http://example.com", "A website with details about the author."},
     {repo, "https://github.com/emqx/emqx-plugin-template", "Where to find the source code for this plugin."}

src/emqx_plugin_template.erl

@@ -93,18 +93,33 @@ on_client_connected(ClientInfo = #{clientid := ClientId}, ConnInfo, _Env) ->
               [ClientId, ClientInfo, ConnInfo]).
 
 on_client_disconnected(ClientInfo = #{clientid := ClientId}, ReasonCode, ConnInfo, _Env) ->
-  io:format("Client(~s) disconnected due to ~p, ClientInfo:~n~p~n, ConnInfo:~n~p~n",
+    io:format("Client(~s) disconnected due to ~p, ClientInfo:~n~p~n, ConnInfo:~n~p~n",
               [ClientId, ReasonCode, ClientInfo, ConnInfo]).
 
-on_client_authenticate(ClientInfo = #{clientid := ClientId}, Result, Env) ->
-  io:format("Client(~s) authenticate, ClientInfo:~n~p~n, Result:~p,~nEnv:~p~n",
-    [ClientId, ClientInfo, Result, Env]),
-  {ok, Result}.
-
-on_client_authorize(ClientInfo = #{clientid := ClientId}, PubSub, Topic, Result, Env) ->
-  io:format("Client(~s) authorize, ClientInfo:~n~p~n, ~p to topic(~s) Result:~p,~nEnv:~p~n",
-    [ClientId, ClientInfo, PubSub, Topic, Result, Env]),
-  {ok, Result}.
+%% @doc
+%% - Return `{stop, ok}' if this client is to be allowed to login.
+%% - Return `{stop, {error, not_authorized}}' if this client is not allowed to login.
+%% - Return `ignore' if this client is to be authenticated by other plugins
+%% or EMQX's built-in authenticators.
+on_client_authenticate(ClientInfo = #{clientid := ClientId}, DefaultResult, Env) ->
+    io:format("Client(~s) authenticate, ClientInfo:~n~p~n"
+              "DefaultResult:~p~n"
+              "Env:~p~n",
+              [ClientId, ClientInfo, DefaultResult, Env]),
+    DefaultResult.
+
+%% @doc
+%% - Return `{stop, #{result => Result}}' where `Result' is either `allow' or `deny'.
+%% - Return `ignore' if this client is to be authorized by other plugins or
+%% EMQX's built-in authorization sources.
+on_client_authorize(ClientInfo = #{clientid := ClientId}, PubSub, Topic, DefaultResult, Env) ->
+    io:format("Client(~s) authorize, ClientInfo:~n~p~n"
+              "~p to topic (~p) DefaultResult:~p~n"
+              "Env:~p~n",
+              [ClientId, ClientInfo, PubSub, Topic, DefaultResult, Env]),
+    %% `from' is for logging
+    Result = #{result => allow, from => ?MODULE},
+    {stop, Result}.
 
 on_client_subscribe(#{clientid := ClientId}, _Properties, TopicFilters, _Env) ->
     io:format("Client(~s) will subscribe: ~p~n", [ClientId, TopicFilters]),