AdminGuide:BasicConcepts:Users and roles

Return to AdminGuide:BasicConcepts

Users

Access to KalliopePBX GUI (as well as CTI services, LDAP phonebook, etc.) is granted to users. There are two kinds of users: builtin and custom users. Builtin users include administrative and service users, whose roles are usually predefined and not modifiable, whereas custom users are additional users that can be created and assigned to custom roles.

Each user has one or more associated access permissions among GUI, CTI, and API.

• GUI: GUI access means that the user can log into the KalliopePBX web interface; GUI access also grants the user permission to access the integrated LDAP server.
• CTI: CTI access allows the users to use Kalliope applications (CTI, Logger, Supervisor Panel) which connect to the PBX using the CTI socket and protocol.
• API: API access allows the users to invoke the KalliopePBX REST APIs available at http[s]://<PBX IP>/rest/ (see REST API).

Builtin users

The first example of builtin user is admin (whose default password is "admin"), used to access the GUI after the first firmware installation. This is the primary technical figure, and is commonly used to perform the system configuration. Additional users may have the rights to perform configuration tasks, but they can be limited to specific GUI panels only, according to their granted Role.

The following table lists the builtin users along with their access permissions. (Note: (+) means that this access permission is assigned and cannot be revoked; (-) means that the permission can be granted or not.)

Username	Access permissions	Notes
admin	GUI (+) CTI (+) API (+)	This is the main technical user. They have full privileges on PBX configuration both for system (network, network services) and telephony (entities, services, etc.). They have full access to logs and registers, but they have some limitations regarding aspects related to the privacy of the users. Firstly, they cannot see the external telephone numbers in the CDR in full, but are only able to view them with last three digits replaced by "xxx"; secondly, the "admin" user does not have access to Call Recording configuration and files, which is limited to "privacyadmin" user (and delegated users).
privacyadmin	GUI (-) API (-)	This user has full access to the external telephone numbers of the CDR, and is the only one who can configure call recording authorization. They can also access call recording records, download and listen the recorded calls, as well as grant other users with the "privacy" permission, which grants another user access to full numbers in CDR and to list of recorded calls (and files).
phonebook	GUI (-) API (-)	This user has read access to the KalliopePBX phonebook. It has to be explicitly enabled from the "System Settings" -> "Users Management" panel, assigning it a password and the related access permissions. NOTE: GUI permission also grants the right to access the integrated LDAP server, where the KalliopePBX phonebook is published (according to the settings in "Phonebook"->"LDAP Settings" panel). The "phonebook" user is mainly useful to have a single identity (configurable through provisioning) used by telephones to access the KalliopePBX phonebook using LDAP.
click2call	GUI (-) API (-)	This user is useful when using third party applications to send click-to-call commands (using the REST API /rest/phoneServices/c2c/{dest_exten}/{source_exten}) to KalliopePBX using a single authentication user with limited privileges

Multitenant

During Multitenant license activation, the PBX and the tenant entities, which were bundled under a single administration entity, are separated and a new builtin user pbxadmin is created (with default password "admin").

Management of the PBX as a system is granted to the new "pbxadmin" user, who has both GUI and CTI permissions, whereas the "admin" user retains control of the telephony service configuration for the tenant. Since multiple tenants can be created, each with its own "admin", it is necessary to extend the username to specify the relevant tenant domain. The predefined existing tenant domain is "default", so the predefined builtin users become admin@default, privacyadmin@default, etc.

For each new tenant that gets created (e.g. with domain "sampledomain"), a number of new users are generated, namely admin@sampledomain, privacyadmin@sampledomain, phonebook@sampledomain, and so on.

The admin@default and admin@sampledomain users are completely independent and each one can only manage their own tenant.

N.B.: if a user does not specify the domain when logging in (e.g. uses "admin" instead of "admin@somedomain"), then it is assumed to belong to the default domain and authentication is performed accordingly.

Custom users

Additional users can be created. Currently, custom users have to be associated to an Extension. Custom user can be created in the "Edit Extension" panel, defining a unique (within the tenant) username and assigning GUI, CTI and/or API access permissions. By default all custom users are created with the standard "Tenant User" role, but a different one can be selected among those available. As detailed below, roles are managed in the "System Settings" -> "Roles Management" panel, where different access permissions (none/list/read/write) can be assigned for each panel of the GUI, allowing the admin to delegate some configuration tasks to selected users.

Once created, custom users cannot be edited from the "Edit extension" panel, but they appear in the "System Settings" -> "Users Management" panel, along with the builtin ones.

User authentication

User authentication is performed with a password check, using one of the two available authentication methods.

The first method is "Local Authentication": the user password is handled by the PBX, and its hash is stored in the internal database for authentication. This is the only available authentication method for the "admin" user.

KalliopePBX can also authenticate users with external services; the supported external authentication services are Microsoft Active Directory and LDAP servers. External authentication services are defined on a per-tenant basis, so they need to handle authentication usernames in the form "user@tenant_domain".

Roles

Each user is assigned a role, which determines their permissions in terms of access to the various panels. Builtin users have builtin roles (currently not assignable to custom users) since their permissions are fixed.

Custom users by default have the "Tenant User" (or simply "User") role, which is builtin and not modifiable. This role grants the user the right to access their own CDR and the extensions (or local), the shared, and personal phonebooks.

Additional roles ("Power User" roles) can be created and assigned to the custom users. Each role has a priority attribute (an integer value between 1 and 99; standard users have priority 0, whereas tenant admin has 100) which is used to resolve contention of the Configuration Lock when multiple users need to perform configuration operations on the PBX. Users can acquire the Configuration Lock even if it is currently held by another user, provided that their role priority is higher than the one of the user currently holding the lock. Note that the action of acquiring the lock currently held by another user drops all the pending changes made by the first user.

Custom roles are configured by selecting the access level of each panel, among the values:

• "none": the user cannot access this panel and the navigation menu will not include the link to that panel (direct access to the panel URL is blocked too);
• "list": the user has read-only access to the panel which lists the related entities (e.g. the Extensions list) but cannot see the details of the single Extensions entries nor execute any action on those;
• "read": the user can access the list panel as well as the single entity entries, but in read-only mode;
• "write": user has full read-write access to the related entities.