TOTP/HOTP#

Совет

См. RFC 6238 TOTP: Time-Based One-Time Password Algorithm.

Внимание

API-запросы отправляются на адрес https://login.company.com/<context>/<url>, где context — заданный относительный путь до сервисов Blitz Identity Provider, url - адрес метода, приведенный в настоящем разделе. По умолчанию API-запросы отправляются на https://login.company.com/blitz/<url>.

Проверка наличия TOTP#

Метод

GET /api/v3/users/{subjectId}/totps

Проверка наличия у пользователя настроенного TOTP-генератор одноразовых кодов.

Необходимые разрешения: blitz_api_usec или blitz_api_sys_usec.

Возвращает

Если TOTP настроен, то в ответ будут получены его настройки.

Если TOTP отсутствует у пользователя, то вернется HTTP код 404.

Пример

Запрос

GET /api/v3/users/d2580c98-e584-4aad-a591-97a8cf45cd2a/totps HTTP/1.1
Authorization: Bearer cNwIXatB0wk5ZHO0xG5kxuuLubesWcb_yPPqLOFWDuwzMDc0Nz
Cache-Control: no-cache

Ответ

[
    {
        "id": "SW_TOTP_1_d2580c98-e584-4aad-a591-97a8cf45cd2a",
        "len": 6,
        "name": "Google Authenticator"
    }
]

Привязка TOTP по QR-коду#

Привязка к учетной записи пользователя TOTP-генератора с использованием QR-кода осуществляется в два этапа.

Этап №1

Метод

GET /api/v3/users/{subjectId}/totps/attach/qr

Запрос в Blitz Identity Provider QR-кода и строки привязки.

Необходимые разрешения: blitz_api_usec_chg или blitz_api_sys_usec_chg.

Заголовки

В пользовательском режиме необходимо передать заголовки с IP‑адресом пользователя и User-Agent.

Возвращает

Атрибуты:

base64QRCode – QR-код привязки генератора, который нужно отобразить пользователю;
base32Secret – секретная строка привязки генератора, которую нужно отобразить пользователю, если ему неудобно будет фотографировать QR-код, и он предпочтет ввести код привязки в генератор вручную.

Пример

Запрос

GET /api/v3/users/d25..2a/totps/attach/qr HTTP/1.1
Authorization: Bearer cN..z
Cache-Control: no-cache

Ответ

{
    "base64QRCode": "iVB…g==",
    "base32Secret": "W247OHVTPPTIAOXMGKK6Z7BZ3DEYWO74"
}

Этап №2

Метод

POST /api/v3/users/{subjectId}/totps/attach/qr

Подтверждение регистрации привязки.

Необходимые разрешения: blitz_api_usec_chg или blitz_api_sys_usec_chg.

Тело запроса

base32Secret – секретная строка инициализации TOTP-генератора;
otpCode – одноразовый код, выработанный генератором по алгоритму TOTP от строки secret и текущего временного слота;
name – отображаемое имя TOTP-генератора (необязательно).

Возвращает

В случае успешного выполнения - HTTP 204 No Content.
В случае ошибки сервис - HTTP 400 Bad Request.

Пример

Запрос

POST /api/v3/users/d2580c98..cd2a/totps/SW_TOTP_1_d2580c98..cd2a HTTP/1.1
Content-Type: application/json
X-Forwarded-For: 200.200.100.100
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5)

{
    "base32Secret": "W247OHVTPPTIAOXMGKK6Z7BZ3DEYWO74",
    "name": "Google Authenticator",
    "otpCode": "123456"
}

Ответ

{
    "base64QRCode": "iVB…g==",
    "base32Secret": "W247OHVTPPTIAOXMGKK6Z7BZ3DEYWO74"
}

Ошибка

Передан неправильный код#

{
    "type": "process_error",
    "error": "wrong_otp_code"
}

Привязка TOTP по переданному секрету#

Метод

POST /api/v3/users/totps/attach

Привязка к учетной записи пользователя TOTP-генератора по переданному в параметрах секрету.

Необходимые разрешения:

для привязки TOTP с полем otpCode: blitz_api_usec_chg или blitz_api_sys_usec_chg;
для привязки TOTP без поля otpCode: blitz_api_otp_full_access.

Тело запроса

base32Secret – секретная строка инициализации TOTP-генератора;
name – отображаемое имя TOTP-генератора;

Примечание

Параметр опционален. При отсутствии используется название, указанное в консоли.
len – длина одноразового кода (может принимать значения от 4 до 16 символов);
algo – используемый алгоритм (SHA1, SHA256 или SHA512);
period – время действия одноразового кода (может принимать значения от 30 до 300 секунд);
otpCode – одноразовый код, выработанный генератором по алгоритму TOTP от строки secret и текущего временного слота.

Примечание

Параметр опционален.

Возвращает

В случае успешного выполнения - HTTP 204 No Content.
В случае ошибки - HTTP 400 Bad Request.

Пример

Запрос

POST /blitz/api/v3/users/totps/attach HTTP/1.1
Content-Type: application/json
X-Forwarded-For: 200.200.100.100
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5)

{
   "base32Secret": "W247OHVTPPTIAOXMGKK6Z7BZ3DEYWO74",
   "name": "Google Authenticator",
   "len": 17,
   "algo": "SHA256243434",
   "period": 400,
   "otpCode": "123456"
}

Ответ

204 No Content

Ошибка

400 Bad Request

{
   "type": "input_error",
   "error": "wrong_values",
   "errors": [
      {
            "type": "input_error",
            "error": "wrong_value",
            "desc": "wrong algo",
            "pos": "algo"
      },
      {
            "type": "input_error",
            "error": "wrong_value",
            "desc": "len cannot be greater than 16",
            "pos": "len"
      },
      {
            "type": "input_error",
            "error": "wrong_value",
            "desc": "period cannot be greater than 300",
            "pos": "period"
      }
   ]
}

Удаление привязки TOTP#

Метод

DELETE /api/v3/users/{subjectId}/totps/{id}

Удаление привязки TOTP-генератора к учетной записи пользователя.

Необходимые разрешения: blitz_api_usec_chg или blitz_api_sys_usec_chg.

URL-параметры

В качестве id указывается полученный идентификатор привязки.

Заголовки

В пользовательском режиме необходимо передать заголовки с IP‑адресом пользователя и User-Agent.

Возвращает

При успешном выполнении сервис вернет HTTP 204 No Content.

Пример

Запрос#

DELETE /api/v3/users/d..2a/totps/SW_TOTP_1_d..2a HTTP/1.1
Authorization: Bearer cN..z

Привязка HOTP по переданному секрету#

Метод

POST /api/v3/users/hotps/attach

Привязка к учетной записи пользователя HOTP-генератора по переданному в параметрах секрету.

Необходимое разрешение: blitz_api_otp_full_access.

Тело запроса

base32Secret – секретная строка инициализации HOTP-генератора;
name – отображаемое имя HOTP-генератора;

Примечание

Параметр опционален. При отсутствии используется название Mobile App (HOTP).
len – длина кода подтверждения (может принимать значения от 4 до 16 символов);
algo – используемый алгоритм (SHA1, SHA256 или SHA512);
counter – начальное значение счётчика, используемого HOTP для генерации одноразовых кодов (должно быть больше 0).

Возвращает

В случае успешного выполнения - HTTP 204 No Content.
В случае ошибки сервис - HTTP 400 Bad Request.

Пример

Запрос

POST /blitz/api/v3/users/hotps/attach HTTP/1.1
Content-Type: application/json
X-Forwarded-For: 200.200.100.100
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5)

{
    "base32Secret": "W247OHVTPPTIAOXMGKK6Z7BZ3DEYWO74",
    "name": "Yandex TEST",
    "len": 8,
    "algo": "SHA512",
    "counter": 1
}

Ответ

204 No Content

Ошибка

400 Bad Request

{
   "type": "input_error",
   "error": "wrong_values",
   "errors": [
      {
            "type": "input_error",
            "error": "wrong_value",
            "desc": "wrong algo",
            "pos": "algo"
      },
      {
            "type": "input_error",
            "error": "wrong_value",
            "desc": "len cannot be greater than 16",
            "pos": "len"
      }
   ]
}