# Enhanced Auth ## Custom Auth Plugin We introduced a new plugin that adds to the current capabilities of VerneMQ. These include a JWT based authentication and an ACL validator that takes inspiration from ACL auth provided by the core project. ``` plugins.vmq_gojek_auth = on ``` ## Authentication You have the option of configuring jwt based authentication for clients. You need to connect with a password that can be verified with the `secret_key`. The plugin matches the value of the `rid` key against the username to verify if this is an authentic user. ``` vmq_gojek_auth.enable_jwt_auth = true vmq_gojek_auth.secret_key = some_cool_secret ``` ## Authorization ACL based authorization mechanism is also provided that extends the current scope: VerneMQ periodically checks the specified ACL file. ``` vmq_gojek_auth.enable_acl_hooks = true ``` The check interval defaults to 10 seconds and can also be defined in the `vernemq.conf`. ``` vmq_gojek_auth.acl_reload_interval = 10 vmq_gojek_auth.acl_file = ./etc/vmq.acl ``` Setting the `acl_reload_interval = 0` disables automatic reloading. {% hint style="info" %} Both configuration parameters can also be changed at runtime using the `vmq-admin` script. {% endhint %} ### Managing the ACL entries Topic access is added with lines of the format: ``` topic [read|write] [label ] ``` {% hint style="info" %} Only one space should be put between the topic and the preceeding keyword. Extra spaces will be interpreted as part of the topic! Also note that the ACL parser doesn't accept empty lines between entries. {% endhint %} The access type is controlled using `read` or `write`. If not provided then read an write access is granted for the `topic`. The `topic` can use the MQTT subscription wildcards `+` or `#`. To make it easier to identify ACL entries, we can assign a name to them by adding a value after the `label` keyword. This label will be mapped with the topic and referred to as `acl_name` during the ACL parsing. The `acl_name` is added following events hooks such as `on_subscribe`, `on_publish`, `on_deliver`, `on_delivery_complete`, and `on_message_drop`. This allows for better instrumentation and observability. If the `label ` is not provided to the entry, the ACL parser will map the `acl_name` as an empty value with the topic. The first set of topics are applied to all anonymous clients (assuming `allow_anonymous = on`). User specific ACLs are added after a user line as follows (this is the username not the client id): ``` user ``` It is also possible to define ACLs based on pattern substitution within the the topic. The form is the same as for the topic keyword, but using pattern as the keyword. ``` pattern [read|write] [label ] ``` The patterns available for substitution are: > * `%c` to match the client id of the client > * `%u` to match the username of the client The substitution pattern must be the only text for that level of hierarchy. Pattern ACLs apply to all users even if the **user** keyword has previously been given. This project extends these capabilities provided by vmq\_acl . It is possible to only match certain parts of client-id or username using token as the keyword. ``` token [read|write] [label ] ``` For example: > * `%(c, :, 3)` to match the 3rd token extracted from client id of the client after delimiting using `:`. > * `%(u, -, 2)` to match the 2nd token from username of the client after delimiting using `-`. The semantics are as follows: ``` %((username or client-id identifier), delimiter, token number) ``` ### Simple ACL Example ``` # ACL for anonymous clients topic bar label topic_bar topic write foo label topic_foo topic read open_to_all label open token read foo/%(u, :, 3)/bar label foo_client_bar # ACL for user 'john' user john topic foo label john_foo topic read bar label john_bar topic write open_to_all label john_open_to_all ``` Anonymous users are allowed to * publish & subscribe to topic bar and labelled as `topic_bar`. * publish to topic foo and labelled as `topic_foo`. * subscribe to topic open\_to\_all and labelled as `open`. * subscribe to topic foo/\/bar and labelled as `foo_client_bar`. User john is allowed to * publish & subscribe to topic foo and labelled as `john_foo`. * subscribe to topic bar and labelled as `john_bar`. * publish to topic open\_to\_all and labelled as `john_open_to_all`. Note that the ACL file parser is picky on a couple of things. If you doubt whether your ACLs are fully applied, check for the following. * Whitespaces at the end of topic names are part of the topic * Avoid empty lines in the ACL file. * But add a newline at the end of the ACL file. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://courier-gojek.gitbook.io/vernemq/configuring-vernemq/customauth.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.