Данное руководство описывает API Ринго для управления учётными записями пользователей и ролями. Вы узнаете, как создавать, изменять и удалять пользователей, назначать им роли, а также управлять правами доступа через API. Документация предназначена для интеграции с системами управления идентификацией, такими как 1IDM.
https://<ringo-server>/api/v1
Content-Type: application/json
Accept: application/json
Кодировка: UTF-8
| Поле | Тип | Описание |
|---|---|---|
id |
UUID | Уникальный идентификатор пользователя |
username |
string | Имя пользователя для входа (уникальное) |
password |
string | Пароль (только для создания/обновления, не возвращается) |
display_name |
string | Отображаемое имя |
email |
string | null | Email пользователя |
role |
object | null | Роль пользователя (объект с id, title, permissions) |
superadmin |
boolean | Флаг владельца окружения (суперадминистратор) |
origin_type |
enum | Источник УЗ: local или ldap |
access_origin |
enum | Источник прав: personal или group |
two_factor_auth_enabled |
boolean | Включена ли 2FA |
created_at |
datetime | Дата создания |
updated_at |
datetime | Дата последнего обновления |
| Поле | Тип | Описание |
|---|---|---|
id |
UUID | Уникальный идентификатор роли |
title |
string | Название роли (уникальное) |
permissions |
array | Массив разрешений (Permission) |
created_at |
datetime | Дата создания |
updated_at |
datetime | Дата последнего обновления |
| Значение | Описание |
|---|---|
local |
Локальная учётная запись (пароль хранится в Ринго) |
ldap |
Учётная запись из LDAP/AD (аутентификация через LDAP) |
| Значение | Описание |
|---|---|
personal |
Права назначаются персонально через роль |
group |
Права наследуются из групп системных пользователей |
Для интеграции с 1IDM рекомендуется:
origin_type: "local",access_origin: "personal"
Перед вызовом API необходимо получить access_token.
POST /api/v1/auth
Описание: Аутентификация и получение токена доступа.
Запрос:
{
"username": "idm_service_account",
"password": "SecurePassword123!"
}
Заголовки запроса:
Content-Type: application/json
User-Agent: 1IDM-Integration/1.0
Ответ (200 OK):
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"username": "idm_service_account",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"permissions": ["ReadAdministration", "EditAdministration", "ReadDevices", "EditDevices"],
"superadmin": false,
"two_factor_auth_required": false,
"two_factor_auth_activated": false
}
Ошибки:
| Код | Описание |
|---|---|
| 401 | Неверное имя пользователя или пароль |
| 400 | Отсутствует агент пользователя |
Все последующие запросы должны содержать заголовок авторизации:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
User-Agent: 1IDM-Integration/1.0
Сервисная учётная запись для 1IDM должна иметь права:
| Permission | Описание |
|---|---|
ReadAdministration |
Просмотр пользователей и ролей |
EditAdministration |
Создание, изменение, удаление пользователей и ролей |
POST /api/v1/user
Описание: Создать новую учётную запись.
Требуемые права: EditAdministration
Запрос:
{
"username": "ivanov.ivan",
"password": "SecureP@ssw0rd!",
"display_name": "Иванов Иван Иванович",
"email": "ivanov@client.ru",
"origin_type": "local",
"access_origin": "personal",
"role": "550e8400-e29b-41d4-a716-446655440001",
"superadmin": false
}
Параметры запроса:
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
username |
string | Да | Имя пользователя (max 256 символов) |
password |
string | Да* | Пароль (*обязателен для origin_type: "local") |
display_name |
string | Нет | Отображаемое имя (по умолчанию = username) |
email |
string | Нет | Email пользователя |
origin_type |
string | Да | local или ldap |
access_origin |
string | Да | personal или group |
role |
UUID | Нет | UUID роли (только для access_origin: "personal") |
superadmin |
boolean | Нет | Флаг суперадминистратора (default: false) |
Ответ (200 OK):
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"username": "ivanov.ivan",
"display_name": "Иванов Иван Иванович",
"email": "ivanov@client.ru",
"role": {
"id": "550e8400-e29b-41d4-a716-446655440001",
"title": "Оператор",
"permissions": ["ReadDevices", "ReadProfiles"]
},
"superadmin": false,
"origin_type": "local",
"access_origin": "personal",
"two_factor_auth_enabled": false,
"created_at": "2025-12-08T10:30:00.000Z",
"updated_at": "2025-12-08T10:30:00.000Z"
}
Ошибки:
| Код | Сообщение | Описание |
|---|---|---|
| 400 | Уже имеется пользователь с таким именем | Дубликат username |
| 400 | missing password | Пароль обязателен для local-пользователей |
| 404 | Роль не найдена | Указанная роль не существует |
| 403 | Только другой владелец окружения может создавать владелеца окружения | Нет прав на установку superadmin |
GET /api/v1/user/list
Описание: Получить список всех пользователей с пагинацией.
Требуемые права: ReadAdministration или EditAdministration
Query-параметры:
| Параметр | Тип | Описание | По умолчанию |
|---|---|---|---|
page |
integer | Номер страницы | 1 |
limit |
integer | Количество записей на страницу | 10 |
sort_field |
enum | Поле сортировки | username |
sort_order |
enum | Порядок сортировки: asc / desc |
asc |
origin_type |
enum | Фильтр по источнику: local / ldap |
– |
Поля сортировки (sort_field):
| Значение | Описание |
|---|---|
username |
Имя пользователя |
display_name |
Отображаемое имя |
email |
|
role |
Роль |
superadmin |
Флаг суперадмина |
origin_type |
Тип источника |
access_origin |
Источник прав |
created_at |
Дата создания |
updated_at |
Дата обновления |
Пример запроса:
GET /api/v1/user/list?page=1&limit=50&origin_type=local&sort_field=username&sort_order=asc
Ответ (200 OK):
{
"count": 125,
"users": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"username": "ivanov.ivan",
"display_name": "Иванов Иван Иванович",
"email": "ivanov@client.ru",
"role": {
"id": "550e8400-e29b-41d4-a716-446655440001",
"title": "Оператор",
"permissions": ["ReadDevices", "ReadProfiles"]
},
"superadmin": false,
"origin_type": "local",
"access_origin": "personal",
"two_factor_auth_enabled": false,
"created_at": "2025-12-08T10:30:00.000Z",
"updated_at": "2025-12-08T10:30:00.000Z"
}
// ... другие пользователи
]
}
GET /api/v1/user/{id}
Описание: Получить информацию о пользователе по его UUID.
Требуемые права: ReadAdministration или EditAdministration
Ответ (200 OK):
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"username": "ivanov.ivan",
"display_name": "Иванов Иван Иванович",
"email": "ivanov@client.ru",
"role": {
"id": "550e8400-e29b-41d4-a716-446655440001",
"title": "Оператор",
"permissions": ["ReadDevices", "ReadProfiles"]
},
"superadmin": false,
"origin_type": "local",
"access_origin": "personal",
"two_factor_auth_enabled": false,
"created_at": "2025-12-08T10:30:00.000Z",
"updated_at": "2025-12-08T10:30:00.000Z"
}
Ошибки:
| Код | Описание |
|---|---|
| 404 | Пользователь не найден |
PATCH /api/v1/user/{id}
Описание: Изменить атрибуты пользователя.
Требуемые права: EditAdministration
Запрос (частичное обновление):
{
"display_name": "Иванов Иван Иванович",
"email": "ivanov@client.ru"
}
Все доступные поля для обновления:
| Параметр | Тип | Описание |
|---|---|---|
username |
string | Имя пользователя (только для local) |
password |
string | Пароль (только для local) |
display_name |
string | Отображаемое имя |
email |
string | |
role |
UUID | null | UUID роли или null для удаления |
access_origin |
enum | Источник прав (personal / group) |
superadmin |
boolean | Флаг суперадминистратора |
Ответ (200 OK):
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"username": "ivanov.ivan",
"display_name": "Иванов Иван Иванович",
"email": "ivanov@client.ru",
"role": {
"id": "550e8400-e29b-41d4-a716-446655440001",
"title": "Оператор",
"permissions": ["ReadDevices", "ReadProfiles"]
},
"superadmin": false,
"origin_type": "local",
"access_origin": "personal",
"two_factor_auth_enabled": false,
"created_at": "2025-12-08T10:30:00.000Z",
"updated_at": "2025-12-08T12:00:00.000Z"
}
Ошибки:
| Код | Сообщение | Описание |
|---|---|---|
| 404 | Пользователь не найден | Неверный UUID |
| 400 | Уже имеется пользователь с таким именем | Дубликат username |
| 400 | Невозможно изменить имя пользователя созданного из LDAP каталога | Попытка изменить username для ldap |
| 400 | Невозможно изменить пароль пользователя созданного из LDAP каталога | Попытка изменить password для ldap |
| 400 | Нельзя лишить себя прав администратора | Попытка отозвать свою роль |
PATCH /api/v1/user/{id}
Описание: Назначить роль пользователю (тот же эндпоинт обновления).
Запрос:
{
"role": "550e8400-e29b-41d4-a716-446655440002"
}
Ответ (200 OK):
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"username": "ivanov.ivan",
"display_name": "Иванов Иван Иванович",
"email": "ivanov@client.ru",
"role": {
"id": "550e8400-e29b-41d4-a716-446655440002",
"title": "Администратор устройств",
"permissions": ["ReadDevices", "EditDevices", "ReadProfiles", "EditProfiles"]
},
"superadmin": false,
"origin_type": "local",
"access_origin": "personal",
"two_factor_auth_enabled": false,
"created_at": "2025-12-08T10:30:00.000Z",
"updated_at": "2025-12-08T12:15:00.000Z"
}
PATCH /api/v1/user/{id}
Описание: Отозвать роль у пользователя, установив role: null.
Запрос:
{
"role": null
}
Результат: Пользователь теряет все права, связанные с ролью. После этого:
Важно! Это эквивалент "мягкой блокировки" – пользователь существует, но не имеет полномочий.
DELETE /api/v1/user/{id}
Описание: Полностью удалить учётную запись.
Требуемые права: EditAdministration
Ответ (200 OK):
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"username": "ivanov.ivan",
"display_name": "Иванов Иван Иванович",
"email": "ivanov@client.ru",
"role": null,
"superadmin": false,
"origin_type": "local",
"access_origin": "personal",
"two_factor_auth_enabled": false,
"created_at": "2025-12-08T10:30:00.000Z",
"updated_at": "2025-12-08T12:30:00.000Z"
}
Ошибки:
| Код | Сообщение | Описание |
|---|---|---|
| 404 | Пользователь не найден | Неверный UUID |
| 400 | Нельзя удалить своего пользователя | Самоудаление запрещено |
| 400 | В системе должен быть хотя бы один владелец окружения | Должен остаться хотя бы один superadmin |
| 403 | Только суперадминистратор может удалять суперадминистраторов | Нет прав |
GET /api/v1/user/{id}/groups
Описание: Получить группы системных пользователей, в которых состоит пользователь.
Требуемые права: ReadAdministration или EditAdministration
Query-параметры:
| Параметр | Тип | Описание |
|---|---|---|
page |
integer | Номер страницы |
limit |
integer | Количество записей |
sort_field |
enum | Поле сортировки: title, role |
sort_order |
enum | Порядок: asc / desc |
Ответ (200 OK):
{
"count": 2,
"groups": [
{
"id": "group-uuid-1",
"title": "Операторы 1 уровня",
"role": {
"id": "role-uuid",
"title": "Оператор"
}
},
{
"id": "group-uuid-2",
"title": "Группа технической поддержки",
"role": null
}
]
}
POST /api/v1/roles
Описание: Создать новую роль с набором разрешений.
Требуемые права: EditAdministration
Запрос:
{
"title": "Оператор первого уровня",
"permissions": [
"ReadDevices",
"ReadProfiles",
"ReadPolicies"
]
}
Ответ (201 Created):
{
"id": "550e8400-e29b-41d4-a716-446655440003",
"title": "Оператор первого уровня",
"permissions": [
"ReadDevices",
"ReadProfiles",
"ReadPolicies"
],
"created_at": "2025-12-08T10:00:00.000Z",
"updated_at": "2025-12-08T10:00:00.000Z"
}
Ошибки:
| Код | Описание |
|---|---|
| 404 | Роль с таким названием уже существует |
GET /api/v1/roles
Описание: Получить все роли системы.
Требуемые права: ReadAdministration или EditAdministration
Ответ (200 OK):
{
"count": 5,
"roles": [
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"title": "Администратор",
"permissions": [
"ReadDevices", "EditDevices",
"ReadProfiles", "EditProfiles",
"ReadPolicies", "EditPolicies",
"ReadGroups", "EditGroups",
"ReadAdministration", "EditAdministration",
"ReadCommands", "EditCommands",
"ReadScripts", "EditScripts",
"ReadPackages", "EditPackages",
"ReadDeviceUsers", "EditDeviceUsers",
"ReadDeviceApplications", "EditDeviceApplications",
"ReadTerminal", "EditTerminal"
],
"created_at": "2025-01-01T00:00:00.000Z",
"updated_at": "2025-01-01T00:00:00.000Z"
},
{
"id": "550e8400-e29b-41d4-a716-446655440002",
"title": "Оператор",
"permissions": [
"ReadDevices",
"ReadProfiles"
],
"created_at": "2025-01-01T00:00:00.000Z",
"updated_at": "2025-01-01T00:00:00.000Z"
}
]
}
GET /api/v1/roles/{id}
Описание: Получить детали конкретной роли.
Требуемые права: ReadAdministration или EditAdministration
Ответ (200 OK):
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"title": "Администратор",
"permissions": [
"ReadDevices", "EditDevices",
"ReadProfiles", "EditProfiles"
],
"created_at": "2025-01-01T00:00:00.000Z",
"updated_at": "2025-01-01T00:00:00.000Z"
}
PATCH /api/v1/roles/{id}
Описание: Изменить название и/или права роли.
Требуемые права: EditAdministration
Запрос:
{
"title": "Оператор расширенный",
"permissions": [
"ReadDevices", "EditDevices",
"ReadProfiles"
]
}
Ответ (200 OK):
{
"id": "550e8400-e29b-41d4-a716-446655440002",
"title": "Оператор расширенный",
"permissions": [
"ReadDevices", "EditDevices",
"ReadProfiles"
],
"created_at": "2025-01-01T00:00:00.000Z",
"updated_at": "2025-12-08T14:00:00.000Z"
}
Ошибки:
| Код | Описание |
|---|---|
| 404 | Роль не найдена |
| 400 | Роль с таким названием уже существует |
| 400 | Нельзя изменить или удалить роль администратора |
Важно! Изменение роли автоматически применяется ко всем пользователям с этой ролью.
DELETE /api/v1/roles/{id}
Описание: Удалить роль.
Требуемые права: EditAdministration
Ограничения:
Ошибки:
| Код | Описание |
|---|---|
| 404 | Роль не найдена |
| 400 | Эта роль назначена пользователю |
| 400 | Нельзя удалить системную роль "Администратор" |
| Permission | Описание |
|---|---|
| Устройства | |
ReadDevices |
Просмотр устройств |
EditDevices |
Управление устройствами |
| Группы | |
ReadGroups |
Просмотр групп |
EditGroups |
Управление группами |
| Профили конфигурации | |
ReadProfiles |
Просмотр профилей |
EditProfiles |
Управление профилями |
| Политики | |
ReadPolicies |
Просмотр политик |
EditPolicies |
Управление политиками |
| Администрирование | |
ReadAdministration |
Просмотр настроек администрирования |
EditAdministration |
Управление настройками, пользователями, ролями |
| Команды | |
ReadCommands |
Просмотр команд |
EditCommands |
Выполнение команд на устройствах |
| Скрипты | |
ReadScripts |
Просмотр скриптов |
EditScripts |
Управление скриптами |
| Пакеты | |
ReadPackages |
Просмотр пакетов |
EditPackages |
Управление пакетами |
| Пользователи устройств | |
ReadDeviceUsers |
Просмотр пользователей устройств |
EditDeviceUsers |
Управление пользователями устройств |
| Приложения | |
ReadDeviceApplications |
Просмотр приложений |
EditDeviceApplications |
Управление приложениями |
| Терминал | |
ReadTerminal |
Просмотр истории терминала |
EditTerminal |
Доступ к терминалу устройств |
Перед началом работы убедитесь, что выполнены следующие условия:
idm_service с ролью, содержащей права ReadAdministration и EditAdministrationPOST /api/v1/auth
Content-Type: application/json
User-Agent: 1IDM-Integration/1.0
Запрос:
{
"username": "idm_service",
"password": "ServiceP@ssw0rd!"
}
Ответ:
{
"id": "<UUID>",
"username": "idm_service",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJzZXJ2aWNlLXVzZXItdXVpZCIsImlhdCI6MTczMzY1MDAwMH0.signature",
"permissions": ["ReadAdministration", "EditAdministration"],
"superadmin": false,
"two_factor_auth_required": false,
"two_factor_auth_activated": false
}
Важно! Сохраните
access_tokenдля использования во всех последующих запросах.
GET /api/v1/roles
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
User-Agent: 1IDM-Integration/1.0
Ответ:
{
"count": 3,
"roles": [
{
"id": "<UUID>",
"title": "Администратор",
"permissions": ["ReadDevices", "EditDevices", "ReadAdministration", "EditAdministration"]
},
{
"id": "<UUID>",
"title": "Оператор",
"permissions": ["ReadDevices", "ReadProfiles"]
},
{
"id": "<UUID>",
"title": "Техническая поддержка",
"permissions": ["ReadDevices", "EditDevices", "ReadCommands", "EditCommands"]
}
]
}
Сценарий: Создание нового сотрудника с ролью "Оператор".
POST /api/v1/user
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
User-Agent: 1IDM-Integration/1.0
Запрос:
{
"username": "petrov.petr",
"password": "password",
"display_name": "Петров Пётр Петрович",
"email": "petrov@client.ru",
"origin_type": "local",
"access_origin": "personal",
"role": "<ROLE_UUID>"
}
Ответ:
{
"id": "<UUID>",
"username": "petrov.petr",
"display_name": "Петров Пётр Петрович",
"email": "petrov@client.ru",
"role": {
"id": "<ROLE_UUID>",
"title": "Оператор",
"permissions": ["ReadDevices", "ReadProfiles"]
},
"superadmin": false,
"origin_type": "local",
"access_origin": "personal",
"two_factor_auth_enabled": false,
"created_at": "2025-12-08T10:00:00.000Z",
"updated_at": "2025-12-08T10:00:00.000Z"
}
Сценарий: Повысить пользователя до роли "Техническая поддержка".
PATCH /api/v1/user/<UUID>
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
User-Agent: 1IDM-Integration/1.0
Запрос:
{
"role": "<ROLE_UUID>"
}
Ответ:
{
"id": "<UUID>",
"username": "petrov.petr",
"display_name": "Петров Пётр Петрович",
"email": "petrov@client.ru",
"role": {
"id": "<ROLE_UUID>",
"title": "Техническая поддержка",
"permissions": ["ReadDevices", "EditDevices", "ReadCommands", "EditCommands"]
},
"superadmin": false,
"origin_type": "local",
"access_origin": "personal",
"two_factor_auth_enabled": false,
"created_at": "2025-12-08T10:00:00.000Z",
"updated_at": "2025-12-08T11:00:00.000Z"
}
Сценарий: Сотрудник переводится в другой отдел, временно снимаем роль.
PATCH /api/v1/user/<UUID>
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
User-Agent: 1IDM-Integration/1.0
Запрос:
{
"role": null
}
Ответ:
{
"id": "<UUID>",
"username": "petrov.petr",
"display_name": "Петров Пётр Петрович",
"email": "petrov@client.ru",
"role": null,
"superadmin": false,
"origin_type": "local",
"access_origin": "personal",
"two_factor_auth_enabled": false,
"created_at": "2025-12-08T10:00:00.000Z",
"updated_at": "2025-12-08T12:00:00.000Z"
}
Результат: Пользователь может войти в систему, но не имеет прав на действия.
Сценарий: Аудит – получить текущие права конкретного пользователя.
GET /api/v1/user/<UUID>
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
User-Agent: 1IDM-Integration/1.0
Ответ:
{
"id": "<UUID>",
"username": "petrov.petr",
"display_name": "Петров Пётр Петрович",
"email": "petrov@client.ru",
"role": null,
"superadmin": false,
"origin_type": "local",
"access_origin": "personal",
"two_factor_auth_enabled": false,
"created_at": "2025-12-08T10:00:00.000Z",
"updated_at": "2025-12-08T12:00:00.000Z"
}
Интерпретация:
role: null → пользователь не имеет назначенной ролиsuperadmin: false → не является суперадминистраторомСценарий: Проверить, существует ли пользователь и есть ли у него права.
GET /api/v1/user/<UUID>
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
User-Agent: 1IDM-Integration/1.0
Логика определения статуса:
| Условие | Статус |
|---|---|
Пользователь найден + role не null |
Активен с правами |
Пользователь найден + role = null + superadmin = false |
Активен без прав (мягкая блокировка) |
Пользователь найден + superadmin = true |
Активен как суперадмин |
| Ответ 404 | Не существует / Удален |
Сценарий: Увольнение сотрудника – полное удаление учётной записи.
DELETE /api/v1/user/<UUID>
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
User-Agent: 1IDM-Integration/1.0
Ответ:
{
"id": "<UUID>",
"username": "petrov.petr",
"display_name": "Петров Пётр Петрович",
"email": "petrov@client.ru",
"role": null,
"superadmin": false,
"origin_type": "local",
"access_origin": "personal",
"two_factor_auth_enabled": false,
"created_at": "2025-12-08T10:00:00.000Z",
"updated_at": "2025-12-08T14:00:00.000Z"
}
Результат: Пользователь полностью удалён. При попытке GET вернётся 404.
При истечении access_token необходимо обновить его:
GET /api/v1/auth/refresh
Cookie: refreshToken=<refresh_token_value>
User-Agent: 1IDM-Integration/1.0
Ответ:
{
"id": "<UUID>",
"username": "idm_service",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.NEW_TOKEN...",
"permissions": ["ReadAdministration", "EditAdministration"],
"superadmin": false,
"two_factor_auth_required": false
}
Минимальный запрос (локальный пользователь без роли):
{
"username": "novikov.an",
"password": "password",
"origin_type": "local",
"access_origin": "personal"
}
Полный запрос:
{
"username": "novikov.an",
"password": "password",
"display_name": "Новиков Андрей Николаевич",
"email": "novikov.an@client.ru",
"origin_type": "local",
"access_origin": "personal",
"role": "<ROLE_UUID>",
"superadmin": false
}
{
"role": "<ROLE_UUID>"
}
{
"role": null
}
{
"display_name": "Новиков Андрей Петрович",
"email": "novikov.ap@client.ru"
}
{
"password": "new_password"
}
{
"title": "Аудитор",
"permissions": [
"ReadDevices",
"ReadGroups",
"ReadProfiles",
"ReadPolicies",
"ReadAdministration"
]
}
{
"permissions": [
"ReadDevices",
"EditDevices",
"ReadGroups",
"ReadProfiles",
"ReadPolicies",
"ReadAdministration"
]
}
| Операция | Доступна | Примечание |
|---|---|---|
| Создание локальных пользователей | Да | origin_type: "local" |
| Создание LDAP-пользователей | Да | origin_type: "ldap", username должен существовать в AD |
| Назначение роли | Да | Через PATCH /user/ |
| Отзыв роли | Да | role: null |
| Удаление пользователя | Да | DELETE |
| Смена пароля локального пользователя | Да | Через PATCH |
| Смена пароля LDAP-пользователя | Нет | Пароль управляется в AD |
| Блокировка без удаления | С условием | Реализуется через role: null |
| Создание ролей | Да | |
| Изменение ролей | Да | Кроме системной роли "Администратор" |
| Удаление ролей | С условием | Только если нет назначенных пользователей |
| Ограничение | Описание |
|---|---|
| Самоудаление запрещено | Нельзя удалить своего пользователя |
| Минимум один суперадмин | Нельзя удалить/понизить последнего суперадминистратора |
| Роль "Администратор" защищена | Системная роль не подлежит редактированию и удалению |
| Уникальность username | Невозможно создать дубликат |
| Уникальность title роли | Невозможно создать роли с одинаковыми названиями |
| Поле | Обязательное | Источник в IDM |
|---|---|---|
username |
Да | Логин сотрудника |
password |
Да* | Генерируется IDM или передаётся из AD |
display_name |
Нет | ФИО сотрудника |
email |
Нет | Корпоративная почта |
origin_type |
Да | Всегда "local" для IDM-управления |
access_origin |
Да | Всегда "personal" для IDM-управления |
role |
Нет | UUID роли из Ринго |
| Поле | Назначение |
|---|---|
role |
UUID роли или null для отзыва |
display_name |
При изменении ФИО |
email |
При изменении почты |
password |
При сбросе пароля |
| Сценарий | Проблема | Решение |
|---|---|---|
| Пользователь создан как local, но существует в AD | Дубликат username при попытке синхронизации LDAP | Использовать уникальные username или префиксы |
| IDM создаёт ldap-пользователя, которого нет в AD | Ошибка 400: "Пользователь не найден в LDAP" | Синхронизировать создание с AD |
| LDAP-группы и IDM управляют одним пользователем | Конфликт источников прав | Использовать access_origin: "personal" для IDM-управления |
| Пользователь удалён в AD, но остался в Ринго | "Orphaned" учётная запись | Регулярная синхронизация и очистка |
Рекомендация: Для интеграции с 1IDM использовать только локальных пользователей (
origin_type: "local",access_origin: "personal"), чтобы избежать конфликтов с LDAP-интеграцией.
Обязательные операции:
| Операция | Метод | Endpoint |
|---|---|---|
| Аутентификация | POST | /api/v1/auth |
| Список ролей | GET | /api/v1/roles |
| Создание пользователя | POST | /api/v1/user |
| Изменение пользователя | PATCH | /api/v1/user/{id} |
| Удаление пользователя | DELETE | /api/v1/user/{id} |
| Просмотр пользователя | GET | /api/v1/user/{id} |
Дополнительные операции:
| Операция | Метод | Endpoint |
|---|---|---|
| Список пользователей | GET | /api/v1/user/list |
| Создание роли | POST | /api/v1/roles |
| Обновление роли | PATCH | /api/v1/roles/{id} |
1. POST /api/v1/auth → Получить access_token
2. GET /api/v1/roles → Получить UUID нужной роли
3. POST /api/v1/user → Создать пользователя с ролью
4. (опционально) GET /api/v1/user/{id} → Подтвердить создание
1. POST /api/v1/auth → Получить access_token
2. GET /api/v1/roles → Найти UUID новой роли
3. PATCH /api/v1/user/{id} → Обновить роль
1. POST /api/v1/auth → Получить access_token
2. PATCH /api/v1/user/{id} → { "role": null }
1. POST /api/v1/auth → Получить access_token
2. DELETE /api/v1/user/{id} → Удалить пользователя
1. POST /api/v1/auth → Получить access_token
2. GET /api/v1/user/list?origin_type=local → Получить всех локальных пользователей
3. Сравнить с базой IDM
4. Для каждого расхождения:
- Лишние в Ринго → DELETE
- Отсутствующие в Ринго → POST
- Различия в атрибутах → PATCH
| Поле | Обязательное | Значение по умолчанию |
|---|---|---|
username |
Да | – |
password |
Да | – |
origin_type |
Да | – (использовать "local") |
access_origin |
Да | – (использовать "personal") |
display_name |
Нет | = username |
email |
Нет | null |
role |
Нет | null |
superadmin |
Нет | false |
Все поля опциональны. Передавать только изменённые.
| Операция | Идемпотентна? | Примечание |
|---|---|---|
| GET | Да | Всегда безопасно |
| POST /user | Нет | Повторный вызов создаст ошибку 400 (дубликат username) |
| PATCH /user | Да | Можно вызывать многократно с тем же телом |
| DELETE /user | Нет | Первый вызов – успех, повторный – 404 |
| POST /roles | Нет | Ошибка при дубликате title |
| PATCH /roles | Да | Можно вызывать многократно |
| DELETE /roles | Нет | Первый вызов – успех, повторный – 404 |
Текущая реализация: DELETE выполняет hard delete (полное удаление записи).
Альтернатива для "мягкой блокировки":
PATCH /api/v1/user/{id}
{
"role": null
}
Это сохраняет учётную запись, но лишает пользователя прав.
{
"message": "Текст ошибки на русском языке",
"statusCode": 400,
"timestamp": "2025-12-08T10:00:00.000Z",
"path": "/api/v1/user"
}
| Код | Ситуация | Действие IDM |
|---|---|---|
| 200 | Успех | Продолжить |
| 201 | Создано | Продолжить |
| 400 | Неверный запрос | Логировать, проверить payload |
| 401 | Не авторизован | Обновить токен через /auth/refresh или /auth |
| 403 | Запрещено | Проверить права сервисной УЗ |
| 404 | Не найдено | Ресурс отсутствует, возможно уже удалён |
| 500 | Внутренняя ошибка | Повторить, эскалировать при повторении |
ReadAdministration и EditAdministrationsuperadmin права