This page describes the new flexible permission mechanism introduced in ejabberd 16.12.
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" from: - ejabberd_ctl - mod_http_api
It tells that group named
Admin access allows all users that are accepted by
admin to execute all commands except command
stop, using the command-line tool
ejabberdctl or sending a ReST query handled by
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 the short version:
Name | ACLRule
This accepts a command when the authentication provided matches rules of
NameAccess Control List (or inline rules from
access: Name | AccessDefinition
This allows execution if the Access Rule
allowedfor command's authentication details
This rule (and only this) will match for commands that were executed with OAuth authentication. Inside ListOfRules you can use any rule described above (
access: Name) and additionally you must include
scope: ListOfScopeNameswith OAuth scope names that must match scope used to generate OAuth token used in command authentication.
who allows the command to be executed if at least one rule matches.
If you want to require several rules to match at this same time,
access (see examples below).
who rule is equivalent to
who: none which will stop group
from accepting any command.
This accepts user
email@example.com or commands originating
who: user: firstname.lastname@example.org ip: 127.0.0.1/8
This only allows execution of a command if it's invoked by user
email@example.com and comes from localhost address.
If one of those restrictions isn't satisfied, execution will fail:
who: access: allow: user: firstname.lastname@example.org ip: 127.0.0.1/8
Those rules match for users from
muc_admin ACL both using regular
authentication and OAuth):
who: access: allow: acl: muc_admin oauth: scope: "ejabberd:admin" access: allow: acl: muc_admin
what section are constructed from
"strings" literals. You can use:
- "command_name" of an existing API command
- command_name is same as before, but no need to provide
- "*" is a wildcard rule to match all commands
- "[tag: tagname ]" allows all commands that have been declared with tag
tagname. You can consult the list of tags and their commands with:
ejabberdctl help tags
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: access: allow: - acl: admin oauth: scope: "ejabberd:admin" access: allow: - acl: admin what: - "*" - "!stop" - "!start"