Перейти к основному содержимому

Интеграция для сайтов и приложений

Схема потоков данных

Схема потоков данных мультифакторной аутентификации

Для подключения двухфакторной аутентификации для сайта нужно сделать:

  1. Пользователь вводит на вашем сайте логин и пароль, сайт проверяет корректность данных.
  2. Если данные корректны, сайт запрашивает API Мультифактора для создания запроса доступа. В ответе API содержится уникальный адрес страницы доступа.
  3. Сайт переадресовывает пользователя на страницу доступа Мультифактор, где ему будет предложено пройти второй фактор аутентификации. После успешного завершения, Мультифактор создает токен доступа и возвращает пользователя на ваш сайт.
  4. Сайт проверяет токен и авторизует пользователя.

JWT токен

JSON Web Token — современный стандарт создания токена доступа для обмена аутентификационной информацией между двумя сторонами. При всей сложности названия, JWT имеет простую структуру и его очень удобно использовать.

Структура

Токен состоит из трех частей:

  1. Заголовок
  2. Данные
  3. Подпись

Части разделены точками и закодированы в формате base64-url.

Обратите внимание

Части токена закодированы не в формате base64, а в base64-url для безопасной передачи в параметрах HTTP запроса.

Пример:

xxx.yyy.zzz

Первые две части содержат в себе JSON данные в формате ключ: значение, подпись — вычисленное значение для проверки первых двух.

Заголовок

В заголовке описывается формат токена:

{
"typ": "JWT", //тип : JWT
"alg": "HS256" //алгоритм подписи: HMAC с использованием SHA-256
}

Данные

Во втором блоке передаются сведения о пользователе и аутентификации

{
"iss": "https://access.multifactor.ru", //кто выдал
"aud": "rs_1a913e4ea690ac12ea163331dd60d", //кому выдан (ApiKey)
"sub": "user@example.com", //имя пользователя
"jti": "RxMEyo9", //id токена
"iat": 1571684399, //когда выдан
"exp": 1571684699, //срок действия
"returnUrl": "/", //произвольный ключ
"rememberMe": "False", //произвольный ключ
"createdAt": "10/21/19 6:59:55 PM" //произвольный ключ
}

Блок содержит обязательные и необязательные ключи. К обязательным относятся:

КлючНазваниеОписаниеЗначение
issIssuerСторона, где был выдал токенВсегда https://access.multifactor.ru/
audAudienceКому предназначен токенApiKey из настроек в личном кабинете
subSubjectИдентификатор пользователяИз параметра 'Identity' API
jtiJWT IDИдентификатор токенаСовпадает с идентификатором запроса доступа
iatIssued AtДата/время выдачив формате UNIX time
expExpiration TimeДата/время окончания действияв формате UNIX time

Обязательные ключи зарезервированы системой Мультифактор и всегда присутствуют в токене.

К необязательным относятся любые параметры, переданные в API для создания запроса доступа. Это могут быть: роли пользователя в вашей системе, дополнительные атрибуты безопасности и т.д.

Подпись

Третий блок JWT содержит подпись токена. Мультифактор поддерживает два вариант подписи:

  • HS256
  • RS256

Подпись гарантирует, что токен выдан системой Мультифактор и передан вам без изменений.

Формат HS256

Подпись формируется, как HMAC-SHA256(message, secret), где:

  • message — первые две части сообщения, закодированные в base64-url и разделенные точкой;
  • secret — API Secret, доступный в личном кабинете, в разделе "Ресурсы" -> "Параметры".

Формат RS256

Сообщение подписывается закрытым ключом, известным только Мультифактору, а вы проверяете с помощью открытого ключа всегда доступного по адресу https://api.multifactor.ru/.well-known/jwks.json.

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

Проверка токена и авторизация

После успешного прохождения второго фактора аутентификации на странице доступа Мультифактор, пользователь возвращается на ваш сайт, на адрес, указанный в API при создании запроса. Адрес получает параметр accessToken, который необходимо проверить перед авторизацией пользователя.

Проверка обязательно должна включать в себя:

  • Контроль даты выдачи и срока действия токена
  • Проверку аудитории (aud) — должен совпадать с ApiKey
  • Проверку подписи

Если все корректно, сайт авторизует пользователя (выдает сессионную куку).

Важно

JWT токен не зашифрован, поэтому недопустимо включать в него пароль пользователя или другую конфиденциальную информацию.

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