API аутентификации#

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

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

Blitz Identity Provider предоставляет HTTP API, позволяющее встроить в веб‑страницу приложения идентификацию и аутентификацию пользователей без перенаправления пользователя на отдельную страницу входа. Данное HTTP API создано для веб-приложений. При использовании API обеспечивается Web Single Sign‑On, а именно при последующем входе в той же веб-сессии пользователя в другое подключенное к Blitz Identity Provider приложение, у него не будет повторно запрашиваться вход.

Настройки для использования API#

Приложение должно быть зарегистрировано в Blitz Identity Provider. Приложению в Blitz Identity Provider должны быть присвоены client_id и client_secret, и в Blitz Identity Provider должны быть зарегистрированы URL возврата приложения.

Взаимодействие страницы приложения и Blitz Identity Provider основано на выполнении серии AJAX-взаимодействий. Для возможности такого взаимодействия на веб‑сервере приложения и на веб-сервере Blitz Identity Provider должны быть сделаны следующие настройки CORS (Cross-origin resource sharing):

На сервере Blitz Identity Provider для обработчика /blitz/oauth/ae нужно настроить CORS-разрешение, добавив следующие HTTP Headers (нужно указать origin для ПРОД‑сайта и необходимые origin для нужных тестовых сред):
```
"Access-Control-Allow-Origin" -> "https://{app-domain}",
"Access-Control-Allow-Credentials" -> "true"
```
В этом заголовке {app-domain} – это домен приложения.
На сервере портала для callback-обработчика (см. Схема взаимодействия) ответа от Blitz Identity Provider нужно настроить следующее CORS-разрешение (разрешение на null, так как после редиректа браузер сбрасывает origin):
```
"Access-Control-Allow-Origin" -> null,
"Access-Control-Allow-Credentials" -> "true"
```

Схема взаимодействия#

HTTP API аутентификации позволяет:

Проверить наличие SSO-сессии. В случае отсутствия SSO-сессии получить список доступных пользователю методов аутентификации.
Провести идентификацию и аутентификацию с использованием логина и пароля.
Провести идентификацию и аутентификацию с использованием логина (телефона) и кода подтверждения, отправляемого по SMS.
Провести идентификацию и аутентификацию по QR-коду;
Провести подтверждение входа с использованием кода подтверждения, отправляемого по SMS.

На рисунке ниже приведена схема взаимодействия при входе по логину и паролю с последующим подтверждением входа с использованием кода подтверждения, отправляемого по SMS.

На следующем рисунке приведена схема взаимодействия при входе по телефону и коду подтверждения, отправляемому по SMS.

Веб-приложение взаимодействует с Blitz Identity Provider, выполняя серию из AJAX‑запросов.

Примечание

Запросы должны делаться обязательно с сохранением и передачей cookie – необходимо использовать withCredentials: true

В последующих разделах приводятся описания вызываемых запросов, возможных ответов и рекомендаций по их обработке. Примеры запросов и ответов приводятся в виде вызовов cURL.

Запуск процесса входа#

Чтобы запустить процесс входа, приложение должно направить в AJAX к Blitz Identity Provider запрос HTTP GET (обязательно с withCredentials: true) на обычный обработчик Authorization Endpoint (/blitz/oauth/ae, см. Получение кода авторизации), добавив к запросу специальный параметр display=script.

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

curl -v -b cookies.txt -c cookies.txt \
--request GET 'https://login.company.com/blitz/oauth/ae?response_type=code&client_id=ais&scope=openid&state=…&display=script&redirect_uri=https%3A%2F%2Fapp.company.com%2Fre'

Если SSO-сессия уже существует, то Blitz Identity Provider автоматически перенаправит пользователя на адрес обработчика redirect_uri, добавив к запросу код авторизации и параметр state. Используя полученный код авторизации приложение продолжит стандартное взаимодействие по OpenID Connect для получения маркеров безопасности и данных учетной записи.

Пример ответа с перенаправлением, если сессия SSO-сессия уже существует:

…
< HTTP/2 302
…
< location: https://…?code=…&state=…
…

Пример ответа, если требуется аутентификация:

{
    "inquire":"choose_one",
    "items":[
        {
            "inquire":"login_with_password"
        },
        {
            "inquire":"request_auth_with_fed_point",
            "fp":"esia:esia_1"
        },
        …
        {
            "inquire":"request_auth_with_fed_point",
            "fp":"yandex:yandex_1"
        },
        {
            "inquire":"login_to_send_sms"
        },
        {
            "inquire":"show_qr_code",
            "link":"https://…?code=dde087f0-8f4a-478e-886b-5354b0283362",
            "expires":1660905165,
            "logo":"https:/…"
        }
    ]
}

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

login_with_password – войти по логину и паролю;
request_auth_with_fed_point – войти с помощью внешнего поставщика идентификации (социальной сети);
login_to_send_sms – войти с помощью логина и кода подтверждения, отправленного по SMS;
show_qr_code – отобразить QR-код, позволяющий осуществить вход.

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

В зависимости от включенных в Blitz Identity Provider режимов защиты инструкция login_with_password может содержать дополнительные параметры:

Если в Blitz Identity Provider настроен режим необходимости использования CAPTCHA при входе, то в инструкции будет параметр captchaId, который необходимо использовать приложению для теста CAPTCHA:

{
    "inquire": "choose_one",
    "items": [
        {
            "inquire": "login_with_password",
            "captchaId": "9cf48a75-6be1-4008-b34e-8906220c472f"
        },
        …
    ]
}

Если в Blitz Identity Provider настроен режим защиты от подбора пароля, требующий решения от приложения длительной вычислительной задачи (Proof of Work), то в инструкции будет параметр proofOfWork:

{
    "inquire": "choose_one",
    "items": [
        {
            "inquire": "login_with_password",
            "captchaId": "9cf48a75-6be1-4008-b34e-8906220c472f",
            "proofOfWork": "1:15:220313184752:abe…539::Ekf…w==:"
        }
    ]
}

В случае получения параметра proofOfWork рекомендуется асинхронно сразу запустить алгоритм нахождения решения, не дожидаясь, пока пользователь выберет режим входа по логину и паролю и введет данные. Это позволит скрыть от пользователя время задержки на решение задачи (может составлять несколько секунд в зависимости от сложности задачи). В настоящий момент используется алгоритм Hashcash.

Важно

Необходимо дополнить параметр proofOfWork таким значением, чтобы вычисленный от него по алгоритму SHA-1 хэш содержал в начале столько нулевых бит, сколько задано условием задачи (число после первого символа : в параметре proofOfWork).

Например, решением для 1:15:yyyy03Su212003:BlitzIdp::McMybZIhxKXu57jd:0 будет строка 1:15:yyyy03Su212003:BlitzIdp::McMybZIhxKXu57jd:3/g

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

Вход по логину и паролю.
Вход по телефону и коду подтверждения в SMS.
Вход по QR-коду.
Вход через внешний поставщик идентификации – такой способ входа возможен только через браузер с перенаправлением пользователя на страницу входа внешнего поставщика идентификации. Нужно повторить вызов Authorization Endpoint (см. Получение кода авторизации), использовать в вызове необходимое значение параметра bip_action_hint, соответствующее выбранному пользователем внешнему поставщику входа (например, bip_action_hint=externalIdps:esia:esia_1).

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

https://login.company.com/blitz/oauth/ae?response_type=code&client_id=portal.ru&scope=openid+profile&redirect_uri=https://apitest.company.com/success&state=342a2c0c-d9ef-4cd6-b328-b67d9baf6a7f& bip_action_hint=used_externalIdps:esia:esia_1

Завершение процесса входа в этом случае будет происходить стандартным образом в соответствии с OpenID Connect – Blitz Identity Provider вернет код авторизации на redirect_uri обработчик приложения.

Вход по логину и паролю#

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

При использовании reCAPTCHA v3 необходимо выполнить инициализацию reCAPTCHA v3 согласно документации.

Загрузить на странице приложения скрипт, используя такой же reCAPTCHA v3 sitekey как зарегистрирован в Blitz Identity Provider:

<script src="https://www.google.com/recaptcha/api.js?render=reCAPTCHA_site_key"></script>

Вызвать grecaptcha.execute на нажатие кнопки входа:

<script>
    function onClick(e) {
        e.preventDefault();
        grecaptcha.ready(function() {
            grecaptcha.execute('reCAPTCHA_site_key', {action: 'submit'}).then(function(token) {
                // Add your logic to submit to your backend server here.
            });
        });
    }
</script>

Сразу после вызова со страницы входа сервисов reCAPTCHA необходимо вызвать с сервера приложений операцию проверки (verify). Вызов должен быть произведен не напрямую на сервера Google, а через специальный proxy-сервис в Blitz Identity Provider.

Пример запроса на проверки (операция verify):

POST /blitz/login/captcha/verify
Content-Type: 'text/json'
{
    "ctx": {
         // captchaId
        "id": "9cf48a75-6be1-4008-b34e-8906220c472f",
        "method": "password"
    },
    "params": {
        // token для проверки капчи, полученный при регистрации в Google
        "response": "03…sA"
    }
}


Ответ ``HTTP 200 OK``:

{
    "action": "submit",
    "challenge_ts": "2021-03-16T11:18:41Z",
    "success": true,
    "hostname": "company.com",
    "score": 0.9
}

Также если в Blitz Identity Provider включена защита Proof of Work, то нужно вычислить значение параметра proofOfWork (см. Запуск процесса входа).

Для проверки логина и пароля приложение должно направить в AJAX к Blitz Identity Provider запрос HTTP POST (обязательно с withCredentials: true) на URL https://login.company.com/blitz/login/methods/headless/password с Content-Type x-www-form-urlencoded и Body, содержащим параметры login и password, а также вычисленный proofOfWork (если этот параметр был получен от Blitz Identity Provider при запуске процесса входа).

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

curl -v -b cookies.txt -c cookies.txt \
--request POST 'https://login.company.com/blitz/login/methods/headless/password' \
--header "Content-Type: application/x-www-form-urlencoded" \
--data 'login=логин&password=пароль&proofOfWork=решение'

Blitz Identity Provider при получении запроса выполняет необходимые проверки безопасности (пройдена ли CAPTCHA, решен ли ProofOfWork, не заблокирована ли учетная запись). Если проверки безопасности пройдены, то Blitz Identity Provider проверяет переданные логин и пароль.

Если проверки логина и пароля успешные и если пройденной аутентификации достаточно, то Blitz Identity Provider автоматически перенаправит пользователя на адрес обработчика redirect_uri, добавив к запросу код авторизации и параметр state. Используя полученный код авторизации приложение продолжит стандартное взаимодействие по OpenID Connect для получения маркеров безопасности и данных учетной записи.

Пример ответа с перенаправлением, если сессия SSO-сессия уже существует:

…
< HTTP/2 302
…
< location: https://…?code=…&state=…
…

Если какие-либо проверки завершились ошибкой или если необходимы дальнейшие действия от пользователя, то Blitz Identity Provider возвращает одну из инструкций.

Пример ответа в случае ошибки проверки логина и пароля:

{
    "inquire": "login_with_password",
    "errors": [
        {
            "code": "invalid_credentials",
            "params": {}
        }
    ]
}

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

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

{
    "inquire": "login_with_password",
    "captchaId": "9cf48a75-6be1-4008-b34e-8906220c472f",
    "proofOfWork": "1:15:220313184752:abe…539::Ekf…w==:",
    "errors": [
        {
            "code": "invalid_credentials",
            "params": {
                "_cause": "used_old_password"
            }
        }
    ]
}

Пример получения ошибки, что не прошла проверка CAPTCHA:

{
    "inquire": "login_with_password",
    "captchaId": "9cf48a75-6be1-4008-b34e-8906220c472f",
    "errors": [
        {
            "code": "invalid_captcha",
            "params": {}
        }
    ]
}

Пример ошибки, что не прошла проверка решения Proof of Work:

{
    "inquire": "handle_error",
    "errors": [
        {
            "code": "doesNotMatch",
            "params": {}
        }
    ]
}

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

{
   "inquire": "delayed_login_with_password",
   "delayedFor": 5
}

Повторный вызов должен быть сделан, когда пройдет требуемое время. В повторный вызов необходимо передать параметр isDelayed=true.

Пример повторного вызова проверки пароля в ответ на инструкцию delayed_login_with_password:

curl -v -b cookies.txt -c cookies.txt \
--request POST 'https://login.company.com/blitz/login/methods/headless/password' \
--header "Content-Type: application/x-www-form-urlencoded" \
--data 'login=логин&password=пароль&proofOfWork=решение&isDelayed=true'

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

Пользователь передал неправильный пароль, после чего включилась защита, и CAPTCHA нужна для очередной попытки аутентификации.
Защита от подбора пароля для учетной записи включалась ранее. Текущий переданный пароль не проверялся, так как не проводился тест CAPTCHA.

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

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

Пример ответа для первого случая, что пароль неправильный и нужен тест CAPTCHA:

{
    "inquire":"login_with_password",
    "captchaId":"1c9e4047-c8c4-47ad-a447-cc1809bd3e6c",
    "errors":[
        {
            "code":"invalid_credentials",
            "params":{}
        }
    ]
}

Пример ответа для второго случая, что пароль не проверялся и нужен тест CAPTCHA:

{
    "inquire":"login_with_password",
    "captchaId":"2f818f5d-3a89-428d-b424-cde38c19051e",
    "errors":[
        {
            "code":"bypass_captcha",
            "params":{}
        }
    ]
}

Пример ошибки, если учетная временно заблокирована:

{
    "inquire":"login_with_password",
    "errors": [
        {
            "code":"pswd_method_temp_locked",
            "params":{"0":"2"}
        }
    ]
}

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

{
    "inquire": "handle_error",
    "errors": [
        {
            "code": "inactivity_lock",
            "params": {}
        }
    ]
}

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

{
    "inquire":"go_to_web",
    "redirect_uri":
        "https://…/blitz/login/methods/password/change?f=false&c=password_policy_violated"
}

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

{
    "inquire":"choose_one",
    "items": [
        {
            "inquire":"ask_to_send_sms"
        },
        {
            "inquire":"go_to_web",
            "redirect_uri":"https://login.company.com/blitz/login/methods2/sms"
        }
    ]
}

Можно или перенаправить пользователя на веб-страницу, чтобы он продолжил подтверждение входа на веб-странице Blitz Identity Provider, или продолжить использовать HTTP API для подтверждения входа по коду из SMS.

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

Вход по телефону и коду подтверждения#

Вход по телефону и коду подтверждения состоит из следующих шагов:

Отправка пользователю кода подтверждения по SMS.
Проверка введенного пользователем кода подтверждения.

Для отправки пользователю кода подтверждения по SMS приложение должно направить в AJAX к Blitz Identity Provider запрос HTTP POST (обязательно с withCredentials: true) на URL https://login.company.com/blitz/login/methods/headless/sms/bind с Content-Type x-www-form-urlencoded и Body, содержащим login пользователя. В качестве login рекомендуется передавать номер телефона, введенный пользователем.

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

curl -v -b cookies.txt -c cookies.txt \
--request POST 'https://login.company.com/blitz/login/methods/headless/sms/bind' \
--header "Content-Type: application/x-www-form-urlencoded" \
--data 'login=логин'

Если учетная запись с переданным логином не найдена, то Blitz Identity Provider вернет ошибку:

{
    "inquire":"handle_error",
    "errors":[
        {
            "code":"no_subject_found",
            "params":{}
        }
    ]
}

Если учетная запись найдена, но по ней ранее был зафиксирован перебор кодов подтверждения, то Blitz Identity Provider вернет ошибку:

{
    "inquire":"handle_error",
    "errors":[
        {
            "code":"method_temp_locked",
            "params":{}
        }
    ]
}

Если учетная запись найдена и для нее возможен вход данным способом, то Blitz Identity Provider отправит пользователю SMS с кодом подтверждения и вернет ответ:

{
    "inquire":"enter_sms_code",
    "contact":"+79991234567",
    "ttl":300,
    "remain_attempts":3
}

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

Для проверки введенного пользователем кода подтверждения приложение должно направить в AJAX к Blitz Identity Provider запрос HTTP POST (обязательно с withCredentials: true) на URL https://login.company.com/blitz/login/methods/headless/sms/bind с Content-Type x-www-form-urlencoded и Body, содержащим sms-code с кодом подтверждения.

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

curl -v -b cookies.txt -c cookies.txt \
--request POST 'https://login.company.com/blitz/login/methods/headless/sms/bind' \
--header "Content-Type: application/x-www-form-urlencoded" \
--data 'sms-code=123456'

Если код неправильный, то Blitz Identity Provider вернет ошибку:

{
    "inquire":"handle_error",
    "errors":[
        {
            "code":"invalid_otp",
            "params":{}
        }
    ],
    "contact":"+79991234567",
    "remain_attempts":2,
    "ttl":276
}

Если количество попыток проверки кода закончилось, то Blitz Identity Provider вернет ошибку:

{
    "inquire":"handle_error",
    "errors":[
        {
            "code":"no_attempts",
            "params":{}
        }
    ]
}

Если срок действия кода истек, то Blitz Identity Provider вернет ошибку:

{
    "inquire":"handle_error",
    "errors":[
        {
            "code":"expired",
            "params":{}
        }
    ]
}

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

curl -v -b cookies.txt -c cookies.txt \
--request POST 'https://login.company.com/blitz/login/methods/headless/sms/bind' \
--header "Content-Type: application/x-www-form-urlencoded" \
--data 'sms-send=sms'

Если запросить переотправку кода до истечения срока действия предыдущего, то вернется ошибка:

{
    "inquire":"handle_error",
    "errors":[
        {
            "code":"code_not_expired",
            "params":{}
        }
    ]
}

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

{
    "inquire":"handle_error",
    "errors":[
        {
            "code":"method_temp_locked",
            "params":{}
        }
    ]
}

Если введенный код подтверждения правильный, и этого достаточно для завершения входа, то Blitz Identity Provider автоматически перенаправит пользователя на адрес обработчика redirect_uri, добавив к запросу код авторизации и параметр state. Используя полученный код авторизации приложение продолжит стандартное взаимодействие по OpenID Connect для получения маркеров безопасности и данных учетной записи.

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

…
< HTTP/2 302
…
< location: https://…?code=…&state=…
…

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

{
    "inquire":"choose_one",
    "items":[
        {
            "inquire":"go_to_web",
            "redirect_uri":"https://login.company.com/blitz/login/methods2/email"
        }
    ]
}

Первичный вход по email#

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

Отправка пользователю кода подтверждения по электронной почте.
Проверка введенного пользователем кода подтверждения.

Для отправки пользователю кода подтверждения по email приложение должно направить в AJAX к Blitz Identity Provider запрос HTTP POST (обязательно с withCredentials: true) на URL https://login.company.com/blitz/login/methods/headless/email/bind с Content-Type x-www-form-urlencoded и Body, содержащим login пользователя. В качестве login нужно передавать адрес электронной почты, введенный пользователем.

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

curl --location --request POST 'https://login.company.com/blitz/login/methods/headless/email/bind' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'login=<email>'

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

{
    "inquire": "enter_email_code",
    "contact": "user@gmail.com",
    "remain_attempts": 3,
    "ttl": 300
}

Проверка кода:

curl --location --request POST 'https://login.company.com/blitz/login/methods/headless/email/bind' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'email-code=746234'

Варианты ответов, если проверка прошла неуспешно:

{
    "errors": [
        {
            "code": "invalid_otp",
            "params": {}
        }
    ],
    "contact": "user@gmail.com",
    "inquire": "handle_error",
    "remain_attempts": 2,
    "ttl": 257
}

{
    "inquire": "handle_error",
    "errors": [
        {
            "code": "no_attempts",
            "params": {}
        }
    ]
}

Повторная отправка кода:

curl --location --request POST 'https://login.company.com/blitz/login/methods/headless/email/bind' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cookie: blc=Hc..; bua=7cd2c312-...; cTm=1:RGVm==; cTmTgs=1:c3Nv; oauth_az=0MyeV-5v_...OnIE; portal_lang=ru' \
--data-urlencode 'email-send=email'

Ответ на повторную отправку кода:

{
    "inquire": "enter_email_code",
    "contact": "user@gmail.com",
    "remain_attempts": 1,
    "ttl": 288
}

Вход по QR-коду#

Вход по QR-коду состоит из следующих шагов:

Отображение пользователю QR-кода на компьютере, на котором выполняется вход;
Периодическая проверка, выполнил ли пользователь сканирование QR-кода мобильным приложением;
Периодическая проверка, подтвердил или отклонил пользователь в мобильном приложении запрос на вход по QR-коду;
Обновление устаревшего QR-кода.

Приложение должно отобразить пользователю QR-код, закодировав в него строку, полученную от Blitz Identity Provider. Ниже показан фрагмент инструкции для входа по QR‑коду (см. Запуск процесса входа).

{
    "inquire":"choose_one",
    "items":[
        …
        {
            "inquire":"show_qr_code",
            "link":"https://…?code=dde087f0-8f4a-478e-886b-5354b0283362",
            "expires":1660905165,
            "logo":"https:/…"
        }
    ]
}

Пояснения по полученным от Blitz Identity Provider параметрам:

inquire – инструкция с доступным вариантом входа, в случае входа по QR-коду имеет значение show_qr_code;
link – ссылка, которая должна быть закодирована в QR-коде, отображаемом пользователю;
expires – время (в Unix Epoch), до которого действителен QR-код. По истечении срока действия рекомендуется отобразить пользователю, что QR-код просрочен;
logo – если в Blitz Identity Provider настроено отображение маленького логотипа в центре поверх QR-кода, то в указанной настройке вернется URL-адрес логотипа.

Когда приложение отобразило пользователю QR-код, необходимо дождаться, чтобы пользователь прочитал QR-код специальным мобильным приложением. Интеграция мобильного приложения для встраивания функции входа по QR-коду описано в Вход в приложение по QR-коду.

Веб-приложение может периодически выполнять проверку, был ли считан мобильным приложением QR-код. Для этого необходимо выполнить в AJAX к Blitz Identity Provider запрос HTTP GET (обязательно с withCredentials: true) на URL https://login.company.com/blitz/login/methods/headless/qrCode/pull.

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

curl -v -b cookies.txt -c cookies.txt \
--request GET 'https://login.company.com/blitz/login/methods/headless/qrCode/pull'

Если QR-код еще не был считан, то вернется ответ:

{
   "command":"showQRCode"
}

Если QR-код считан, то вернется ответ:

{
   "command":"askForConfirm"
}

В этом случае можно обновить пользователю веб-страницу и написать на ней, что ожидается подтверждение входа в мобильном приложении.

Если QR-код просрочен, то вернется ответ:

{
   "command":"needRefresh",
   "cause":"qr_code_expired"
}

Если пользователь отклонил в мобильном приложении запрос входа по QR-коду, то вернется ответ:

{
   "command":"needRefresh",
   "cause":"refused_login"
}

В случае если QR-код просрочен или пользователь отклонил вход по QR-коду, то можно предложить пользователю получить новый QR-код. Для этого выполнить в AJAX к Blitz Identity Provider запрос HTTP POST (обязательно с withCredentials: true) на URL https://login.company.com/blitz/login/methods/headless/qrCode/refresh.

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

curl -v -b cookies.txt -c cookies.txt \
--request POST 'https://login.company.com/blitz/login/methods/headless/qrCode/refresh'

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

{
    "link":"https://…?code=4ddf1667-d57f-4f86-b8f2-3ee53b367dfe",
    "expires":1660922807,
    "logo":"https:/…"
}

Если пользователь подтвердил в мобильном приложении запрос входа по QR-коду, то сервис https://login.company.com/blitz/login/methods/headless/qrCode/pull вернется ответ:

{
   "command":"needComplete"
}

В ответ на этот запрос для завершения входа необходимо выполнить в AJAX к Blitz Identity Provider запрос HTTP POST (обязательно с withCredentials: true) на URL https://login.company.com/blitz/login/methods/headless/qrCode/complete.

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

curl -v -b cookies.txt -c cookies.txt \
--request POST 'https://login.company.com/blitz/login/methods/headless/qrCode/complete'

Если пройденной аутентификации достаточно для завершения входа, то Blitz Identity Provider автоматически перенаправит пользователя на адрес обработчика redirect_uri, добавив к запросу код авторизации и параметр state. Используя полученный код авторизации приложение продолжит стандартное взаимодействие по OpenID Connect для получения маркеров безопасности и данных учетной записи.

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

…
< HTTP/2 302
…
< location: https://…?code=…&state=…
…

Если требуется пройти дополнительно подтверждение входа, то вернется инструкция с возможными способами подтверждения:

{
    "inquire":"choose_one",
    "items":[
        {
            "inquire":"go_to_web",
            "redirect_uri":"https://login.company.com/blitz/login/methods2/email"
        }
    ]
}

Подтверждение входа по коду подтверждения#

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

Отправка пользователю кода подтверждения по SMS.
Проверка введенного пользователем кода подтверждения.

Для отправки пользователю кода подтверждения по SMS приложение должно направить в AJAX к Blitz Identity Provider запрос HTTP POST (обязательно с withCredentials: true) на URL https://login.company.com/blitz/login/methods/headless/sms/bind с Content-Type x-www-form-urlencoded без Body:

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

curl -v -b cookies.txt -c cookies.txt \
--request POST 'https://login.company.com/blitz/login/methods/headless/sms/bind' \
--header "Content-Type: application/x-www-form-urlencoded"

Blitz Identity Provider отправит пользователю SMS с кодом подтверждения и вернет ответ:

{
   "inquire":"enter_sms_code",
   "contact":"+79991234567",
   "ttl":300,
   "remain_attempts":3
}

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

Для проверки введенного пользователем кода подтверждения приложение должно направить в AJAX к Blitz Identity Provider запрос HTTP POST (обязательно с withCredentials: true) на URL https://login.company.com/blitz/login/methods/headless/sms/bind с Content-Type x-www-form-urlencoded и Body, содержащим sms-code с кодом подтверждения.

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

curl -v -b cookies.txt -c cookies.txt \
--request POST 'https://login.company.com/blitz/login/methods/headless/sms/bind' \
--header "Content-Type: application/x-www-form-urlencoded" \
--data 'sms-code=123456'

Если код неправильный, то Blitz Identity Provider вернет ошибку:

{
    "inquire":"handle_error",
    "errors":[
        {
            "code":"invalid_otp",
            "params":{}
        }
    ],
    "contact":"+79991234567",
    "remain_attempts":2,
    "ttl":276
}

Если количество попыток проверки кода закончилось, то Blitz Identity Provider вернет ошибку:

{
    "inquire":"handle_error",
    "errors":[
        {
            "code":"no_attempts",
            "params":{}
        }
    ]
}

Если срок действия кода истек, то Blitz Identity Provider вернет ошибку:

{
    "inquire":"handle_error",
    "errors":[
        {
            "code":"expired",
            "params":{}
        }
    ]
}

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

curl -v -b cookies.txt -c cookies.txt \
--request POST 'https://login.company.com/blitz/login/methods/headless/sms/bind' \
--header "Content-Type: application/x-www-form-urlencoded" \
--data 'sms-send=sms'

Если запросить переотправку кода до истечения срока действия предыдущего, то вернется ошибка:

{
    "inquire":"handle_error",
    "errors":[
        {
            "code":"code_not_expired",
            "params":{}
        }
    ]
}

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

{
    "inquire":"handle_error",
    "errors":[
        {
            "code":"method_temp_locked",
            "params":{}
        }
    ]
}

Если введенный код подтверждения правильный, и этого достаточно для завершения входа, то Blitz Identity Provider автоматически перенаправит пользователя на адрес обработчика redirect_uri, добавив к запросу код авторизации и параметр state. Используя полученный код авторизации приложение продолжит стандартное взаимодействие по OpenID Connect для получения маркеров безопасности и данных учетной записи.

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

…
< HTTP/2 302
…
< location: https://…?code=…&state=…
…