Дополнительный метод аутентификации#

Blitz Identity Provider позволяет подключить собственный разработанный метод аутентификации. Для этого система, выступающая в качестве поставщика такого метода аутентификации, должна:

предоставить обработчик запроса на аутентификацию;
передать в Blitz Identity Provider результат аутентификации;
предоставить сервис проверки применимости метода аутентификации Опционально.

В Blitz Identity Provider разработанный метод аутентификации нужно зарегистрировать как внешний метод аутентификации.

Сервис обработчика запроса#

Взаимодействие Blitz Identity Provider с сервисом обработчика запроса на аутентификацию выполняется следующим образом:

Сервис обработчика представляет собой URL для приема HTTP-запросов от Blitz Identity Provider. При запросе на аутентификацию Blitz Identity Provider будет делать запрос методом POST по данному адресу.

В теле запроса Blitz Identity Provider в формате JSON передаст следующие данные:
- идентификатор запроса (id);
- утверждения, характеризующие пользователя (claims) – опционально, только при вызове в качестве второго фактора;
- идентификатор системы, запросивший вход (rpId);
- идентификатор контекста аутентификации (loginContextId);
- данные о запросе (request), включающий в себя заголовки (headers), IP-адрес пользователя (remoteAddress), адрес метода (uri), перечень cookie (cookies) и User Agent пользователя (userAgent).
Пример тела запроса#
```
{
    "id": "a9692091-4613-41aa-91d2-9a71a3fc2e07",
    "claims": {},
    "rpId": "_blitz_profile",
    "loginContextId": "4502aa51-f28c-4a64-951c-5ab1e77b1294",
    "request": {
      "headers": {},
      "remoteAddress": "172.25.0.1",
      "uri": "/blitz/login/methods2/outside_test",
      "cookies": {},
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:80.0)…"
    }
}
```

На стороне поставщика внешнего метода необходимо предусмотреть обработку запроса Blitz Identity Provider. В результате внешний метод должен вернуть:

Если аутентификация возможна - HTTP-ответ для выполнения в браузере пользователя, который, например, содержит код HTML-страницы или инициирует редирект браузера на необходимую страницу внешнего метода.
Ошибку в случае невозможности провести аутентификацию пользователя.

Требования к обработке запроса Blitz Identity Provider

HTTP-ответ

ответ должен включать в себя установку cookie (на общий домен Blitz Identity Provider и внешнего метода);
название cookie должно быть предварительно зарегистрировано в Blitz Identity Provider;
в качестве значения cookie должен быть использован идентификатор сессии, сгенерированный внешним методом.

Пример HTTP-ответа с редиректом и установкой cookie#

HTTP/1.1 302 Found
Location: https://login.company.com/blitz/begin?id=a9692091-4613-41aa-91d2
Set-Cookie: Bmr=YTk2OTIwOTEtNDYxMy00MWFhLTkxZDItOWE3MWEzZmMyZTA3; Domain=company.com; path=/blitz; Secure; HttpOnly

Важно

При прохождении внешнего метода поставщик должен проверить, что значение cookie для данного запроса не было изменено.

Ошибка

Рекомендуемые коды возврата:

Код ответа HTTP	Значение ответа	Описание ответа
`200`	`OK`	Инициирование внешнего метода посредством отображения контента страницы
`302`	`Found`	Инициирование внешнего метода посредством редиректа
`400`	`Bad Request`	Отсутствуют обязательные параметры запроса
`500`	`Internal Server Error`	Внутренняя ошибка обработки входящего запроса

Передача результата аутентификации#

После прохождения внешнего метода поставщик должен выполнить следующие действия:

Серверная часть поставщика должна вызвать Blitz Identity Provider методом POST по адресу:
```
https://login.company.com/blitz/login/methods/outside/save?methodName=outside\_{name}
```
В данном запросе name – это имя внешнего метода, присвоенное ему в Blitz Identity Provider при регистрации.

Тело запроса
Успешная аутентификация
В случае успеха аутентификации в теле запроса должны быть указаны:
- идентификатор запроса (id);
- extSessionId – идентификатор сессии, сгенерированный внешним методом. Идентификатор должен совпадать со значением, переданным в исходном запросе в cookie;
- claims – перечень утверждений, которыми нужно обогатить сессию пользователя. Перечень может быть пустым;
- subjectId – идентификатор пользователя (только для первого фактора; при вызове внешнего метода в качестве второго фактора нельзя передавать идентификатор пользователя);
- loginContextId – идентификатор контекста аутентификации, соответствующий исходному запросу.
Пример запроса#
POST /blitz/login/methods/outside/save?methodName=outside_test HTTP/1.1 Content-Type: application/json { "id": "426b5139-e4f7-41e6-a206-9503de6f34dd", "extSessionId": "YTk2OTIwOTEtNDYxMy00MWFhLTkxZDItOWE3MWEzZmMyZTA3", "claims": {}, "loginContextId": "3ca4d1f0-654a-4665-be98-d105ab6ec35d", "subjectId": "2db787c7-6e37-4018-abe9-2bea1011c047" }
Ошибка аутентификации
В случае ошибки в теле запроса должны быть указаны:
- id – идентификатор запроса;
- extSessionId – идентификатор сессии, сгенерированный внешним методом. Идентификатор должен совпадать со значением, переданным в исходном запросе в cookie;
- error – код ошибки;
- msg – текстовое описание ошибки (опционально).
Пример запроса#
POST /blitz/login/methods/outside/save?methodName=outside_test HTTP/1.1 Content-Type: application/json { "id": "426b5139-e4f7-41e6-a206-9503de6f34dd", "extSessionId": "YTk2OTIwOTEtNDYxMy00MWFhLTkxZDItOWE3MWEzZmMyZTA3", "error": "not_found", "msg": "User not found" }
В случае сохранения результатов аутентификации (как успешной, так и неуспешной) Blitz Identity Provider возвращает ответ HTTP 200 OK.
Браузерная часть поставщика должна обеспечить перенаправление пользователя обратно в Blitz Identity Provider. Для этого необходимо перенаправить браузер по адресу:
```
https://login.company.com/blitz/login/methods/outside/callback?methodName=outside\_{name}
```
В данном запросе name – это имя внешнего метода, присвоенное ему в Blitz Identity Provider при регистрации.

Сервис проверки метода#

Сервис проверки применимости метода аутентификации представляет собой URL для приема HTTP-запросов от Blitz Identity Provider. До запроса на аутентификацию Blitz Identity Provider будет делать запрос методом POST по данному адресу, передав в теле в формате JSON те же данные, что и в запросе на аутентификацию.

В качестве ответа внешний метод должен вернуть JSON со следующими атрибутами:

идентификатор запроса (id);
результат проверки применимости (result), принимающий значение либо true (метод применим) или false (метод неприменим);
идентификатор контекста аутентификации (loginContextId), соответствующий запросу.

Если сервис вернет false в качестве результата проверки применимости, то далее Blitz Identity Provider не будет выполнять запрос на аутентификацию для данного пользователя.