Roles

Most accounts on a server need the same access as many others. Maintaining that access permission by permission on every account would be slow and error-prone. Roles solve this. A role is a named set of permissions, where each permission is an individual right that the server checks for an operation. An administrator defines a level of access once as a role, for example “help desk” or “domain administrator”, and assigns the role to as many accounts and groups as need it.

Roles can also include other roles. A role for help-desk staff can therefore consist of the User role plus a few management permissions, instead of repeating every permission of the User role.

Each role is a Role object (found in the WebUI under Management › Directory › Roles). It has these parts:

• A description, which is the role’s name
• The permissions it grants, in enabledPermissions
• The permissions it removes, in disabledPermissions
• The roles it includes, in roleIds

A permission disabled by a role is removed even if an included role grants it. Roles do not list their members. Instead, each account and group refers to the roles it uses.

Default roles

On first start, the server creates four roles and records them as defaults on the Authentication singleton (found in the WebUI under Settings › Authentication › General). The default role sets on that singleton decide which roles an account receives when it does not name its own:

Role	Purpose	Used by default in
User	Signing in and using every mail, calendar, contacts and file protocol, and managing one’s own credentials and settings	defaultUserRoleIds; also part of defaultAdminRoleIds and defaultTenantRoleIds
Group	The protocol permissions of a group account	defaultGroupRoleIds
Tenant Administrator	Managing the domains, accounts and related objects of a tenant (Enterprise)	defaultTenantRoleIds, together with User
System Administrator	Managing the whole server	defaultAdminRoleIds, together with User

Permissions lists the permissions in each role.

The default roles are ordinary Role objects, so they can be edited. A change applies to every account that uses the role. Because both administrator role sets include User, removing a permission from the User role also removes it from administrators.

Assigning roles

Each account selects its roles in its roles field. For a user account, the field takes one of three values, depending on whether the account should follow a default role set or have its own:

• User applies the roles in defaultUserRoleIds, by default the User role. New accounts receive this value.
• Admin applies the roles in defaultAdminRoleIds, by default the System Administrator and User roles. For an account that belongs to a tenant, it applies defaultTenantRoleIds instead, which makes the account an administrator of its tenant and nothing more.
• Custom applies the roles listed in roleIds.

The roles field of a group has two values: Default, which applies defaultGroupRoleIds, or Custom. The roles of a group govern what the group account itself may do, for example whether it may receive mail. They are not passed on to the group’s members.

Changing defaultUserRoleIds or another default role set changes the roles of every account that uses the corresponding value. These fields are read when the settings are loaded, so a change applies only after a ReloadSettings action. Even then, accounts that have been used since the last restart keep their previous permissions, because the server caches them. They pick up the change once an InvalidateCaches action clears the cached permissions, or when the server restarts. Changes to the Role objects themselves need neither action.

Create a custom role

A custom role combines existing roles with additional permissions. The following role gives help-desk staff the User permissions plus the ability to look up accounts and reset passwords:

{
  "description": "Help desk",
  "roleIds": {"<id of the User role>": true},
  "enabledPermissions": {
    "sysAccountGet": true,
    "sysAccountQuery": true,
    "sysAccountUpdate": true,
    "sysDomainGet": true,
    "sysDomainQuery": true
  }
}

An account receives the role through its roles field:

{
  "roles": {"@type": "Custom", "roleIds": {"<id of the role>": true}}
}

The role does not let its holders manage every account. An account can change only accounts whose permissions it holds itself (Granting permissions to other accounts). Help-desk staff with this role can therefore reset the passwords of ordinary users, but not of administrators.

In the Enterprise edition, a role can belong to a tenant through memberTenantId. Tenant administrators create such roles for their own accounts, and these roles count against the tenant’s maxRoles quota.

Propagation of changes

Changes to access take effect without a new sign-in. A change to a Role, or to an account’s roles, permissions, group memberships, tenant or credentials, applies to every affected account at its next HTTP request. This includes accounts that receive the role through another role or, in the Enterprise edition, through their tenant. Open IMAP and POP3 sessions pick up the change shortly after. OAuth access tokens follow the change as well, so applications do not have to sign in again.

A cluster without a coordinator is the exception. There, the change reaches at once only the node that processed it. On the other nodes, sign-ins with a password or app password see the change. Requests with OAuth tokens or API keys, and changes to the permissions inside a role, keep the previous permissions until the cached entry is evicted or the node restarts.