LDAP | Odata V2

Odata V2

Назначение

Модуль «Odata V2» загружает сотрудников и подразделения из внешней системы, которая публикует данные по протоколу OData версии 2 (например, кадровая система на платформе 1С). Сотрудники попадают в Пользователи → Сотрудники, подразделения — в Пользователи → Группы, состав групп заполняется по данным источника. Синхронизация выполняется каждый день автоматически и по кнопке, поэтому списки сотрудников в StopPhish не нужно вести вручную.

Где находится и кому доступно

Меню Odata V2. Пункт виден ролям «Гл. Администратор» и «Администратор», когда модуль установлен.

Рисунок 60 — Пункт меню «Odata V2»

Пункт открывает в новой вкладке браузера отдельное приложение модуля. Вход выполняется под той же учётной записью: если сеанс администратора активен, приложение открывается сразу, иначе показывает свою страницу входа: Email, пароль, код TOTP (если у учётной записи включена двухфакторная аутентификация) и кнопка «Продолжить». Меню приложения слева состоит из одного пункта «Настройки», на этой странице находится блок «OData V2» со списком источников.

Перед началом

Служба OData V2 внешней системы опубликована и доступна с сервера StopPhish по адресу, начинающемуся с http:// или https://. Ответы службы — в формате JSON.
Для подключения подготовлена учётная запись только с правами чтения (логин и пароль) или токен доступа — если служба требует аутентификацию.
Известны названия наборов данных (Entity) с сотрудниками и с подразделениями и названия их свойств: идентификатор, адрес электронной почты, фамилия, имя, отчество, идентификатор подразделения у сотрудника, название подразделения. Названия вводятся точно так, как их отдаёт служба OData, с учётом регистра.
У каждого загружаемого сотрудника заполнен адрес электронной почты: сотрудники без email не загружаются, подразделения без названия — тоже.

Настройка

Список источников

Откройте Odata V2 и в приложении модуля — «Настройки». В таблице перечислены настроенные источники.

Рисунок 61 — Источники OData V2

Обозначение полей:

№	Поле	Что означает	Допустимые значения / по умолчанию
1	Расписание синхронизации	Когда синхронизация запускается автоматически	«Каждый день в 00:00 UTC» (03:00 по московскому времени); не изменяется
2	Синхронизировать сейчас	Запускает синхронизацию всех активных источников сразу	Результат — уведомление (см. «Синхронизация»)
3	Добавить OData V2	Открывает панель «Создать OData V2»	—
4	ID	Номер источника	Присваивается автоматически
5	Имя	Название источника	Задаётся в форме источника
6	URL	Адрес службы OData	Задаётся в форме источника
7	Синхронизация	Состояние источника	Дата и время последней успешной синхронизации в формате «ЧЧ:ММ:СС, ДД.ММ.ГГГГ» по часовому поясу компьютера администратора; у выключенного источника — служебная надпись «disabled»; у включённого, который ещё не синхронизировался, — «not_synced»
8	Изменить	Открывает панель «Изменить OData V2» с настройками источника	—
9	Удалить	Удаляет источник	Браузер спрашивает «Удалить OData V2 '<имя>'?»; после подтверждения источник пропадает из списка и больше не синхронизируется

Подключение источника

Нажмите «Добавить OData V2» или «Изменить» в строке источника. Справа откроется панель «Создать OData V2» или «Изменить OData V2». Верхняя часть формы задаёт подключение к службе.

Рисунок 62 — Подключение к службе OData

Обозначение полей:

№	Поле	Что означает	Допустимые значения / по умолчанию
1	Имя	Название источника: показывается в списке, в уведомлениях о синхронизации и в «Журнале»	Обязательное; не должно совпадать с названием другого источника
2	Активен	Участвует ли источник в синхронизации по расписанию и по кнопке «Синхронизировать сейчас»	По умолчанию включено
3	URL	Базовый адрес службы OData; названия наборов данных (Entity) добавляются к нему, например `https://zup.example.com/hr/odata/standard.odata`	Обязательное; начинается с `http://` или `https://`, иначе под полем — «Введите корректный URL (http://... или https://...)»
4	Способ аутентификации (список в блоке «Параметры Аутентификации»)	Как модуль представляется службе OData	«Без аутентификации» (по умолчанию), «Basic» — логин и пароль, «Bearer» — поле «Токен» с токеном доступа. При смене способа введённые учётные данные очищаются
5	Пользователь	Логин учётной записи для способа «Basic»	Обязательное для «Basic»
6	Пароль	Пароль учётной записи для способа «Basic»	Обязательное для «Basic»
7	Сохранять внешний идентификатор сотрудника	Сохранять у сотрудника StopPhish код из кадровой системы (например, код ЕСК)	По умолчанию выключено
8	Название поля внешнего идентификатора	Свойство сотрудника в службе OData, значение которого сохраняется как внешний идентификатор	Появляется, когда включён переключатель 7; подсказка в пустом поле — «esk_code_physic». Пока поле пустое, идентификатор не сохраняется

Под формой — кнопка «Тестировать» (в рамке) и пояснение «Пользователи без email, а также Группы без имени не будут загружены». Внизу панели — кнопка «Сохранить».

В блоке «Параметры пользователей» укажите, откуда брать сотрудников и какие свойства службы OData соответствуют полям сотрудника StopPhish.

Рисунок 63 — Параметры пользователей

Обозначение полей:

№	Поле	Что означает	Допустимые значения / по умолчанию
1	Entity	Набор данных с сотрудниками, например `Catalog_Сотрудники`	Обязательное
2	Фильтр	Условие отбора сотрудников на языке запросов OData, например `DeletionMark eq false`	Необязательное. Вводите само условие, без «$filter=» из подсказки
3	id	Свойство с уникальным идентификатором сотрудника, например `Ref_Key`	Обязательное. По нему сотрудники сопоставляются с участниками групп
4	Email	Свойство с адресом электронной почты	Обязательное. Сотрудники с пустым адресом не загружаются
5	Имя	Свойство с именем	Необязательное
6	Фамилия	Свойство с фамилией	Необязательное
7	Отчество	Свойство с отчеством	Необязательное
8	ID группы	Свойство сотрудника с идентификатором его подразделения — того же вида, что свойство «id» в блоке «Параметры групп»	Заполните это поле или поле «Участники» в блоке «Параметры групп» (можно оба)

В блоке «Параметры групп» укажите набор данных с подразделениями.

Рисунок 64 — Параметры групп

Обозначение полей:

№	Поле	Что означает	Допустимые значения / по умолчанию
1	Entity	Набор данных с подразделениями, например `Catalog_ПодразделенияОрганизаций`	Обязательное
2	Фильтр	Условие отбора подразделений на языке запросов OData	Необязательное; вводите условие без «$filter=»
3	id	Свойство с уникальным идентификатором подразделения	Обязательное
4	Имя	Свойство с названием подразделения: оно становится названием группы в StopPhish	Обязательное. Подразделения с пустым названием не загружаются
5	Участники	Свойство подразделения со списком идентификаторов участников: сотрудников (значения свойства «id» сотрудника) или других подразделений	Заполните это поле или «ID группы» в блоке «Параметры пользователей». Участники вложенного подразделения входят и в родительскую группу

Нажмите «Тестировать». Кнопка доступна, когда заполнены все обязательные поля. Модуль читает данные из службы OData, ничего не меняя в StopPhish, и показывает уведомление «Успешное подключение» и окно «Результат» с разделами «Пользователи», «Группы» и «Связи». Рядом с каждым разделом — сколько записей пригодно для загрузки из полученных: зелёным — все, жёлтым — часть, красным — ни одной. Щелчок по разделу раскрывает таблицу; строки без email или без названия выделены красным. Если служба недоступна или настройки неверны, появляется уведомление «Не удалось подключиться» с причиной.
Нажмите «Сохранить». Кнопка доступна, когда заполнены все обязательные поля и одно из полей «ID группы» или «Участники». Если закрыть панель без сохранения, изменения не сохраняются.

Синхронизация

Синхронизация запускается каждый день в 00:00 UTC и по кнопке «Синхронизировать сейчас». Обрабатываются все источники с включённым переключателем «Активен», по очереди; ошибка одного источника не останавливает остальные. Для каждого источника модуль:

создаёт и обновляет сотрудников: email, фамилию, имя, отчество и, если включено, внешний идентификатор;
создаёт группы по подразделениям и обновляет их состав. Группы создаются на верхнем уровне, без вложенности: вложенное подразделение становится отдельной группой;
удаляет сотрудников и группы, которые раньше были загружены из этого источника, а в нём больше не встречаются. Удаляются только сотрудники с ролью «Сотрудник»: учётные записи администраторов остаются.

После ручного запуска появляется уведомление «Успешно синхронизировано!» или «Не удалось синхронизировать» со сводкой «Успешно: N. С ошибками: M.» и причиной ошибки для каждого источника. Если лицензия не включает интеграцию с каталогами пользователей, появляется уведомление «Ошибка лицензии» — «Модуль не лицензирован».

Проверка результата

Кнопка «Тестировать» в форме источника показывает, какие сотрудники, группы и связи будут загружены.
После синхронизации в столбце «Синхронизация» появляются дата и время, сотрудники и группы источника видны в Пользователи → Сотрудники и Пользователи → Группы.
Каждая синхронизация источника — успешная или с ошибкой — записывается в Журнал с названием источника в столбце «Субъект».

Ограничения и частые ошибки

«Тестировать» выполняет проверку, только если заполнены и необязательные поля «Имя», «Фамилия», «Отчество» в блоке «Параметры пользователей»; если хотя бы одно пустое, появляется «Не удалось подключиться». Сохранение и синхронизация работают и без этих полей.
Модуль получает список одним запросом. Если служба OData отдаёт список частями (постранично), загружается только первая часть, а сотрудники с остальных частей при синхронизации удаляются как отсутствующие в источнике. Отключите постраничную выдачу на стороне службы или разделите сотрудников фильтрами на несколько источников.
Каждый запрос к службе OData ждёт ответа не дольше 10 секунд. Если служба отвечает дольше, синхронизация источника завершается ошибкой: сократите объём данных фильтром.
Время в столбце «Синхронизация» показывается по часовому поясу компьютера, а расписание задано в UTC: при синхронизации по расписанию в Москве в столбце будет около 03:00.
В столбце «Синхронизация» вместо текста состояния выводятся служебные надписи «disabled» (источник выключен) и «not_synced» (ещё не синхронизировался).
«Не удалось подключиться» при проверке — неверный адрес, учётные данные или название набора данных (Entity) либо служба недоступна с сервера StopPhish. Откройте адрес вида <URL>/<Entity> в браузере с той же учётной записью и сравните названия свойств с введёнными.