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

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

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

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"            //произвольный ключ
}

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

Ключ	Название	Описание	Значение
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

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

К необязательным относятся любые параметры, переданные в 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 токен не зашифрован, поэтому недопустимо включать в него пароль пользователя или другую конфиденциальную информацию.

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