- Общая информация по технологии
- Базовая информация по интеграции
- Пример 1: HDE + OneLogin
- Пример 2: HDE + Okta
- Режим отладки в HDE
- Настраиваемые атрибуты: departments_ids, custom_group_id, custom_departments_ids. Маппинг групп и департаментов.
1. ОБЩАЯ ИНФОРМАЦИЯ
SSO (Single Sign-On) - технология единого входа пользователей, благодаря которой владея одной лишь учетной записью пользователь может посещать множество различных сервисов.
SAML - это популярный XML-протокол для реализации SSO. Как правило используется в больших организациях (enterprise) как проверенный и надежный вариант. В организациях где централизованно ведется актуальная база пользователей, вводятся свои политики безопасности и т.п. Соответственно и доступ к контенту в сервисе становится более безопасным и контролируемым.
В аутентификации через SAML SSO участвует три стороны:
- SAML identity Provider (IdP)
- SAML Service Provider (SP)
- браузер пользователя (User Agent)
Сама схема взаимодействия представлена на рисунке ниже:
Более подробно с технологией можно ознакомиться на просторах интернета.
2. БАЗОВАЯ ИНФОРМАЦИЯ
- Логин происходит по почте, NameID описан в metadata
- Имеются 3 кастомных параметра (необязательные, если не указать - они не будут обновляться):
- group_id - число, позволяет менять группу на авторизации
- organization - строка, организация меняется на авторизации
- name - строка, полное имя, может меняется на авторизации
Авторизовать можно двумя способами:
- логин из системы - дополнительная кнопка входа в систему на форме входа:
- авторизация из самого сервиса:
3. Пример подключения интеграции через сервис OneLogin (onelogin.com)
На текущий момент выполнить интеграцию с HelpDeskEddy возможно через настройку и подключение тестового коннектора SSO SAML, предоставленного сервисом OneLogin. В планах имеется добавление собственного приложения-коннектора HelpDeskEddу и интеграция таким образом упростится до нескольких кликов.
1. Создаем аккаунт в сервисе OneLogin (почта может быть только в корпоративном домене, никаких gmail или mail.ru)
2. Переходим в Администрирование:
3. И добавляем приложение:
4. Ищем в поиске по saml test и выбираем SAML Test Connector (Advanced):
5. Далее необходимо будет задать название коннектора, по необходимости его описание и сохранить:
6. После сохранения станут доступны другие настройки коннектора.
Затронем основные настройки, касающиеся интеграции с HelpDeskEddy.
Настройки на стороне сервиса OneLogin, которые берутся из HDE (SP):
- RelayState (необязательное) - ссылка для перенаправления в случае если авторизация была из сервиса. Можно оставлять пустой, а можно например указать прямую ссылку на Омниканальность или КБ (если есть необходимость).
- Audience (EntityID) - поле куда вставляем metadata из HDE, он же "Audience Restriction" вставляем поле "Audience (EntityID)" из SSO соединения в HDE.
- Recipient - приёмник вызовов на логин, он же - "Single Sign On URL" или "ACS" или "Assertion consumer service URL", в это поле вставляем "Assertion consumer service URL (ACS)" из HDE.
- ACS (Consumer) URL Validator* - валидатор ссылки (защита). По умолчанию ставим .* (точка + звездочка)
- ACS (Consumer) URL* - вызов на логин от сервиса. В это поле добавляем "Assertion consumer service URL (ACS)" из HDE.
- Single Logout URL - ссылка для вызова на logout (выход), это "Single logout URL" из HDE. На эту ссылку уходит вызов при выходе из сервиса в фоне (везде работает по разному). Также на эту ссылку переходит пользователь после успешного выхода через кнопку логаута в HDE
Эти данные берутся из HDE создав SSO соединение:
Настройки на стороне HDE (ldP), которые берутся их OneLogin (Applications - Connector - SSO):
Использована терминология Onelogin, поля указаны цифрами для удобства
- Issuer URL - метаинформация, по этой ссылке находятся все нужные точки для соединения. В HDE поле называется также.
- SAML 2.0 Endpoint (HTTP) - ссылка, по которой HDE направляет пользователя для авторизации в сервисе. В HDE поле называется также.
- SLO Endpoint (HTTP) - ссылка, по которой HDE отправляет выход из системы. В HDE поле называется также.
- Cертификат - есть и другие методы защиты, но на текущий момент в HDE используется только X.509 Certificate
Добавляем эти данные в SSO соединение в HDE:
7. Кастомные поля HDE + OneLogin:
4. Пример подключения интеграции через сервис Okta (okta.com)
1. Регистрируемся, заходим в аккаунт и создаем приложение:
Настройки Okta:
1) Single sign on URL - ссылка на вход в сервис, это "Assertion consumer service (ACS)" в HDE. Если галочку здесь не ставим - появится еще одно поле Recipient URL - его тоже можно заполнить той же ссылкой.
2) Audience URI (SP Entity ID) - метадата, вставляем поле "Audience (EntityID)" из HDE.
3) Single Logout URL - okta не интересны выходы со стороны HDE. НО они могут выкинуть пользователя из системы когда выходишь с их приложения, соответственно настройка по желанию (можно не использовать) - поле Single logout service (SLS) из HDE. Так как Okta не поддерживает полноценно SLO, можно вставить ссылку с окончанием /slo вместо /sls . Разница будет в том, что пользователь сразу вылетит из системы, а если на стороне HDE ссылка SLO не указана - просто произойдёт переход на старт HDE.
4) SP Issuer - поле Single logout service (SLS) из HDE. Он обязательный если используется SLO.
5) Сертификат, его нужно скачать если используем SLO и закинуть в 6 пункт.
6) Поле загрузки сертификата из пункта 5.
Настройки в HDE.
Необходимые для внесение настройки на стороне HDE можно найти в настройках созданного приложения:
1) RelayState - это поле можно не указывать. Если указать - туда будет перенаправлен пользователь после авторизации в HDE.
2) Ссылка на метадату и сертификат. При переходе на View Setup Instructions откроются необходимые нам данные (см. следующий скриншот)
далее переходим в инструкции.
3) Ставим email.
View Setup Instructions:
2.1) Identity Provider Single Sign-On URL = SAML 2.0 Endpoint (HTTP) в HDE
2.2) Identity Provider Single Logout URL = SLO Endpoint (HTTP) в HDE
2.3) Identity Provider Issuer = Issuer URL в HDE
2.4) Сертификат - вставляем сертификат в HDE
После сохранения настроек и добавления пользователей для данного приложение получится войти в систему через сервис Okta:
5. РЕЖИМ ОТЛАДКИ В HDE
При активации режима отладки в лог при авторизации будут записаны передаваемые атрибуты.
Может послужить помощником при настройке новых подключений, отображая какая именно информация поступает в HDE.
Пример:
Активируется по кнопке Режим отладки в подключении SSO в HDE
+
6. НАСТРАИВАЕМЫЕ АТРИБУТЫ
departments_ids - возможность задать список доступов к департаментам. Воспринимает массивы. Передаются ID департаментов в HDE.
Маппинг групп и департаментов:
Одну группу или департамент можно определить за разными ролями, или наоборот, разные роли из SSO могут назначать одну и ту же группу в HDE.
Активируется по кнопке - Включить настраиваемые атрибуты
разделитель многозначного атрибута - параметр используется, если передача строчная, например разделитель запятая и передается строка "role,role2,role3". Если передается не строка - будет читаться только первый параметр и будет попытка его поделить.
custom_group_id - позволяет назначить группу пользователю в зависимости от ролей SSO. Работает по первому совпадению роли из SSO. Здесь важен порядок выставленных пар группа - роль в HD
Т.е. при передаче custom_group_id = "admin;manager;operator" пользователь получит группу Сотрудник, т.к. она более приоритета в списке.
custom_departments_ids - позволяет выставить доступы к департаментам на основании ролей SSO. Добавляет все департамента из всех переданных ролей. Порядок значения не имеет.
Т.е. при передаче custom_departments_ids = "operator;manager" пользователь получит доступы к 7 департаментам, т.е. для обоих совпадений по "департаменты - роль".
Пример настроек на стороне OKTA.
В настройках приложения в разделе SAML Settings добавляем объявление переменных и указываем на какие переменные они должны ссылаться - https://support.okta.com/help/s/article/How-to-define-and-configure-a-custom-SAML-attribute-statement?language=en_US
Предварительно эти самые поля необходимо будет создать:
И соответственно прописать нужные значения для учетных записей: