Рекомендации разработчикам по вызову сервисов регистрации и изменения данных пользователя

Общие сведения

В Blitz Identity Provider предусмотрен ряд REST-сервисов, позволяющих выполнять следующие операции:

  • регистрация пользователя;
  • изменение данных пользователя;
  • привязка генераторов разовых паролей, работающих по алгоритму HOTP и TOTP.

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

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

  • нажать «Добавить приложение»;
  • указать идентификатор, название и домен системы;
  • нажать «Сохранить».

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

  • пароль – будет использоваться при HTTP Basic-аутентификация, в качестве логина – идентификатор системы-клиента; если параметр не задан, то HTTP Basic-аутентификация не будет возможна для данной системы-клиента;
  • допустимые CN – перечень значений атрибута CN сертификата, используемого при TLS-аутентификация; если не заданы параметры, то TLS-аутентификация не будет возможна для данной системы-клиента.

Настройка приложения с использованием консоли (протокол REST)

Вызов сервиса регистрации нового пользователя

Инициирование регистрации в Blitz Identity Provider нового пользователя осуществляется методом PUT по адресу /blitz/reg/api/v1/users. Запрос включает в себя заголовок (header) для проведения HTTP Basic авторизации.

В теле запроса указывается json, имеющий вид {"attr": value}, где:

  • attr – название атрибута. Оно должно соответствовать одному из атрибутов, определенных в разделе Источники данных консоли управления;
  • value – значение атрибута.

Если в числе передаваемых атрибутов присутствует атрибут, требующий подтверждения (например, адрес электронной почты), то на него будет отправлено письмо с колом подтверждения.

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

PUT /blitz/reg/api/v1/users HTTP/1.1
Host: <hostname>
Authorization: Basic cmVzdF90ZXN0Om9yYWNsZV8x
Content-Type: application/json
Cache-Control: no-cache

{"surname": "Петров",
"name": "Иван",
"password":"nk%_NhNu"
}

Возможны следующие результаты успешного исполнения запроса:

  • пользователь зарегистрирован успешно. В этом случае будет возвращен идентификатор пользователя (subject). Пример ответа:
{
    "subject": "BIP-E3RKU2Y",
    "instructions": [],
    "context": "ZepajBu88kWx88FgY9U1me6yu3hAN84du_RTUmIwxeMO1jtFYVZ5h5rbWYYr3Cb7bUt2BcdRRG-lcnFUsasFeQ"
}
  • создана заявка на регистрацию пользователя. В этом случае в атрибуте instructions содержится инструкция по завершению регистрации. Например, ниже приведен ответ для случая, когда для завершения регистрации пользователь должен воспользоваться ссылкой из письма, отправленной на электронную почту:
{
    "subject": "BIP-XP437MA",
    "instructions": [
        {
            "email": "mail@example.com",
            "exp": 1522858133,
            "attemts": 3,
            "name": "eml-enter-code"
        }
    ],
    "context": "4Df72jdlWPU9OAR3hxdYgEDDE-qbr6LVjH9p8yBEmqkhKEGQ9rqHWFu0jlZaGVdHQ97pZit1d1YbLVVyydsNTQ"
}

При наличии ошибки возможны следующие ответы сервиса:

  • статус 401 (Unauthorized) – система-клиент не зарегистрирована или неверно произведена его авторизация;
  • статус 400 (Bad request) – отправлены некорректные данные;
  • статус 500 (Internal Server Error) – возникла внутренняя ошибка сервера.

В тех случаях, когда это возможно, сервис также возвращает json, содержащий тип и описание ошибки. Пример ответа:

{
    "errors": [
        {
            "errMsg": "Пользователь с таким значением уже зарегистрирован. Для дальнейшей регистрации введите другое значение",
            "field": "mail"
        }
    ],
    "context": ""
}

Вызов сервиса изменения данных пользователя

Поиск данных пользователя

Для изменения данных пользователя необходимо предварительно его найти, чтобы узнать идентификатор версии данных пользователя. Поиск данных пользователя осуществляется методом GET по адресу /blitz/api/v1/users?query={attr}={query}, где attr – имя атрибута, по которому необходимо осуществлять поиск, а query – его значение (можно использовать символ * для поиска по маске). Запрос включает в себя заголовок (header) для проведения HTTP Basic авторизации.

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

GET /blitz/api/v1/users?query=personal_mail=k* HTTP/1.1
Host: <hostname>
Authorization: Basic cmVzdF9kZWDAxOm9yYWNV8x
Content-Type: application/json
Cache-Control: no-cache

В качестве ответа сервис возвращает все учетные записи, соответствующие поисковому запросу, в виде json-объектов. Например:

[
    {
        "instanceId": "ZGV2LWhhbGRhcDp1aWQ9QklQLVlNUzZXWUEsb3U9c3ViLGRjPWRldixkYz1yZWF4b2Z0LGRjPWxvYw",
        "attrs": {
            "personal_mail": "ksidor@identityblitz.com",
            "personal_mobile": "+7(999)1234567",
            "locked": false,
            "uid": "BIP-YMS6WYA"
        },
        "readOnly": false
    },
    {
        "instanceId": "ZGV2LWhhbGRhcDp1aWQ9QklQLVk0SlJKRkEsb3U9c3ViLGRjPWRldixkYz1yZWF4b2Z0LGRjPWxvYw",
        "attrs": {
            "personal_mail": "kgav@reaxoft.ru",
            "personal_mobile": "+7(999)7654321",
            "locked": false,
            "uid": "BIP-Y4JRJFA"
        },
        "readOnly": false
    },
    {
        "instanceId": "ZGV2LWhhbGRhcDp1aWQ9QklQLVhQNDM3TUEsb3U9YmlwLWRlbW8yLG91PXN1YixkYz1kZXYsZGM9cmVheG9mdCxkYz1sb2M",
        "attrs": {
            "personal_mail": "kag@gmail.com",
            "name": "Иван",
            "surname": "Петров",
            "locked": false,
            "uid": "BIP-XP437MA"
        },
        "readOnly": false
    }
]

Каждая учетная запись характеризуется следующими признаками:

  • attrs – набор атрибутов пользователя;
  • instanceId – идентификатор версии данных пользователя;
  • readOnly – признак доступности данных пользователя только для чтения (принимает значение только true/false);
  • unmodifiable – перечень атрибутов, которые не могут быть изменены.

Отображение данных конкретного пользователя

В ряде случаев возникает необходимость получить данные конкретного пользователя по его идентификатору версии. Этот запрос также позволяет получить актуальный идентификатор версии, если он изменился. Для этого следует выполнить запрос методом GET по адресу /blitz/api/v1/users/{instanceId}, где instanceId – идентификатор версии данных пользователя. Запрос включает в себя заголовок (header) для проведения HTTP Basic авторизации.

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

GET /blitz/api/v1/users/ZGV2LWhhbGRhcDp1aWQ9QklQLVk0SlJKRkEsb3U9c3ViLGRjPWRldixkYz1yZWF4b2Z0LGRjPWxvYw HTTP/1.1
Host: bip-demo1.reaxoft.ru
Authorization: Basic cmVzdF9kZW1vX2FwcDAxOm9yYWNsZV8x
Content-Type: application/json
Cache-Control: no-cache

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

{
    "instanceId": "ZGV2LWhhbGRhcDp1aWQ9QklQLVk0SlJKRkEsb3U9c3ViLGRjPWRldixkYz1yZWF4b2Z0LGRjPWxvYw",
    "attrs": {
        "personal_mail": "kgav@reaxoft.ru",
        "personal_mobile": "+7(999)7654321",
        "locked": false,
        "uid": "BIP-Y4JRJFA"
    },
    "readOnly": false
}

Изменение данных пользователя

Запрос на изменение данных пользователя осуществляется методом POST по адресу /blitz/api/v1/users. Запрос включает в себя заголовок (header) для проведения HTTP Basic авторизации, а в теле запроса json, содержащий следующие данные:

  • instanceId – идентификатор версии данных пользователя;
  • replaced – перечень атрибутов и их значения, которые должны быть изменены или добавлены;
  • deleted – перечень атрибутов, которые должны быть удалены.

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

POST /blitz/api/v1/users HTTP/1.1
Host: bip-demo1.reaxoft.ru
Authorization: Basic cmVzdF9kZW1vX2FwcDAxOm9yYWNsZV8x
Content-Type: application/json
Cache-Control: no-cache

{
    "instanceId": "ZGV2LWhhbGRhcDp1aWQ9QklQLVk0SlJKRkEsb3U9c3ViLGRjPWRldixkYz1yZWF4b2Z0LGRjPWxvYw",
    "replaced": {
        "name": "Иван",
        "surname": "Петров"},
    "deleted": ["personal_mail"]
}

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

Если атрибут не указан в запросе, то он не изменяется.

Если запрос выполнен успешно, то сервис вернет статус 200 ОК.

При наличии ошибки возможны следующие ответы сервиса:

  • статус 401 (Unauthorized) – система-клиент не зарегистрирована или неверно произведена его авторизация;
  • статус 400 (Bad request) – отправлены некорректные данные;
  • статус 404 (Not found) – пользователь с указанным в запросе идентификатором не найден;
  • статус 500 (Internal Server Error) – возникла внутренняя ошибка сервера.

В тех случаях, когда это возможно, сервис также возвращает json, содержащий тип и описание ошибки.

Привязка HOTP/TOTP-генератора к учетной записи пользователя

С использованием API приложение может назначить пользователю HOTP/TOTP аппаратный ключ для осуществления двухфакторной аутентификации.

Запрос на привязку HOTP/TOTP-генератора кодов к учетной записи пользователя осуществляется методом PUT по адресу /blitz/rest/usr/{username}/attach/hotp, где username – имя (идентификатор пользователя). Запрос включает в себя заголовок (header) для проведения HTTP Basic авторизации, а в теле запроса json, имеющий вид:

{
    "serial" : "AN064433",
    "otp1" : "200299",
    "otp2" : "136915",
    "otp3" : "024689"
}

где:

  • serial – значение серийного номера HOTP-генератора;
  • otp1, otp2, otp3 – значение последовательности трех разовых кодов HOTP-устройства.

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

PUT: /blitz/rest/usr/ivanov/attach/hotp
Host: demo.identityblitz.ru
Authorization: Basic bWFudWFsLXRlc3QtY2xpZW50OjEyMzQ1Njc4OTA=
Content-Type: application/json
Cache-Control: no-cache

{
    "serial" : "AN064433",
    "otp1" : "200299",
    "otp2" : "136915",
    "otp3" : "024689"
}

Должна осуществляться только привязка тех HOTP/TOTP-генераторов, по которым в Blitz Identity Provider предварительно администратор выполнил загрузку файла с описанием устройств, полученный от производителя.