Skip to content

Access Control with Tags

Jump to bottom Edit New page
Innocent Bystander edited this page Aug 26, 2015 · 18 revisions

This section details getting started with access control with the new User & Conversation Tagging feature officially introduced in bot version 2.7 and above.

Basic tagging commands are also outlined in the aforementioned article

A read-through of this page is strongly recommended if you are new to the concept of tagging.

Once you are thoroughly familiar with the basics and desire to fully customise the access control system, a proper reference for altering the behaviour of the bot via config.json keys is available, along with a step-by-step guide on things you need to consider

Plugin Developers: The article on Plugin Authoring has been updated with instructions to add tag support to your plugins via the Modern Pattern or Modern-Alternate Pattern

Table of Contents

Basic Access Control

Commands and users can be tagged - allowing bot administrators to grant/block access to specific commands.

Bot administrators are not subject to tag-based access control, as they will always bypass any tag checks.

default configuration

With the default bot configuration, commands are automatically assigned preset tags, which can be immediately used to grant user access to admin-level commands or block user access to user-level commands.

Hint: You can list all tags that are attached to a command with /bot tagscommand <command name>. /bot plugininfo from Basic Commands is also capable of listing tagged commands on a per-plugin basis, but does not include tags that might have been registered via config["commands_tagged"]

With the default configuration, there is still a difference between user and admin commands that are automatically registered by loaded plugins. As before, user commands can be run by any user, and admin commands can only be executed by bot administrators. Now with the default tagging configuration, you can also:

  • Block specific users from running specific user commands
  • Grant specific users access to specific admin commands

This is made possible because the default configuration automatically registers preset tags for all loaded commands. The preset tags will be of the following pattern: <plugin name>-<command name> and <plugin name>-<command access level>. Thus, the user-level ping command would be auto-tagged as basic-ping and basic-user; whereas the admin-level rename command in the default plugin would be auto-tagged: default-rename and default-admin

To learn more about modifying the default preset patterns or switching it off entirely, please see plugins.tags.auto-register

granting/removing user access

To grant access to a set of tagged commands, tag users with the matching tag(s): 

/bot tagset user <user id> default-rename

# grants access to admin-level /bot rename

/bot tagset user <user id> default-admin

# grants access to all admin-level commands in default plugin

To remove user access that was granted from previous tagging: 

/bot tagdel user <user id> default-rename

# removes tag "default-rename" from <code><user id</code>
# the tag and user must exist for this to work

/bot tagdel user <user id> default-admin

# removes tag "default-admin" from <user id>
# the tag and user must exist for this to work

Other advanced grant/block methods are detailed in the section:

Command Reference: Basic Tag Manipulation

Other Common Access Control Tasks

This section outlines several common tasks that bot administrators and/or plugin developers might need to perform.

Note: A full reading of the reference documentation for User and Conversation Tagging is recommended.

reviewing user access and tags

To review tags which are assigned to users, you can use /bot tagsuser; /bot tagsuserlist; and even the impersonate sub-command with /bot help impersonate

adding tags to commands

You can add extra tags to commands by using the commands_tagged key in config.json

These tags will be combined with the existing preset tags if plugins.tags.auto-register is activated.

Plugin developers can also use the new optional tags parameter in the Modern Pattern or Modern-Alternate Pattern to register tags during plugin initialisation.

listing tagged commands

To see which tags are available for commands, you can use /bot tagscommand <command name>; and /bot plugininfo - note that the former has more complete output than the latter, which is more useful for plugin developers

grant/block per-conversation

Note: Tags assigned to users are prioritised based on their specificity: per-conversation user tags override any global tags. Please see the reference article on Tagging Users

You can grant a per-conversation user tag: 

/bot tagset convuser <conv id>|<user id> default-rename

To remove a per-conversation user tag: 

/bot tagdel convuser <conv id>|<user id> default-rename
Command Reference: Basic Tag Manipulation

match all tags instead of any tag

use a sublist inside the commands_tagged key for matching ALL specified tags e.g. 

"commands_tagged": {
  "version" :
  [ 
    "run-version", 
    [ "run-version-part-1", "run-version-part-2" ]
  ]
}

users who can run /bot version
* admins (always override tags)
* users tagged "run-version"
* users tagged "run-version-part-1" AND "run-version-part-2"

explicit command denial

Deny access to tagged commands by prefixing the tag with ! e.g. !run-version.

Deny has the highest priority, and will always override any other grants. The prefix can be changed by specifying it a new character in the config.json key: commands.tags.deny-prefix

You cannot deny commands for admins, as configured admins always bypass this setting.

  • obeys ANY-ALL matching
  • this feature allows you to assign group/role-like tags (for multiple commands) and still individually deny access to certain commands for some specific users under a group e.g.
commands_tagged: {
  "whereami": [ "run-whereami", "poweruser" ],
  "version": [ "run-version", "poweruser" ]
}

/bot tagset user 001 poweruser
/bot tagset user 002 poweruser
/bot tagset user 002 !run-whereami

user 001 can execute: /bot whereami and /bot version
user 002 can execute: /bot version
Command Reference: Basic Tag Manipulation

remove multiple tags at once (purge)

Please see batch tags removal

Advanced Topics

fully-customised access control

There is a step-by-step guide on what you need to do. Familiarity with the tag system is recommended.

plugin development

The article on Plugin Authoring has been updated to reflect tools that can be used to add tag support to your plugins utilising the Modern Pattern or Modern-Alternate Pattern

Plugin List | Developer Reference: [ Intro | Plugins | Sinks | In-built Functionality | [Configuration] (Configuration) ]

# ## ###

Clone this wiki locally