Подключение
Интеграция

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

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

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

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

JWT токен

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

Структура

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

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

Части разделены точками и закодированы в формате 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" //произвольный ключ
}

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

Ключ	Название	Описание	Значение
iss	Issuer	Сторона, где был выдал токен	Всегда https://access.multifactor.ru/
aud	Audience	Кому предназначен токен	ApiKey из настроек в личном кабинете
sub	Subject	Идентификатор пользователя	Из параметра 'Identity' API
jti	JWT ID	Идентификатор токена	Совпадает с идентификатором запроса доступа
iat	Issued At	Дата/время выдачи	в формате UNIX time
exp	Expiration Time	Дата/время окончания действия	в формате UNIX time

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

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

Подпись

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

HS256
RS256

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

Формат HS256

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

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

Формат RS256

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

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

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

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

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