mod_authz_internal

Usage

mod_authz_internal provides roles that determine access to certain functions based on internal information sourced from the config file and stored account information.

For a full overview of roles and permissions in Prosody, reade the Roles and Permissions documentation page.

This page details the configuration options provided by mod_authz_internal, which is Prosody’s default authorization provider.

Configuration

-- Select authorization provider
authorization = "internal"

admins = {
    "admin@example.org",
    "other-admin@example.org",
}

default_user_role = "prosody:registered"
host_user_role = "prosody:registered"
server_user_role = nil
public_user_role = nil

custom_roles = {}
add_permissions = {}
remove_permissions = {}

Role defaults

On VirtualHosts

default_user_role specifies the role assigned to users who don’t have a role set in storage. Defaults to "prosody:guest" when anonymous authentication is used. Defaults to "prosody:registered" on hosts with other authentication configured.

On Components

host_user_role determines the role assigned to users from the parent host of Components. Defaults to "prosody:registered". The default “parent host” is calculated by removing the leftmost label from the component’s own domain (for example, the default parent of foo.example.com is example.com). You can configure the parent host explicitly in Prosody using the parent_host option.

server_user_role determines the role assigned to users from hosts from the same Prosody instance, other than the parent domain. Defaults to "prosody:guest".

public_user_role determines the role assigned to users from hosts not covered by the above settings, including remote servers. Defaults to "prosody:guest".

For more information on how roles on components are handled, see the roles scope section of the configuration.

Custom permissions

You can customize the permissions granted to each role using the add_permissions and remove_permissions options:

add_permissions = {
    ["prosody:registered"] = {
        "mod_announce:send-announcement";
    };
}
remove_permissions = {
    ["prosody:registered"] = {
        "";
    };
}

Like roles themselves, permission modifications are scoped to the host you configure them on. If you add a permission to prosody:admin on example.com, the permission won’t be added to prosody:admin on example.net, even if they are in the same Prosody server.

Of course, if you set add_permissions or remove_permissions in the global section of your configuration, they will be applied to all hosts and components by default (unless overridden).

Custom Roles

Custom role definitions are declared with the custom_roles setting.

Example:

custom_roles = {
    -- a list of custom roles
    {
        -- properties
        name = "my-custom-role";
        priority = 20;
        inherits = { "proosdy:registered" };
    };
    {
        -- properties
        name = "my-other-custom-role";
        priority = 25;
        inherits = { "my-custom-role" };
    };
    -- and so on
}