API Permissions

added in 16.12

This page describes ejabberd's flexible permission mechanism.

Access to all available endpoints are configured using the api_permissions top-level option.

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 ACL rule admin to execute all commands except command stop, using the command-line tool ejabberdctl or sending a ReST query handled by mod_http_api.

Each group has associated name (that is just used in log messages), who section 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.

Rules inside who section

There are 3 types of rules that can be placed in who section:

• acl: Name | ACLDefinition
  or the short version:
  Name | ACLRule
  This accepts a command when the authentication provided matches rules of Name Access Control List (or inline rules from ACLDefinition or ACLRule)

• access: Name | AccessDefinition
  This allows execution if the Access Rule Name or inline AccessDefinition returns 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, AClName, 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 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, use access (see examples below).

Missing who rule is equivalent to who: none which will stop group from accepting any command.

Examples of who rules

This accepts user admin@server.com or commands originating from localhost:

who:
  user: admin@server.com
  ip: 127.0.0.1/8

This only allows execution of a command if it's invoked by user admin@server.com and comes from localhost address. If one of those restrictions isn't satisfied, execution will fail:

who:
  access:
    allow:
      user: admin@server.com
      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

Rules in what section

Rules in 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 after ! character will be removed from list of allowed commands.

Missing what rule is equivalent to what: "!*" which will stop group from accepting any command.

Example of what rules

This allows execution of all commands except command stop:

what:
  - "*"
  - "!stop"

This allows execution of status and commands with tag session (like num_resources or status_list):

what:
  - status
  - "[tag:account]"

This matches no command:

what:
  - start
  - "!*"

Rules in from section

This section allows to specify list of allowed module names that expose API to outside world. Currently those modules are ejabberd_xmlrpc, mod_http_api and ejabberd_ctl.

If 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.

Examples

Those rules allow execution of any command invoked by ejabberdctl shell command, or all command except start and stop for users in ACL admin, with regular authentication or ejabberd:admin 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"