Вызов вспомогательных приложений в момент входа#

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

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

обработка запроса на открытие вспомогательного приложения,
возвращение пользователя в Blitz Identity Provider после окончания обработки.

Запрос об открытии приложения#

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

Переход во вспомогательное приложение происходит посредством перенаправления пользователя на предоставленную приложением ссылку. Ссылка в качестве параметра будет содержать код авторизации (code).
Пример ссылки для инициирования запроса#
```
https://<app_hostname>/?lang=ru&theme=default&code=0Tj…qw
```
Приложение должно обменять код авторизации на маркер доступа согласно спецификации OAuth 2.0. Маркер доступа будет использован для получения идентификатора сессии, чтобы вернуть пользователя в Blitz Identity Provider, а также данных пользователя при необходимости.

Пример
Запрос
curl -k -d "grant_type=authorization_code&redirect_uri=https%3A%2F%2Fapp.company.com%2F&client_id=app&client_secret=EW…l0&code=0Tj…qw" -X POST https://login.company.com/blitz/oauth/te
Полученный маркер доступа
{ "access_token": "ey…J9.ey…n0.Wa…Pw", "token_type": "Bearer", "expires_in": 3600, "scope": "profile" }
Важно

Вспомогательное приложение должно быть предварительно зарегистрировано в Blitz Identity Provider с учетом следующих особенностей:
- должен быть указан предопределенный URL возврата, именно он далее должен быть использован для получения токена;
- должны быть настроены разрешения по умолчания (scope), именно они определяют объем данных, получаемых вспомогательным приложением.

Возврат пользователя в Blitz Identity Provider#

Возврат пользователя в Blitz Identity Provider производится следующим образом:

Выполнив необходимые действия (например, показав пользователю информационное сообщение), вспомогательное приложение должно вернуть пользователя в Blitz Identity Provider. Для этого необходимо декодировать полученный маркер доступа, полученный в формате JWT, и извлечь из него утверждение с сессией пользователя (sessionId).
Пример тела декодированного access_token#
```
{
    "scope": "blitz_api_user blitz_api_user_chg blitz_api_usec_chg",
    "jti": "kfP…jA",
    "client_id": "app",
    "exp": 1631026605,
    "sessionId": "ce9f3109-ac79-46b4-b277-099ff1aa1ff0",
    "iat": 1631023005,
    "sub": "8b970179-e141-43b9-b9d5-25997be99261",
    "aud": [
        "app"
    ],
    "crid": "u9th2LzMXZdwb3rRmI3Paw",
    "iss": "https://login.company.com/blitz"
}
```
После декодирования маркера доступа вспомогательное приложение должно сделать POST-запрос на URL обработчика завершения аутентификации Blitz Identity Provider /login/pipe/save/<sessionId>. В теле запроса может быть указан набор утверждений (claims), которые следует добавить в сессию пользователя, либо информация об ошибке (error).
Пример запроса#
```
curl -v --location --request POST 'https://login.company.com/blitz/login/pipe/save/ce9f3109-ac79-46b4-b277-099ff1aa1ff0' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2…ww' \
--data-raw '{"claims":{"org_id":"12345678"}}'
```
В случае успеха Blitz Identity Provider вернет HTTP 204 No Content. Получив его, вспомогательное приложение должно вернуть браузер пользователя по адресу /login/pipe/callback, чтобы пользователь завершил вход в целевое приложение.
Пример ссылки для перенаправления#
```
https://login.company.com/blitz/login/pipe/callback
```

Вызов внешнего приложения#

При необходимости вызвать внешнее приложение Blitz Identity Provider будет делать POST-запрос на URL данного приложения. Приложение должно быть запущено на том же домене, что и Blitz Identity Provider.

Пример запроса#

POST https://login.company.com/consent HTTP/1.1
Content-Type: application/json
Authorization: Basic dG…dk

Пример ответа#

{
 "id": "a9692091-4613-41aa-91d2-9a71a3fc2e07",
 "claims": {"sub":"iivanov","family_name":"Иванов"},
     "requiredScopes": ["openid","profile"]
     "optionalScopes": ["blitz_api_user"]
 "rpId": "test_app",
 "sessionId": "4502aa51-f28c-4a64-951c-5ab1e77b1294",
 "request": {
   "headers": {},
   "remoteAddress": "172.25.0.1",
   "cookies": {},
   "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:80.0)…"
  }
}

Запрос содержит заголовок с Basic-авторизацией. Описание параметров:

id – идентификатор запроса в формате GUID;
sessionId – идентификатор созданной сессии в формате GUID;
rpId – идентификатор приложения, инициировавшего запрос в Blitz Identity Provider;
requiredScopes – перечень согласий (scope), которые обязательно требуются приложением (rpId);
optionalScopes – перечень согласий (scope), которые запрашиваются приложением (rpId), но не обязательны;
claims – утверждения Blitz Identity Provider, характеризующие пользователя;
request – данные о запросе.

Ответ от внешнего приложения с редиректом#

Внешнее приложение должно поставить cookie безопасности с идентификатором сессии на общий с Blitz Identity Provider домен. Также в ответе оно должно указать location для перенаправления в свой интерфейс. Название cookie безопасности должно быть Cac.

Пример ответа#

HTTP/1.1 302 Found
Location:https://login.company.com/consent/begin?id=a9692091-4613-41aa-91d2-9a71a3fc2e07
Set-Cookie:Cac=YTk2OTIwOTEtNDYxMy00MWFhLTkxZDItOWE3MWEzZmMyZTA3; Domain=mos.ru; Secure; HttpOnly

Ответ от внешнего приложения без редиректа#

Если внешнее приложение, получив запрос от Blitz Identity Provider, принимает решение сразу вернуть ответ с перечнем разрешенных согласий (без необходимости отображать веб-интерфейс), то оно может сразу вернуть ответ со статусом HTTP 200 и json со следующими параметрами:

id – идентификатор запроса, берется из исходного запроса;
grantedScopes – перечень согласий (scope), на которые дал согласие пользователь;
status – статус выдачи согласий, в случае успеха принимает значение “granted”.

Пример ответа#

{
   "grantedScopes":[
      "openid",
      "profile"
   ],
   "status":"granted",
   "id":"3e7b-396ae977-4509-a689-bc641e3311b6"
}

Возврат в Blitz Identity Provider из внешнего приложения#

После того, как внешнее приложение сделало все операции, оно должно вернуть пользователя в Blitz Identity Provider и передать перечень выданных пользователей согласий (scope). Для этого оно должно выполнить запрос методом POST на URL Blitz Identity Provider.

Пример запроса в случае успеха#

POST https://login.company.com/sps/oauth/consent/save HTTP/1.1
Content-Type: application/json

Пример ответа#

{
  "id": "a9692091-4613-41aa-91d2-9a71a3fc2e07",
  "extSessionId": "YTk2OTIwOTEtNDYxMy00MWFhLTkxZDItOWE3MWEzZmMyZTA3",
  "grantedScopes": ["openid","profile"],
  "status": "granted",
  "additionalClaims": {"bio_constent":"true"},
  "sessionId": "4502aa51-f28c-4a64-951c-5ab1e77b1294",
}

Параметры запроса:

id и sessionId – значения из исходного запроса;
extSessionId – значение cookie безопасности;
grantedScopes – перечень согласий (scope), на которые дал согласие пользователь
dismissedScopes – перечень согласий (scope), на которые пользователь не дал согласие;
additionalClaims – утверждения (claim) о пользователе, которыми нужно обогатить сессию;
status – статус выдачи согласий. Возможны варианты:
- granted – согласия (scope) выданы;
- dismissed – хотя бы одно обязательное согласие (scope) не выдано;
- error – ошибка при выдаче согласий.

Пример запроса для случая, если обязательное согласие (scope) не выдано#

POST https://login.company.com/sps/oauth/consent/save HTTP/1.1
Content-Type: application/json

Пример ответа#

{
   "id": "a9692091-4613-41aa-91d2-9a71a3fc2e07",
   "extSessionId": "YTk2OTIwOTEtNDYxMy00MWFhLTkxZDItOWE3MWEzZmMyZTA3",
   "dismissedScopes": ["profile","blitz_api_user"],
   "status": "dismissed",
   "sessionId": "4502aa51-f28c-4a64-951c-5ab1e77b1294",
}

Пример запроса при ошибке, возникшей во внешнем приложении#

POST https://login.company.com/sps/oauth/consent/save HTTP/1.1
Content-Type: application/json

Пример ответа#

{
  "id": "a9692091-4613-41aa-91d2-9a71a3fc2e07",
  "extSessionId": "YTk2OTIwOTEtNDYxMy00MWFhLTkxZDItOWE3MWEzZmMyZTA3",
  "status": "error",
  "error_code":"user_not_found",
  "еrror_message":"User not found",
  "sessionId": "4502aa51-f28c-4a64-951c-5ab1e77b1294",
}

В случае успешного сохранения результатов обработки согласий Blitz Identity Provider вернет ответ со статусом HTTP 204 OK. В этом случае внешнее приложение должно выполнить редирект браузера пользователя в Blitz Identity Provider по определенному адресу.

Пример#

https://login.company.com/sps/oauth/consent/callback

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

Вызов вспомогательных приложений в момент входа#

Запрос об открытии приложения#

Возврат пользователя в Blitz Identity Provider#

Вызов приложения выдачи согласия#

Вызов внешнего приложения#

Ответ от внешнего приложения с редиректом#

Ответ от внешнего приложения без редиректа#

Возврат в Blitz Identity Provider из внешнего приложения#