Skip to content

Commit 3954f23

Browse files
jorikfonjorikfon
committed
docs: expand README with comprehensive module documentation
1 parent 3fccd10 commit 3954f23

File tree

2 files changed

+355
-22
lines changed

2 files changed

+355
-22
lines changed

‎README.md‎

Lines changed: 180 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,186 @@
1-
# MikoPBX users right management module
1+
# MikoPBX User Access Control Module
22

33
*Read this in other languages: [English](README.md), [Русский](readme.ru.md).*
44

5-
## Module description ##
5+
## Overview
66

7-
<figure><img src="https://github.com/mikopbx/docs.mikopbx.com/blob/english/.gitbook/assets/module-index-page.png" alt=""><figcaption><p>The module page for configuring access groups</p></figcaption></figure>
8-
The module helps to organize access to the UI with different rights.
9-
It makes possible to make multi-login access to the MikoPBX with separate permissions for each users group.
10-
The module also includes LDAP/AD login feature.
7+
**ModuleUsersUI** is a comprehensive access control module for MikoPBX that enables multi-user access with role-based permissions. It provides granular control over web interface sections, REST API endpoints, and call history visibility.
118

12-
## Instructions ##
13-
14-
The full module documentation you can find by [the link](https://docs.mikopbx.com/mikopbx/v/english/modules/miko/module-users-u-i).
9+
## Key Features
1510

16-
### Questions ###
17-
You are welcome to our telegram channel for developers [@mikopbx_dev](https://t.me/joinchat/AAPn5xSqZIpQnNnCAa3bBw)
11+
### Access Groups Management
12+
- **Role-Based Access Control (RBAC)**: Create unlimited access groups with specific permissions
13+
- **Full Access Mode**: Option to grant unrestricted access for administrator groups
14+
- **Custom Home Page**: Configure landing page after login for each group
15+
- **Granular Permissions**: Control access to individual interface sections and actions
16+
17+
### Authentication Methods
18+
- **Local Authentication**: Username/password stored in MikoPBX database
19+
- **LDAP/Active Directory**: Integration with corporate directory services
20+
- Support for OpenLDAP and Microsoft Active Directory
21+
- Configurable user filters and attribute mapping
22+
- Automatic user synchronization
23+
24+
### Permission Categories
25+
26+
#### Web Interface (AdminCabinet)
27+
Fine-grained control over MikoPBX admin panel sections:
28+
- **View**: Access to list and index pages
29+
- **Modify**: Ability to open and view record details
30+
- **Edit/Delete**: Create, update, and remove records
31+
32+
Supported sections include:
33+
- Employees and Extensions
34+
- Call Queues and Conference Rooms
35+
- IVR Menus and Dialplan Applications
36+
- Incoming/Outgoing Routes
37+
- Providers (SIP/IAX)
38+
- Sound Files
39+
- Call History (CDR)
40+
- System Settings
41+
- And more...
42+
43+
#### REST API Access
44+
Control which API endpoints users can access:
45+
- Standard CRUD operations (getList, getRecord, saveRecord, delete)
46+
- Custom actions per endpoint
47+
- Automatic linking between UI and API permissions
48+
49+
### Call History (CDR) Filtering
50+
Restrict call record visibility based on employee assignments:
51+
- **No Filter**: Show all call records
52+
- **Only Selected**: Show only calls involving specific employees
53+
- **Outgoing Only**: Show only outgoing calls from selected employees
54+
- **Except Selected**: Hide calls from specific employees
55+
56+
### User Profile Self-Service
57+
- Password change for local users
58+
- Passkey (WebAuthn) management for passwordless authentication
59+
60+
## Architecture
61+
62+
### Database Models
63+
| Model | Description |
64+
|-------|-------------|
65+
| `AccessGroups` | Access group definitions with permissions |
66+
| `AccessGroupsRights` | Granular permission assignments |
67+
| `AccessGroupCDRFilter` | CDR filter rules per group |
68+
| `UsersCredentials` | User authentication data |
69+
| `LdapConfig` | LDAP server configuration |
70+
71+
### Key Components
72+
- **UsersUIACL**: Core ACL modification logic integrating with MikoPBX
73+
- **UsersUIAuthenticator**: Handles local and LDAP authentication
74+
- **AutoLinkedActionsResolver**: Automatic UI↔API permission linking
75+
- **UsersUICDRFilter**: CDR visibility filtering
76+
77+
## Installation
78+
79+
1. Download module from MikoPBX Marketplace or GitHub Releases
80+
2. Upload via **Modules → Install Module** in MikoPBX admin panel
81+
3. Enable the module
82+
4. Configure access groups and assign users
83+
84+
## Requirements
85+
86+
- MikoPBX 2025.1.1 or higher
87+
- PHP 8.3+
88+
- Valid license (commercial module)
89+
90+
## Configuration
91+
92+
### Creating an Access Group
93+
94+
1. Navigate to **Modules → User Access Control**
95+
2. Click **Add New Access Group**
96+
3. Configure:
97+
- Group name and description
98+
- Full access toggle (for admin groups)
99+
- Home page after login
100+
- Interface permissions
101+
- REST API permissions
102+
- CDR filter settings
103+
104+
### Adding Users
105+
106+
1. Go to **Extensions** section
107+
2. Edit an employee
108+
3. In **MikoPBX Login** tab:
109+
- Enable login access
110+
- Set username and password
111+
- Select access group
112+
- Optionally enable LDAP authentication
113+
114+
### LDAP Configuration
115+
116+
1. Navigate to **LDAP Settings** tab in module
117+
2. Configure:
118+
- Server address and port
119+
- Admin credentials for directory queries
120+
- Base DN
121+
- User filter and attributes
122+
3. Test connection and user retrieval
123+
124+
## API Integration
125+
126+
The module automatically manages permissions for REST API v3 endpoints:
127+
128+
```
129+
GET /pbxcore/api/v3/{resource} → getList
130+
GET /pbxcore/api/v3/{resource}/{id} → getRecord
131+
POST /pbxcore/api/v3/{resource} → create
132+
PUT /pbxcore/api/v3/{resource}/{id} → update
133+
DELETE /pbxcore/api/v3/{resource}/{id} → delete
134+
```
135+
136+
## Development
137+
138+
### Running Tests
139+
140+
```bash
141+
# Unit tests (PHP)
142+
./vendor/bin/phpunit
143+
144+
# Integration tests (Python)
145+
cd Tests/Integration
146+
pip install -r requirements.txt
147+
cp .env.example .env
148+
# Configure .env with your MikoPBX instance
149+
pytest
150+
```
151+
152+
### Project Structure
153+
154+
```
155+
ModuleUsersUI/
156+
├── App/
157+
│ ├── Controllers/ # MVC Controllers
158+
│ ├── Forms/ # Phalcon Forms
159+
│ └── Views/ # Volt Templates
160+
├── Lib/
161+
│ ├── ACL/ # Access Control Logic
162+
│ └── *.php # Core Libraries
163+
├── Models/ # Phalcon ORM Models
164+
├── Messages/ # i18n Translations
165+
├── Setup/ # Installation Scripts
166+
├── Tests/ # Test Suites
167+
└── public/assets/ # Frontend Resources
168+
```
169+
170+
## Documentation
171+
172+
Full documentation available at:
173+
- English: [docs.mikopbx.com/modules/miko/module-users-u-i](https://docs.mikopbx.com/mikopbx/v/english/modules/miko/module-users-u-i)
174+
- Russian: [docs.mikopbx.com/modules/miko/module-users-u-i](https://docs.mikopbx.com/mikopbx/modules/miko/module-users-u-i)
175+
176+
## Support
177+
178+
- Telegram: [@mikopbx_dev](https://t.me/joinchat/AAPn5xSqZIpQnNnCAa3bBw)
179+
- Email: help@miko.ru
180+
- Issues: [GitHub Issues](https://github.com/mikopbx/ModuleUsersUI/issues)
181+
182+
## License
183+
184+
GPL-3.0-or-later - see [LICENSE](LICENSE) file for details.
185+
186+
Copyright © 2017-2025 MIKO LLC

‎readme.ru.md‎

Lines changed: 175 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,186 @@
11
# Модуль управления доступом к MikoPBX
22

3-
_Read this in other languages:_ [_English_](./)_,_ [_Русский_](readme.ru.md)_._
3+
*Read this in other languages: [English](README.md), [Русский](readme.ru.md).*
44

5-
## Описание модуля расширения ##
5+
## Обзор
66

7-
<figure><img src="https://github.com/mikopbx/docs.mikopbx.com/blob/russian/.gitbook/assets/All-groups-index.png" alt=""><figcaption><p>Страница модуля с настройкой групп доступа</p></figcaption></figure>
7+
**ModuleUsersUI** — комплексный модуль управления доступом для MikoPBX, обеспечивающий многопользовательский доступ с ролевыми разрешениями. Модуль предоставляет детальный контроль над разделами веб-интерфейса, REST API и видимостью истории звонков.
88

9-
Модуль позволяет организовать группы доступа с различными правами, а затем назначить эти группы конкретными пользователям системы.
10-
Также модуль позволяет выполнять авторизацию в системе используя LDAP/AD.
9+
## Основные возможности
1110

12-
Для страницы с историей разговоров реализован дополнительный фильтр по сотрудникам.
13-
Это позволяет запретить доступ к записям разговоров отдельных сотрудников для отдельных групп пользователей.
11+
### Управление группами доступа
12+
- **Ролевое управление доступом (RBAC)**: Создание неограниченного количества групп с определёнными правами
13+
- **Режим полного доступа**: Возможность предоставить неограниченный доступ для администраторов
14+
- **Настраиваемая домашняя страница**: Выбор страницы после входа для каждой группы
15+
- **Гранулярные разрешения**: Контроль доступа к отдельным разделам и действиям
1416

15-
## Документация ##
17+
### Методы аутентификации
18+
- **Локальная аутентификация**: Логин/пароль хранятся в базе MikoPBX
19+
- **LDAP/Active Directory**: Интеграция с корпоративными каталогами
20+
- Поддержка OpenLDAP и Microsoft Active Directory
21+
- Настраиваемые фильтры и маппинг атрибутов
22+
- Автоматическая синхронизация пользователей
1623

17-
Полная документация к модулю доступна [по ссылке](https://docs.mikopbx.com/mikopbx/modules/miko/module-users-u-i)
24+
### Категории разрешений
1825

19-
### Вопросы ##
26+
#### Веб-интерфейс (AdminCabinet)
27+
Детальный контроль над разделами панели управления MikoPBX:
28+
- **Просмотр**: Доступ к спискам и индексным страницам
29+
- **Детали**: Возможность открывать и просматривать записи
30+
- **Редактирование/Удаление**: Создание, изменение и удаление записей
2031

21-
Подключайтесь к каналу для разработчиков в telegram [@mikopbx\_dev](https://t.me/joinchat/AAPn5xSqZIpQnNnCAa3bBw)
32+
Поддерживаемые разделы:
33+
- Сотрудники и внутренние номера
34+
- Очереди вызовов и конференц-комнаты
35+
- IVR-меню и приложения диалплана
36+
- Входящие/исходящие маршруты
37+
- Провайдеры (SIP/IAX)
38+
- Звуковые файлы
39+
- История звонков (CDR)
40+
- Системные настройки
41+
- И многое другое...
2242

43+
#### Доступ к REST API
44+
Контроль доступных API-эндпоинтов:
45+
- Стандартные CRUD-операции (getList, getRecord, saveRecord, delete)
46+
- Пользовательские действия для каждого эндпоинта
47+
- Автоматическая связка между правами UI и API
48+
49+
### Фильтрация истории звонков (CDR)
50+
Ограничение видимости записей звонков по сотрудникам:
51+
- **Не фильтровать**: Показывать все записи
52+
- **Только выбранные**: Показывать только звонки выбранных сотрудников
53+
- **Только исходящие**: Показывать только исходящие звонки выбранных сотрудников
54+
- **Кроме выбранных**: Скрывать звонки определённых сотрудников
55+
56+
### Самообслуживание пользователей
57+
- Смена пароля для локальных пользователей
58+
- Управление ключами Passkey (WebAuthn) для беспарольной аутентификации
59+
60+
## Архитектура
61+
62+
### Модели базы данных
63+
| Модель | Описание |
64+
|--------|----------|
65+
| `AccessGroups` | Определения групп доступа с разрешениями |
66+
| `AccessGroupsRights` | Назначения гранулярных прав |
67+
| `AccessGroupCDRFilter` | Правила фильтрации CDR для групп |
68+
| `UsersCredentials` | Данные аутентификации пользователей |
69+
| `LdapConfig` | Конфигурация LDAP-сервера |
70+
71+
### Ключевые компоненты
72+
- **UsersUIACL**: Основная логика модификации ACL, интегрированная с MikoPBX
73+
- **UsersUIAuthenticator**: Обработка локальной и LDAP-аутентификации
74+
- **AutoLinkedActionsResolver**: Автоматическая связка прав UI↔API
75+
- **UsersUICDRFilter**: Фильтрация видимости CDR
76+
77+
## Установка
78+
79+
1. Скачайте модуль из маркетплейса MikoPBX или GitHub Releases
80+
2. Загрузите через **Модули → Установить модуль** в панели управления
81+
3. Включите модуль
82+
4. Настройте группы доступа и назначьте пользователей
83+
84+
## Требования
85+
86+
- MikoPBX 2025.1.1 или выше
87+
- PHP 8.3+
88+
- Действующая лицензия (коммерческий модуль)
89+
90+
## Настройка
91+
92+
### Создание группы доступа
93+
94+
1. Перейдите в **Модули → Управление доступом**
95+
2. Нажмите **Добавить группу доступа**
96+
3. Настройте:
97+
- Название и описание группы
98+
- Переключатель полного доступа (для администраторов)
99+
- Домашнюю страницу после входа
100+
- Права на интерфейс
101+
- Права на REST API
102+
- Настройки фильтра CDR
103+
104+
### Добавление пользователей
105+
106+
1. Перейдите в раздел **Сотрудники**
107+
2. Откройте карточку сотрудника
108+
3. На вкладке **Вход в MikoPBX**:
109+
- Включите доступ для входа
110+
- Задайте логин и пароль
111+
- Выберите группу доступа
112+
- При необходимости включите LDAP-аутентификацию
113+
114+
### Настройка LDAP
115+
116+
1. Перейдите на вкладку **Настройки LDAP** в модуле
117+
2. Настройте:
118+
- Адрес и порт сервера
119+
- Учётные данные администратора для запросов
120+
- Базовый DN
121+
- Фильтр пользователей и атрибуты
122+
3. Проверьте подключение и получение списка пользователей
123+
124+
## Интеграция с API
125+
126+
Модуль автоматически управляет правами для REST API v3:
127+
128+
```
129+
GET /pbxcore/api/v3/{resource} → getList
130+
GET /pbxcore/api/v3/{resource}/{id} → getRecord
131+
POST /pbxcore/api/v3/{resource} → create
132+
PUT /pbxcore/api/v3/{resource}/{id} → update
133+
DELETE /pbxcore/api/v3/{resource}/{id} → delete
134+
```
135+
136+
## Разработка
137+
138+
### Запуск тестов
139+
140+
```bash
141+
# Юнит-тесты (PHP)
142+
./vendor/bin/phpunit
143+
144+
# Интеграционные тесты (Python)
145+
cd Tests/Integration
146+
pip install -r requirements.txt
147+
cp .env.example .env
148+
# Настройте .env для вашего экземпляра MikoPBX
149+
pytest
150+
```
151+
152+
### Структура проекта
153+
154+
```
155+
ModuleUsersUI/
156+
├── App/
157+
│ ├── Controllers/ # MVC-контроллеры
158+
│ ├── Forms/ # Формы Phalcon
159+
│ └── Views/ # Шаблоны Volt
160+
├── Lib/
161+
│ ├── ACL/ # Логика контроля доступа
162+
│ └── *.php # Основные библиотеки
163+
├── Models/ # ORM-модели Phalcon
164+
├── Messages/ # Переводы (i18n)
165+
├── Setup/ # Скрипты установки
166+
├── Tests/ # Тестовые наборы
167+
└── public/assets/ # Фронтенд-ресурсы
168+
```
169+
170+
## Документация
171+
172+
Полная документация доступна по ссылкам:
173+
- Русский: [docs.mikopbx.com/modules/miko/module-users-u-i](https://docs.mikopbx.com/mikopbx/modules/miko/module-users-u-i)
174+
- English: [docs.mikopbx.com/modules/miko/module-users-u-i](https://docs.mikopbx.com/mikopbx/v/english/modules/miko/module-users-u-i)
175+
176+
## Поддержка
177+
178+
- Telegram: [@mikopbx_dev](https://t.me/joinchat/AAPn5xSqZIpQnNnCAa3bBw)
179+
- Email: help@miko.ru
180+
- Проблемы: [GitHub Issues](https://github.com/mikopbx/ModuleUsersUI/issues)
181+
182+
## Лицензия
183+
184+
GPL-3.0-or-later — подробности в файле [LICENSE](LICENSE).
185+
186+
Copyright © 2017-2025 MIKO LLC

0 commit comments

Comments
 (0)