Словари приложений

ℹ️ О документе

В этом разделе описывается работа со словарями приложений OIDC — автоматическая синхронизация объектов, действий и проектов между внешними приложениями и IDENTYX.

Что такое словари приложений

Словари приложений — это механизм автоматической синхронизации структуры внешнего приложения с системой управления доступом IDENTYX. Когда приложение отправляет свои справочники в IAM, система может автоматически создавать соответствующие объекты, действия и проекты для управления правами доступа.

✅ Преимущества использования словарей
  • Автоматическая синхронизация — не нужно вручную создавать объекты и действия для каждого приложения
  • Актуальность данных — структура прав доступа всегда соответствует структуре приложения
  • Удобство управления — изменения в приложении автоматически отражаются в IAM
  • Централизованное хранение — все справочники хранятся в одном месте

Типы словарей

IDENTYX поддерживает четыре типа словарей приложений:

📦 Объекты приложения

Словарь objects содержит список объектов безопасности приложения — это сущности, на которые назначаются права доступа (разделы меню, документы, страницы и т.д.).

Пример: /app-id/documents, /app-id/reports, /app-id/settings

⚡ Действия приложения

Словарь actions содержит список действий безопасности — это операции, которые можно выполнять над объектами (просмотр, редактирование, удаление и т.д.).

Пример: /app-id/read, /app-id/write, /app-id/delete

🏢 Проекты

Словарь organizations содержит структуру проектов из внешнего приложения для синхронизации с деревом проектов IDENTYX.

Пример: /projects/head-office, /projects/office-moscow

🏬 Площадки

Словарь Площадки содержит список площадок приложения — удалённых сетей, до узлов которых нет прямого сетевого пути. Из этого словаря карточка LDAP-домена берёт варианты для поля Площадка.

В отличие от остальных типов, этот словарь не создаёт объектов и действий: это данные для настройки подключения, а не права доступа.

⚠️ Неизвестные типы словарей отклоняются

Если приложение пришлёт словарь типа, которого IDENTYX не знает, отклоняется вся публикация — с сообщением «Неизвестный тип справочника: <тип>», и в реестр такой словарь не попадает. Строка, подписанная Неизвестный тип, означает другое: словарь принят и сохранён, но у таблицы реестра нет для него названия.

Словарь «Площадки»

Площадки IDENTYX не ведёт сам — их публикует внешнее приложение (INFRAX) вместе с остальными своими словарями. Каждая публикация заменяет содержимое словаря целиком, поэтому площадка, которой в приложении больше нет, исчезает и из IDENTYX.

В словарь попадают только действующие площадки. Не публикуются: собственная площадка самой инсталляции приложения, отозванные площадки и площадки, которые ещё ожидают подключения.

Содержимое смотрят там же, где и у остальных словарей — см. Просмотр словарей приложения. На вкладке Справочники найдите строку типа Площадки и нажмите кнопку с иконкой глаза (Просмотреть содержимое справочника): откроется окно Справочник "Площадки" со списком площадок и счётчиком Всего элементов.

ℹ️ Словарь площадок не редактируется вручную
  • Добавлять, переименовывать и отзывать площадки нужно на стороне приложения — в IDENTYX они появляются автоматически при очередной публикации словарей.
  • Кнопка Применить справочник для площадок не нужна: объекты и действия по этому словарю не создаются.
  • Пока словарь площадок пуст, поле Площадка в карточке LDAP-домена не показывается вовсе — на установке без площадок администратор его не увидит.
  • Если домен ссылается на площадку, которой в словаре уже нет, в его карточке появляется предупреждение «Площадка не найдена в справочнике — вход через этот домен работать не будет», а сохранить такой домен не удастся: система ответит «Площадка не найдена в справочнике: <ключ>».

Просмотр словарей приложения

Для просмотра и управления словарями приложения:

  1. Перейдите в раздел Интеграции → Приложения
  2. Нажмите на нужное приложение для открытия карточки
  3. Перейдите на вкладку Справочники

На вкладке Справочники доступны две подвкладки:

Реестр

Вкладка Реестр отображает список всех словарей, которые были загружены приложением в IDENTYX.

Колонка Описание
Тип справочника Тип словаря: Объекты приложения, Действия приложения, Проекты или Площадки
Операции Кнопка просмотра содержимого словаря
ℹ️ Фильтрация

Вы можете отфильтровать словари по типу, используя выпадающий список в верхней части таблицы. Доступны варианты: Все типы, Объекты приложения, Действия приложения, Проекты, Площадки.

Просмотр содержимого словаря

Для просмотра содержимого конкретного словаря:

  1. На вкладке Реестр нажмите кнопку с иконкой глаза напротив нужного словаря
  2. Откроется модальное окно с содержимым словаря

В окне просмотра содержимого отображается:

  • Дерево элементов — иерархическая структура объектов, действий или проектов
  • Количество элементов — общее количество записей в словаре
  • Настройки применения — параметры для обработки словаря
⚠️ Применение словаря

В окне просмотра доступна кнопка Применить справочник. При нажатии система обработает словарь и создаст или обновит соответствующие объекты безопасности в IDENTYX.

Автоматическая загрузка словарей

Вместо ручного применения каждого словаря, вы можете настроить автоматическую обработку при получении обновлений от приложения.

Настройка автообработки

Для настройки автоматической обработки словарей:

  1. В карточке приложения перейдите на вкладку Справочники
  2. Откройте подвкладку Автоматическая загрузка справочников
  3. В таблице настроек отобразятся все доступные типы словарей

Для каждого типа словаря доступны следующие параметры:

Параметр Описание
Автоматически загружать Установите флажок для включения автоматической обработки этого типа словаря
Удалять старые объекты Если флажок установлен, объекты, которых нет в новом словаре, будут удалены из системы
🚫 Внимание при удалении старых объектов

Опция Удалять старые объекты удалит из IDENTYX все объекты или действия, которых нет в новом словаре. Это может привести к потере настроенных прав доступа. Используйте эту опцию с осторожностью!

Когда происходит автоматическая обработка

Автоматическая обработка словарей выполняется в следующих случаях:

  • При импорте приложения из JSON — если приложение содержит словари и настроена автообработка
  • При обновлении словарей через API — когда приложение отправляет обновленные справочники
  • При сохранении настроек приложения — если были изменены маппинги словарей
ℹ️ Проверка валидности

Перед применением словаря система проверяет возможность построения дерева объектов или действий. Если словарь содержит ошибки (например, циклические зависимости), операция будет отменена с сообщением об ошибке.

Ручное применение словаря

Если автоматическая обработка не включена, вы можете применить словарь вручную:

  1. Откройте реестр словарей на вкладке Справочники → Реестр
  2. Нажмите кнопку просмотра напротив нужного словаря
  3. В открывшемся окне настройте параметр Удалять объекты, если их нет в новом справочнике (опционально)
  4. Нажмите кнопку Применить справочник

После применения словаря:

  • Будут созданы или обновлены соответствующие объекты безопасности в разделе Права доступа → Объекты
  • Будут созданы или обновлены действия безопасности в разделе Права доступа → Действия
  • При необходимости будут обновлены связанные учетные записи и правила доступа
✅ Отслеживание изменений

При изменении путей объектов в словаре система автоматически обновляет пути в правилах доступа (ACL) и учетных записях приложений, чтобы не потерять настроенные права.

Импорт и экспорт словарей

Словари приложений автоматически включаются в экспорт и импорт приложений через JSON файлы.

Экспорт приложения со словарями

Для экспорта приложения вместе со словарями:

  1. Откройте карточку приложения
  2. Нажмите кнопку Экспорт внизу карточки
  3. Будет создан JSON файл с именем app-{client_id}.json

Экспортируемый файл содержит:

  • Все настройки приложения (client_id, client_secret, маршруты и т.д.)
  • Маппинги словарей с настройками автообработки
  • Параметры удаления старых объектов для каждого типа словаря

Импорт приложения со словарями

При импорте приложения из JSON:

  1. Система создаст или обновит приложение
  2. Восстановит настройки маппинга словарей
  3. Если включена автообработка и в JSON есть словари, они будут автоматически применены
⚠️ Формат данных словарей

Содержимое самих словарей (списки объектов и действий) хранится в отдельной таблице и не включается в JSON файл экспорта. Экспортируются только настройки маппинга. Для загрузки содержимого словарей приложение должно отправить их через API.

API для работы со словарями

Внешние приложения могут отправлять свои словари в IDENTYX через специальный API метод:

POST /api/service
{
  "action": "putDictionaries",
  "client_id": "client-id-приложения",
  "client_secret": "secret-приложения",
  "data": {
    "dictionaries": {
      "objects": [
        {"id": "/documents", "title": "Документы", "uid": "0f3c1a52-9d51-4f0a-9f0e-2b4b7c1d0001", "kind": "section"},
        {"id": "/reports", "title": "Отчеты", "uid": "0f3c1a52-9d51-4f0a-9f0e-2b4b7c1d0002", "kind": "folder"},
        {"id": "/settings", "title": "Настройки"}
      ],
      "actions": [
        {"id": "/read", "title": "Чтение"},
        {"id": "/write", "title": "Запись"},
        {"id": "/delete", "title": "Удаление"},
        {"id": "/admin", "title": "Администрирование", "applicable_objects": ["/settings"]}
      ]
    }
  }
}

В примере выше действие "Администрирование" можно назначить только на объект "Настройки" (и его дочерние объекты), а действия "Чтение", "Запись" и "Удаление" можно назначить на любые объекты.

При получении словарей через API:

  1. Система сохраняет содержимое словарей в базу данных
  2. Если для этого типа словаря включена автообработка, словарь будет автоматически применен
  3. Будут созданы или обновлены соответствующие объекты и действия в дереве прав доступа
ℹ️ Структура элементов словаря

Каждый элемент словаря должен содержать как минимум два поля:

  • id — уникальный идентификатор элемента (может быть путем, например /documents/reports)
  • title — отображаемое название элемента

Дополнительно для словаря объектов:

  • uid — собственный идентификатор объекта в приложении, в формате uuid. Если он прислан, объект в IDENTYX опознаётся по нему, а не по пути: перемещение объекта в другую папку меняет только путь, а выданные на объект права остаются на месте. Идентификатор должен быть постоянным на всё время жизни объекта и не повторяться внутри справочника
  • parent_uid — родитель объекта, в формате uuid. Нужен, только если иерархия не выводится из пути: например, родитель объекта не входит в справочник. Если поле не прислано, родитель определяется по пути
  • kind — вид объекта (section, folder, node и т.п.), не длиннее 32 символов. Используется в интерфейсе; на решение о доступе не влияет

Дополнительно для словаря действий:

  • applicable_objects — массив путей-префиксов объектов, к которым может применяться действие (например ["/documents", "/reports"]). Если не указано или пустой массив — действие применимо ко всем объектам
⚠️ Объект, исчезнувший из словаря

Словарь заменяет ветку приложения целиком: объект, которого нет в присланном списке, из дерева удаляется (если для словаря включено удаление старых узлов). Выданные на него права при этом НЕ удаляются — они помечаются осиротевшими и остаются видны администратору. Если объект вернётся в словарь с тем же uid, пометка снимется, а права снова начнут действовать.

Практические сценарии использования

Сценарий 1: Синхронизация структуры меню

У вас есть приложение с иерархическим меню. Вы хотите, чтобы пользователи имели доступ только к определенным разделам меню в зависимости от их роли.

  1. Настройте в приложении отправку словаря objects со структурой меню
  2. В IDENTYX включите автоматическую обработку словаря объектов
  3. После отправки словаря в IDENTYX автоматически создастся дерево объектов, соответствующее структуре меню
  4. Создайте правила доступа (ACL), назначив пользователям или группам права на конкретные разделы меню
  5. Приложение при авторизации получит список прав через scope permissions и покажет только разрешенные разделы меню

Сценарий 2: Разграничение прав на действия

Вы хотите настроить детальное разграничение прав: одни пользователи могут только просматривать документы, другие — редактировать, третьи — удалять.

  1. Отправьте словарь actions с доступными действиями (read, write, delete)
  2. Отправьте словарь objects с разделами приложения (documents, reports)
  3. В IDENTYX создайте правила доступа в формате объект:действие, например:
    • /app-id/documents:read — разрешить чтение документов
    • /app-id/documents:write — разрешить редактирование документов
    • /app-id/documents:delete — разрешить удаление документов
  4. Приложение проверяет наличие соответствующих прав перед выполнением операций

Сценарий 3: Автообновление при изменениях

Структура вашего приложения меняется — добавляются новые разделы, удаляются старые. Вы хотите, чтобы изменения автоматически отражались в IAM.

  1. Включите автоматическую обработку словарей для приложения
  2. Установите флажок Удалять старые объекты (если хотите удалять неактуальные элементы)
  3. Настройте приложение на периодическую отправку обновленных словарей в IDENTYX
  4. При каждом обновлении структура прав доступа в IAM будет автоматически синхронизироваться с приложением
⚠️ Рекомендация по автоудалению

Перед включением опции Удалять старые объекты убедитесь, что ваше приложение всегда отправляет полный список объектов. Если приложение отправит неполный словарь (например, из-за ошибки), недостающие объекты будут удалены из IAM вместе со всеми настроенными правами доступа.

✅ Готовы продолжить?

Переходите к разделу Обзор учетных записей для изучения управления учетными записями приложений.