Roles and permissions

Note: This documentation applies to Prosody 13.0 and higher, where the new roles and permissions framework was introduced.

Overview

Prosody has a flexible roles and permissions system, which allows you to customize who may perform which actions.

Authorization providers

By default Prosody uses its internal provider (mod_authz_internal) to determine which roles a user has, and which permissions a role has. Although Prosody’s default provider is very configurable and should suffice for most deployments, it is also possible to develop custom authorization provider plugins, e.g. to pull role information from external sources.

Name	Description
mod_authz_internal	Prosody’s built-in provider

The rest of the documentation here may not apply if you are using a different provider.

Built-in roles

Prosody has a number of built-in roles, which should be all you need in most cases:

Role	Description
prosody:operator	Highest privileges, allows actions affecting the entire Prosody instance.
prosody:admin	Administrative control over a particular domain (i.e. VirtualHost/Component).
prosody:member	A normal member of the domain.
prosody:registered	Default role for accounts created via in-band registration.
prosody:guest	Anonymous, guest or remote users

Automatic role assignment

Most deployments do not need to worry about managing roles manually. Prosody will automatically assign sensible roles by default:

prosody:operator: This role is applied to accounts which are listed in the ‘admins’ list in the global section of the configuration.
prosody:admin: Similarly, applied to accounts which are listed as admins under a specific VirtualHost or Component only.
prosody:member: The default role for accounts created by the admin or via an invitation link.
prosody:registered: If the server has open in-band registration, new accounts will be assigned this role by default.
prosody:guest: This role is used in most other circumstances, e.g. for anonymous logins or remote JIDs.

Note: If a JID is listed in the ‘admins’ option in the configuration file, this will override anything else (e.g. using the ‘user:set_role’ shell command will have no observable effect).

Manual role assignment

It is possible to change the role of an account, e.g. using prosodyctl shell:

prosodyctl shell user set_role user@example.com prosody:member

You can view the current role with:

prosodyctl shell user role user@example.com

Permissions

Each permission in Prosody is identified by a string, for example ‘mod_muc:list-rooms’. By default each permission is already assigned to built-in roles in order to provide sensible defaults without any additional configuration.

In some cases you may wish to override the default permissions belonging to a role. See the mod_authz_internal documentation for details.

Developers

Plugin developers can easily hook into the roles and permissions system. See our developer docs on permissions for more information.