Внешняя аутентификация (external)
Запросы
| HTTP verb | Endpoint | Описание |
|---|---|---|
|
|
|
|
|
Получение полей для внешней аутентификации
Запускает сценарий обработки внешней аутентификации.
Если сценарий не указан или не найден, запрос возвращает 404 Not Found.
Сценарий, запущенный http-методом GET, должен сгенерировать и отправить в ответе JSON-документ, содержащий типично номер шага и список полей для запроса у
пользователя.
Веб-приложение, получившее такой документ, должно отобразить пользователю форму и отправить список заполненных полей методом POST.
Запрос
| Спецификация | Описание |
|---|---|
|
Номер шага. Необязательный параметр. Интерпретация параметров зависит от установленного сценария обработки внешней аутентификации. |
|
Произвольные параметры. Интерпретация параметров зависит от установленного сценария обработки внешней аутентификации. |
GET /rest/v1/iam/external?step=1 HTTP/1.1Создание сессии (логин посредством внешней аутентификации)
Производит внешнюю аутентификацию пользователя в домене с помощью сценария обработки внешней аутентификации.
Если сценарий не указан или не найден, запрос возвращает 404 Not Found.
Для аутентификации пользователя сценарий может либо использовать проверку пароля пользователя в компоненте Операция, либо делать вызовы к внешнему сервису, который должен вернуть имя домена и логин или id пользователя после подтверждения его личности.
Сценарий, запущенный http-методом POST, должен интерпретировать посланные ему данные, произвести аутентификацию пользователя и вернуть в ответе следующий
управляющий JSON-документ, в соответствии с которым веб-приложение должно повести себя определённым образом:
-
снова отобразить форму с полями, возможно на том же шаге для исправления или на другом шаге с новым набором полей;
-
отказать пользователю по причине невалидности введённых данных и предложить ссылку на повтор аутентификации;
-
определить факт создания сессии по ответу сценария по заголовку set-cookie и перенаправить пользователя на предопределённый или указанный в ответе сценария адрес где отобразится приложение главного экрана. При этом реализация сценария может перенаправлять пользователя на разные приложения главного экрана в зависимости от различных условий (напр., истекающая лицензия).
Для создания новой веб-сессии (после проверки пароля либо получения подтверждения от внешнего сервиса) сценарий использует компонент Операция / Тип "Внешняя аутентификация" / Метод "Создание сессии".
В дальнейшем все запросы, содержащие cookie RSession с идентификатором сессии, ассоциируются с этой сессией.
Для защиты от перебора учётных данных пользователя (паролей, токенов, кодов и т.д.) сценарий использует компонент Операция / Тип "Внешняя аутентификация" / Метод "Добавление в wsban".
Запрос первого шага
| Спецификация | Описание |
|---|---|
|
Шаг авторизации. Параметр скрыт для пользователя, но присутствует в форме и должен быть отправлен веб-приложением вместе с другими полями. |
|
Домен для авторизации. |
|
Логин учетной записи пользователя в домене. |
POST /rest/v1/iam/external HTTP/1.1
Content-Type: application/json; charset=utf-8
{"step":1,"domain":"tele.dom","login":"username"}Ответ первого шага
HTTP/1.1 200 OK
{
"success": true,
"complete": false,
"next_step": 2,
"fields": [
{
"name": "step",
"value": 2,
"type": "hidden"
},
{
"name": "domain",
"value": {"from":{"step":1}},
"type": "hidden"
},
{
"name": "login",
"value": {"from":{"step":1}},
"type": "hidden"
},
{
"name": "sms_phone_code",
"title": "Код из SMS",
"type": "line"
}
]
}Запрос второго шага
| Спецификация | Описание |
|---|---|
|
Шаг авторизации. Параметр скрыт для пользователя, но присутствует в форме и должен быть отправлен веб-приложением вместе с другими полями. |
|
Домен для авторизации. На втором шаге параметр скрыт для пользователя, но присутствует в форме и должен быть отправлен веб-приложением вместе с другими полями. |
|
Логин учетной записи пользователя в домене. На втором шаге параметр скрыт для пользователя, но присутствует в форме и должен быть отправлен веб-приложением вместе с другими полями. |
|
Код, полученный пользователем на привязанный телефонный номер от внешней системы или сценария внешней аутентификации. |
POST /rest/v1/iam/external HTTP/1.1
Content-Type: application/json; charset=utf-8
{"step":2,"domain":"tele.dom","login":"username","phone_sms_code":"3387ab"}Ответ второго шага
HTTP/1.1 302 Found
set-cookie: RSession=6ef97511-0178-a21d-bd9a-e0d55e0cd303; Expires=Mon, 19 Apr 2021 12:59:21 GMT; Path=/; SameSite=Strict
location: /app-index/Протокол взаимодействия веб-приложения и сценария может предусматривать различные способы сигнализации успешности создания сессии и передачи данных — идентификатора сессии и ссылки для перенаправления в приложение главного экрана.
В примере выше сигналом успешности создания сессии является код ответа 302, а также наличие заголовка set-cookie с именем RSession и датой в будущем, а
ссылка для перенаправления содержится в заголовке location.
Альтернативой может служить возврат JSON-документа с соответствующими полями:
HTTP/1.1 200 OK
set-cookie: RSession=6ef97511-0178-a21d-bd9a-e0d55e0cd303; Expires=Mon, 19 Apr 2021 12:59:21 GMT; Path=/; SameSite=Strict
content-type: application/json; charset=utf-8
{
"success": true,
"complete": true,
"location": "/app-index/"
}Модель внешней аутентификации
На диаграмме отображена принципиальная последовательность взаимодействия веб-приложения, сценария и внешнего сервиса аутентификации. Веб-приложение и сценарий общаются по протоколу, где веб-приложение выполняет функцию отображения формы и выполняет ввод данных от пользователя, а сценарий содержит логику взаимодействия с внешним сервисом и обслуживает запросы веб-приложения.
В пределах этого сценария будут работать операции внешней аутентификации в компоненте Операция.
