Внешняя аутентификация (external)

Запросы

HTTP verb Endpoint Описание

GET

/rest/v1/iam/external

Получение полей для внешней аутентификации

POST

/rest/v1/iam/external

Создание сессии (логин посредством внешней аутентификации)

Получение полей для внешней аутентификации

Запускает сценарий обработки внешней аутентификации. Если сценарий не указан или не найден, запрос возвращает 404 Not Found.

Сценарий, запущенный http-методом GET, должен сгенерировать и отправить в ответе JSON-документ, содержащий типично номер шага и список полей для запроса у пользователя.

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

Запрос

Table 1. Параметры запроса
Спецификация Описание

Имя: step
Тип: str

Номер шага. Необязательный параметр. Интерпретация параметров зависит от установленного сценария обработки внешней аутентификации.

Имя: <произвольное имя>
Тип: str

Произвольные параметры. Интерпретация параметров зависит от установленного сценария обработки внешней аутентификации.

Пример запроса
GET /rest/v1/iam/external?step=1 HTTP/1.1

Ответ

Пример ответа
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "fields": [
    {
      "name": "step",
      "value": 1,
      "type": "hidden"
    },
    {
      "name": "domain",
      "title": "Домен",
      "type": "line"
    },
    {
      "name": "login",
      "title": "Логин",
      "type": "line"
    }
  ]
}

Создание сессии (логин посредством внешней аутентификации)

Производит внешнюю аутентификацию пользователя в домене с помощью сценария обработки внешней аутентификации. Если сценарий не указан или не найден, запрос возвращает 404 Not Found.

Для аутентификации пользователя сценарий может либо использовать проверку пароля пользователя в компоненте Операция, либо делать вызовы к внешнему сервису, который должен вернуть имя домена и логин или id пользователя после подтверждения его личности.

Сценарий, запущенный http-методом POST, должен интерпретировать посланные ему данные, произвести аутентификацию пользователя и вернуть в ответе следующий управляющий JSON-документ, в соответствии с которым веб-приложение должно повести себя определённым образом:

  • снова отобразить форму с полями, возможно на том же шаге для исправления или на другом шаге с новым набором полей;

  • отказать пользователю по причине невалидности введённых данных и предложить ссылку на повтор аутентификации;

  • определить факт создания сессии по ответу сценария по заголовку set-cookie и перенаправить пользователя на предопределённый или указанный в ответе сценария адрес где отобразится приложение главного экрана. При этом реализация сценария может перенаправлять пользователя на разные приложения главного экрана в зависимости от различных условий (напр., истекающая лицензия).

Для создания новой веб-сессии (после проверки пароля либо получения подтверждения от внешнего сервиса) сценарий использует компонент Операция / Тип "Внешняя аутентификация" / Метод "Создание сессии".

В дальнейшем все запросы, содержащие cookie RSession с идентификатором сессии, ассоциируются с этой сессией.

Для защиты от перебора учётных данных пользователя (паролей, токенов, кодов и т.д.) сценарий использует компонент Операция / Тип "Внешняя аутентификация" / Метод "Добавление в wsban".

Запрос первого шага

Table 2. Параметры запроса
Спецификация Описание

Имя: step
Тип: any

Шаг авторизации. Параметр скрыт для пользователя, но присутствует в форме и должен быть отправлен веб-приложением вместе с другими полями.

Имя: domain
Тип: str

Домен для авторизации.

Имя: login
Тип: str

Логин учетной записи пользователя в домене.

Пример запроса
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"
    }
  ]
}

Запрос второго шага

Table 3. Параметры запроса
Спецификация Описание

Имя: step
Тип: any

Шаг авторизации. Параметр скрыт для пользователя, но присутствует в форме и должен быть отправлен веб-приложением вместе с другими полями.

Имя: domain
Тип: str

Домен для авторизации. На втором шаге параметр скрыт для пользователя, но присутствует в форме и должен быть отправлен веб-приложением вместе с другими полями.

Имя: login
Тип: str

Логин учетной записи пользователя в домене. На втором шаге параметр скрыт для пользователя, но присутствует в форме и должен быть отправлен веб-приложением вместе с другими полями.

Имя: phone_sms_code
Тип: str

Код, полученный пользователем на привязанный телефонный номер от внешней системы или сценария внешней аутентификации.

Пример запроса
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/"
}

Модель внешней аутентификации

На диаграмме отображена принципиальная последовательность взаимодействия веб-приложения, сценария и внешнего сервиса аутентификации. Веб-приложение и сценарий общаются по протоколу, где веб-приложение выполняет функцию отображения формы и выполняет ввод данных от пользователя, а сценарий содержит логику взаимодействия с внешним сервисом и обслуживает запросы веб-приложения.

В пределах этого сценария будут работать операции внешней аутентификации в компоненте Операция.

assets_categories

Ссылки

Настройки

Компоненты

Функциональные роли