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.

Role scope

As with most things in Prosody, roles are scoped to a specific “host” (i.e. a VirtualHost or a Component defined in the config file). This means that if you set the role prosody:admin for the account user@example.com they will have this role only in the context of example.com. If the same Prosody server also hosts jabber.example, they won’t have any prosody:admin permissions on that host.

Components

In Prosody, Components are top-level entities and they do not inherently “belong” to any VirtualHost. For convenience, however, Prosody does copy over certain configuration (such as certificates) if a component is a direct subdomain of VirtualHost (e.g. share.example.com is a direct subdomain of example.com, but share.foo.example.com is not).

Components do not directly have access to the role information of users in Prosody. Granting someone prosody:admin on example.com does not give them this role on share.example.com. All users on a “parent host” will have the prosody:registered role by default on a component. You can change which host is considered the parent host using the parent_host option under the component.

If you need to change any of this behaviour, there are two main approaches to customize user roles within components:

Use the built-in configuration options host_user_role, server_user_role and public_user_role from mod_authz_internal to control which roles the component assigns to users by default.
Use the community module mod_authz_delegate to configure a component to pull role information from another host (which must be on the same Prosody instance).

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.