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: built-in and custom users. Built-in 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).
Built-in users
The first example of built-in 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 built-in 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 records, 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 to the recorded calls, as well as grant other users "privacy" permissions, which gives them access to full numbers in CDR and to the list of recorded calls and the corresponding 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 required access permissions. N.B.: 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 user with limited privileges |
Multi-tenant
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 telephone 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 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 usernames of 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 local, 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 permissions for 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 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.