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

Версии REST API#

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

Предупреждение

Сервисы версий v1 и v2 после появления аналогов в более новой v3 будут помечены как устаревшие, и будет рекомендовано перейти с их использования на сервисы v3.

  • v1 – REST-сервисы, доступные по адресам:

    • https://login.company.com/blitz/reg/api/v1/,

    • https://login.company.com/blitz/api/v1/.

    Для авторизации вызова этих сервисов используется HTTP Basic авторизация. Для приложения, которое будет вызывать REST-сервисы, необходимо в настройках приложения задать пароль на вкладке REST настроек протоколов приложения. Приложению будут доступны все REST-сервисы v1.

    Совет

    Если какие-то из сервисов использовать не планируется, запретите их вызов через настройки веб-сервера (nginx).

  • v2 – REST-сервисы, доступные по адресу https://login.company.com/blitz/api/v2/. Для авторизации вызова большинства этих сервисов используется HTTP Basic авторизация, а для части сервисов – OAuth 2.0.

  • v3 – REST-сервисы, доступные по адресу https://login.company.com/blitz/api/v3/. Для авторизации вызова этих сервисов используется OAuth 2.0 и полученные от Blitz Identity Provider маркеры безопасности. Доступ приложений к различным REST-сервисам регулируется через разрешения (scope).

Режимы доступа к REST API#

Предоставляемые Blitz Identity Provider сервисы https://login.company.com/blitz/api/v3/ можно вызывать в двух режимах:

  • пользовательский режим,

  • системный режим.

Пользовательский режим доступа#

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

  • Authorization: Bearer <маркер доступа с пользовательскими разрешениями> – заголовок авторизации, содержащий маркер доступа с разрешениями текущего пользователя.

  • X-Forwarded-For: <IP-адрес пользователя> – заголовок, в котором должно быть передано значение IP-адреса пользователя. Данное значение будет записано в событие безопасности Blitz Identity Provider.

  • User-Agent: <значение User-Agent пользователя> – заголовок, в котором должно быть передано значение User-Agent устройства пользователя. Данное значение будет записано в событие безопасности Blitz Identity Provider.

Внимание

Для разрешений пользователя blitz_api_user и blitz_api_user_chg нужно обязательно задавать атрибуты через общие настройки OAuth 2.0.

Возможные разрешения пользователя

Изменение пароля

blitz_change_password

Для использования сервиса POST /blitz/api/v2/users/{subjectId}/password.

Создание новых прав

Для использования сервисов:

  • PUT /blitz/admin/api/v3/rights/right7,

  • GET /blitz/admin/api/v3/rights/right7,

  • DELETE /blitz/admin/api/v3/rights/right6.

Управление правами учетной записи

blitz_user_rights

Для использования сервисов:

  • GET /blitz/api/v3/rights/of/{subjectId},

  • POST /blitz/api/v2/users/rights/change.

Получение атрибутов

blitz_api_user

Для использования сервиса GET /blitz/api/v3/users/{subjectId}.

Изменение атрибутов

blitz_api_user_chg

Для использования сервиса POST /blitz/api/v3/users/{instanceId}.

Получение настроек двухфакторной аутентификации, разрешений, контрольного вопроса

blitz_api_usec

Для использования сервисов:

  • GET /blitz/api/v3/users/{subjectId}/auth,

  • GET /blitz/api/v3/users/{subjectId}/totps,

  • GET /blitz/api/v3/users/{subjectId}/acls,

  • GET /blitz/api/v3/users/{subjectId}/secQsn,

  • POST /blitz/api/v3/users/{subjectId}/secQsn /check.

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

blitz_api_usec_chg

Для использования сервисов:

  • POST /blitz/api/v3/users/{instanceId}/pswd,

  • POST /blitz/api/v3/users/{instanceId}/sessions/reset,

  • POST /blitz/api/v3/users/{instanceId}/secQsn,

  • POST /blitz/api/v3/users/{subjectId}/auth,

  • GET /blitz/api/v3/users/{subjectId}/totps /attach/qr,

  • POST /blitz/api/v3/users/{subjectId /totps /attach/qr,

  • DELETE /blitz/api/v3/users/{subjectId} /secQsn,

  • DELETE /blitz/api/v3/users/{subjectId} /totps/{id},

  • DELETE /blitz/api/v3/users/{subjectId} /acls/{id}.

Получение запомненных устройств

blitz_api_uapps

Для использования сервиса GET /blitz/api/v3/users/{subjectId}/apps.

Удаление запомненных устройств

blitz_api_uapps_chg

Для использования сервиса DELETE /blitz/api/v3/users/{subjectId}/apps/{id}.

Получение событий безопасности

blitz_api_uaud

Для использования сервиса GET /blitz/api/v3/users/{subjectId}/audit.

Получение списка учетных записей внешних поставщиков

blitz_api_ufa

Для использования сервиса GET /blitz/api/v3/users/{subjectId}/fa.

Изменение списка учетных записей внешних поставщиков

blitz_api_ufa_chg

Для использования сервисов:

  • POST /blitz/api/v3/users/{subject Id}/fa/{fpType}/{fpName}/{sid},

  • DELETE /blitz/api/v3/users/{subjectId}/fa/{fpType}/{fpName}/{sid}.

Вход с использованием QR-кода

blitz_qr_auth

Для использования сервисов:

  • GET /blitz/api/v3/auth/qr/{QR_code},

  • POST /blitz/api/v3/auth/qr/{QR_code}/confirm,

  • POST /blitz/api/v3/auth/qr/{QR_code}/refuse.

Маркер доступа на пользовательские разрешения приложение получает в момент идентификации и аутентификации пользователя.

Примечание

Описание механизмов идентификации и аутентификации приведено в разделах:

Системный режим доступа#

В данном разделе приведен перечень разрешений, которые может получить приложение для доступа к REST API.

Внимание

Для разрешений пользователя blitz_api_sys_users и blitz_api_sys_users_chg нужно обязательно задавать атрибуты через общие настройки OAuth 2.0.

Возможные системные разрешения (разрешения, получаемые на приложение)

Доступ к сервисам работы с организациями

blitz_groups

Для использования сервисов:

  • GET /blitz/api/v2/grps/{id},

  • POST /blitz/api/v2/grps,

  • POST /blitz/api/v2/grps/{id}?profile={profile},

  • DELETE /blitz/api/v2/grps/{id}?profile={profile},

  • GET /blitz/api/v2/grps/{id}/members,

  • POST /blitz/api/v2/grps/{id}/members/add?profile={profile},

  • POST /blitz/api/v2/grps/{id}/members/rm?profile={profile}.

Назначение и отзыв прав доступа

blitz_rights_full_access

Для использования сервисов:

  • PUT /blitz/api/v3/rights,

  • DELETE /blitz/api/v3/rights,

  • GET /blitz/api/v3/rights/on,

  • GET /blitz/api/v3/rights/of.

Отзыв прав доступа ведомых учетных записей

blitz_rm_rights

Для использования сервиса POST /blitz/api/v2/users/rights/change.

Получение атрибутов любого пользователя

blitz_api_sys_users

Для использования сервиса GET /blitz/api/v3/users/{subjectId}.

Изменение атрибутов любого пользователя

blitz_api_sys_users_chg

Для использования сервиса POST /blitz/api/v3/users/{instanceId}.

Регистрация учетной записи

blitz_api_sys_users_reg

Для использования сервиса PUT /blitz/api/v3/users.

Получение настроек двухфакторной аутентификации, разрешений любого пользователя, контрольного вопроса

blitz_api_sys_usec

Для использования сервисов:

  • GET /blitz/api/v3/users/{subjectId}/auth,

  • GET /blitz/api/v3/users/{subjectId}/totps,

  • GET /blitz/api/v3/users/{subjectId}/acls,

  • GET /blitz/api/v3/users/{subjectId}/state,

  • GET /blitz/api/v3/users/{subjectId}/secQsn,

  • POST /blitz/api/v3/users/{subjectId}/secQsn/check.

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

blitz_api_sys_usec_chg

Для использования сервисов:

  • POST /blitz/api/v3/users/{instanceId}/pswd,

  • POST /blitz/api/v3/users/{instanceId}/sessions/reset,

  • POST /blitz/api/v3/users/{subjectId}/auth,

  • POST /blitz/api/v3/users/{subjectId}/state,

  • GET /blitz/api/v3/users/{subjectId}/totps/attach/qr,

  • POST /blitz/api/v3/users/{subjectId}/totps/attach/qr,

  • POST /blitz/api/v3/users/{subjectId}/secQsn,

  • DELETE /blitz/api/v3/users/{subjectId}/totps/{id},

  • DELETE /blitz/api/v3/users/{subjectId}/acls/{id},

  • DELETE /blitz/api/v3/users/{subjectId}/secQsn.

Получение устройств любого пользователя

blitz_api_sys_uapps

Для использования сервиса:

GET /blitz/api/v3/users/{subjectId}/apps.

Удаление устройств любого пользователя

blitz_api_sys_uapps_chg

Для использования сервиса:

DELETE /blitz/api/v3/users/{subjectId}/apps/{id}.

Получение событий безопасности любого пользователя

blitz_api_sys_uaud

Для использования сервиса:

GET /blitz/api/v3/users/{subjectId}/audit.

Получение списка учетных записей внешних поставщиков

blitz_api_sys_ufa

Для использования сервиса:

POST /blitz/api/v3/users/{subjectId}/fa/{fpType}/{fpName}/{sid}.

Изменение списка учетных записей внешних поставщиков

blitz_api_sys_ufa_chg

Для использования сервиса:

DELETE /blitz/api/v3/users/{subjectId}/fa/{fpType}/{fpName}/{sid}.

Получение маркера доступа от любого внешнего поставщика

fed_tkn_any

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

Для использования сервиса:

GET /blitz/api/v3/users/${subjectId}/fedToken/${fedPointType}/${fedPointName}.

Получение маркера доступа от определенного внешнего поставщика

fed_tkn_${fedPointType}_${fedPointName}

Blitz Identity Provider можно настроить таким образом, что будут сохраняться маркеры доступа пользователя от внешних поставщиков идентификации. Разрешение позволяет получить маркер доступа пользователя от внешнего поставщика идентификации с типом ${fedPointType} и именем ${fedPointName}, например, fed_tkn_esia_esia_1 для сети esia:esia_1.

Для использования сервиса:

GET /blitz/api/v3/users/${subjectId}/fedToken/${fedPointType}/${fedPointName}.

Чтобы получить маркер доступа на системное разрешение, приложение должно выполнить запрос для получения маркера:

  • Запрос POST https://login.company.com/blitz/oauth/te.

  • Запрос должен содержать заголовок Authorization со значением Basic {secret}, где secret – это client_id:client_secret (например, app:topsecret) в формате Base64.

  • Тело запроса должно содержать следующие параметры:

    • grant_type – принимает значение client_credentials;

    • scope – запрашиваемое системное разрешение.

  • В ответ приложение получит маркер доступа access_token, время его жизни expires_in и тип маркера token_type.

    Совет

    Рекомендуется, чтобы приложение кэшировало полученный маркер доступа для многократного использования на время, немного меньшее, чем параметр expires_in, после чего осуществляло получение нового маркера доступа для обновления в кэше.

  • Возможные ошибки при вызове /oauth/te соответствуют RFC 6749 и описаны здесь.

Примеры

Authorization: Basic YWlzOm…XQ=

POST blitz/oauth/te HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic ZG5ld…lg

grant_type=client_credentials&scope=blitz_groups

{
   "access_token":"QFiJ9mPgERPuusd36mQvD4mfzYolH_CmuddAJ3YKTOI",
   "expires_in":3600,
   "scope":"blitz_groups",
   "token_type":"Bearer"
}

При попытке вызова REST-сервиса с просроченным маркером доступа к нему: HTTP 401 Unauthorized.