Customising Access Control

This page deals with methods to customise Access Control with Tags

It consist of reference documentation on related config.json keys, as well as a guide to rolling your own access control sytem from scratch - this is considered an advanced topic and some advanced planning and thought is most definitely required.

Table of Contents Configuration Keys commands_admin commands_tagged commands_user commands.tags.deny-prefix commands.tags.escalate plugins.tags.auto-register Rolling your own Access Control Example Recipes

Configuration Keys

This section list all config.json keys that are related to Access Control with Tags

commands_admin

Makes listed commands admin-only, ignoring plugin settings

This key is supported as a per-conversation setting

In the following example, ping and echo are originally user-level commands which have been made admin-only, and whereami remains unchanged as an admin-level command:

"commands_admin": ["ping", "echo", "whereami"]

Setting this key to "commands_admin": true makes ALL loaded commands admin-only

commands_tagged

Add additional custom tags to commands. This key is not set by default.

This key is supported as a per-conversation setting

General format is a {dictionary} with command names as keys and tag list as corresponding values:

"commands_tagged": {
  "whereami" : [
    "group-a",
    "group-b",
    "xyz"
  ]
}

# matches ANY tag: "group-a", "group-b" OR "xyz"

Also supports matching ALL tags:

"commands_tagged": {
  "version" : [
    [ "group-a", "group-b" ],
    "xyz"
  ]
}

# must match BOTH "group-a" AND "group-b", OR "xyz"

If plugins.tags.auto-register is activated, preset tags will be combined with any other tags specified in this key.

Note: Tags registered via this key will show up in /bot tagscommand <command name> but not in /bot plugininfo

commands_user

Makes listed commands available to users and all other unlisted commands admin-only, ignoring plugins settings

This key is supported as a per-conversation setting

In the following example, only help, whoami, whereami and optout will be commands available to users:

"commands_user": ["help", "whoami", "whereami", "optout"]

Setting this key to "commands_user": true makes ALL loaded commands available to ALL users - except if "commands_admin": true - the latter has higher priority

commands.tags.deny-prefix

Modifies the prefix used for denying access to a tagged command

Default (when not set) is !

commands.tags.escalate

Changes the behaviour of how the bot handles tagged commands. Default (when not set) is boolean false, which maintains the original access level of the tagged command. Therefore, a user-level command will remain generally available to all users regardless of whether its been tagged or not.

Setting this key to "commands.tags.escalate": true will make the bot raise (i.e. "escalate") the access level of any tagged command to admin-level. Thus, any user-level command that is tagged will automatically becomes available only to admins and users with the appropriate tags.

plugins.tags.auto-register

Automatically registers preset tags for all loaded commands. The default value for this setting when not set is boolean true, which will auto-tag all loaded commands with the following preset tag patterns:

• {plugin}-{command}
• {plugin}-{type}

Thus, user commands such as ping will be auto-tagged basic-ping and basic-user; whereas admin commands such as leave will be auto-tagged default-leave and default-admin

The tag patterns can be overridden by specifying a list of tag patterns for plugins.tags.auto-register:

"plugins.tags.auto-register": [ 
  "execute-{plugin}-{type}-{command}", 
  "all-{type}", 
  "everything" 
]

In the above example ping would receive 3 preset tags: execute-basic-user-ping, all-user and everything

Supported named presets are as follow:

• {plugin} - the current plugin being loaded
• {command} - the actual command name
• {type} - the command type (user or admin)

Setting "plugins.tags.auto-register": false will prevent auto-registration of any presets.

CAUTION: The default setting with "commands.tags.escalate": true will make all commands accessible only to admins and users with the appropriate tags.

Rolling your own Access Control

Here is a step-by-step guide:

1. Determine your base access-levels with either commands_admin or commands_users (note: treat these keys as mutually exclusive):
   • "commands_admin": true makes all commands admin-only (very restrictive)
   • "commands_user": true makes all commands available to all users (very permissive)
   • "commands_user": [ <commands list> ] makes listed commands available to all users (whitelist)
   • "commands_admin": [ <commands list> ] makes listed commands admin-only (blacklist)
   • leaving both unset will use plugin-determined access levels for commands (default)
2. With plugins.tags.auto-register, determine whether you want to use system presets, or roll your own access control from a blank slate:
   • Leaving plugins.tags.auto-register as the default (unset) or "plugins.tags.auto-register": true will automatically register a unique tag for every command - these tags will be combined with any tags that you set in commands_tagged (with preset tags)
   • "plugins.tags.auto-register": false will require you to define own tags in commands_tagged (custom tags)
3. Use commands.tags.escalate to determine how the bot will treat tagged commands:
   • "commands.tags.escalate": true will make tagged user commands available only to admins and users with the correct set of matching tags (conservative tagging) - setting is suitable for maintaining restrictive control over tagged commands (since any tagged command is automatically promoted to admin-level access)

     CAUTION: Using this together with plugins.tags.auto-register unset or "plugins.tags.auto-register": true will cause every command to be promoted to admin-level, thus barring untagged users from accessing any command whatsoever unless explicitly granted access.

   • "commands.tags.escalate": false or unset will leave user commands still available to untagged users (flexible tagging) - this setting is suitable if you prefer users having closer to default access for most user-level commands and intend to only selectively block/ban a small portion of users from using some commands with "deny tags"
4. Use commands_tagged to assign specific tags to desired commands:
   • "commands_tagged": [ <command list> ] allows you to assign tags to user and admin commands

     Reminder: Assigning tags for a user command when "commands.tags.escalate": true will automatically convert the user command into an admin command

Example Recipes

Available as a discussion page