This page describes the new flexible permission mechanism introduced in ejabberd 16.12.
Configuring permissions to API endpoints
Access to all available endpoints are configured using
It allows to define multiple groups, each one with separate list of filters on who and what are allowed by rules specified inside it.
Basic rule looks like this:
api_permissions: "admin access": - who: - admin - what - "*" - "!stop"
It tells that group named
Admin access allows all users that are accepted by
admin to execute all commands except command
Each group has associated name (that is just used in log messages),
for rules that authentication details must match,
what section for specifying
list of command, and
from with list of modules that API was delivered to.
There are 3 types of rules that can be placed in
- acl: Name|ACLDefinition or shortcut version
: It accepts command when authentication used to execute command matches
Name ACL (or inline rules from
- access: Name|AccessDefinition
: This will allow execution if access
Name or inline
allowed for command's authentication details
- oauth: ListOfRules
: This rule (and only this) will match for commands that were executed
with OAuth authentication. Inside ListOfRules you can use any rule
described above (
- acl: Name,
- access: Name) and
additionally you must include
-scope: ListOfScopeNames with OAuth
scope names that must match scope used to generate OAuth token used
in command authentication.
who section will allow command to be executed if at least one rule
included inside it will be successfully matched, if you need to have
ensure that multiple rules must be matched at this same time, you
need to use
- access rule for that.
who rule is equivalent to
- who: none which will stop group
from accepting any command.
This accepts user
firstname.lastname@example.org or commands originating
- who: - user: "email@example.com" - ip: "127.0.0.1/8"
This only allows execution of a command if it's invoked by user
firstname.lastname@example.org and comes from localhost address.
If one of those restrictions isn't satisfied, execution will fail:
- who: - access: - allow: - user: "email@example.com" - ip: "127.0.0.1/8"
Those rules match for users from
muc_admin ACL both using regular
authentication and OAuth (but only for tokens created with
- who: - muc_admin - oauth - scope: "can_muc_admin" - muc_admin
what section are constructed from
"strings" literals, you can
use name of existing commands like
can also use wildcard
"*" rule to match all commands, or you can use rule
"[tag:roster]" to allow all commands that have been declared with tag
Additionally each rule can be prepended with
! character to change
it into negative assertion rule. Command names that would match what is
! character will be removed from list of allowed commands.
what rule is equivalent to
- what: "!*" which will stop group
from accepting any command.
This allows execution of all commands except command
- what: - "*" - "!stop"
This allows execution of
status and commands with tag
- what: - "status" - "[tag:account]"
This matches no command:
- what: - "start" - "!*"
This section allows to specify list of allowed module names that expose API
to outside world. Currently those modules are
from section is missing from group then all endpoints are accepted,
if it's specified endpoint must be listed inside it to be allowed to execute.
Those rules allow execution of any command invoked
ejabberdctl shell command, or all command except
for users in ACL admin, with regular authentication or
scoped OAuth tokens.
api_permissions: "console commands": from: - ejabberd_ctl who: all what: "*" "admin access": who: - admin - oauth: - scope: "ejabberd:admin" - admin what: - "*" - "!stop" - "!start"