Работа с ролевым и JWT-токеном

Варианты авторизации

JWT-токен

Данный тип авторизации использует JWT-токен, который приложение передаёт в SDK. Токен добавляется в заголовок каждого запроса.

JWT (JSON Web Token) — это строка в формате JSON, содержащая claims (набор данных), подписанных для проверки подлинности и целостности.

Токен формируется и подписывается ключом шифрования на стороне серверной части клиента (ключи шифрования не хранятся в приложении). По запросу SDK, приложение обязано передать полученный с сервера JWT-токен.

Преимущества:

• Повышенная безопасность API-запросов.
• Возможность поиска профилей по любым идентификаторам (email, телефон, custom ID).
• Поддержка нескольких пользователей на одном устройстве.
• Восстановление доступа к профилю после переустановки приложения.
• Идентификация конкретного профиля на разных устройствах.

rToken

Альтернативный способ авторизации — использование ролевого токена (rToken), переданного в параметры конфигурации SDK. При этом методе авторизации запросы содержат заголовок с ролевым токеном.

Особенности:

• Поиск профилей возможен только по push-токену устройства (например, FCM).
• Если push-токен изменился и не был передан на сервер (например, после удаления и переустановки приложения), связь с профилем будет потеряна, в результате будет создан новый профиль.

Ограничения:

• Потеря связи с профилем при изменении push-токена, которое не было зафиксировано на сервере Altcraft.
• Отсутствие возможности использовать приложение для разных профилей на одном устройстве.
• Невозможность регистрации одного пользователя на другом устройстве.

Настройка ролевого токена и сервиса предоставления JWT

После создания ресурса в его настройках будет доступен раздел с управлением токенами:

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

Ролевой токен выступает ключом-доступа со стороны mSDK к определённой связке "ресурс-база". В рамках авторизации с помощью данного токена будут доступны следующие действия в платформе:

• Регистрация событий
• Обновление полей профиля
• Импорт профилей

Для создания JWT-токена понадобится предоставить публичный ключ. Платформа допускает использование алгоритма ES384 (ECDSA, как наиболее надежный), но также можно использовать RS256, ES256, ES512 для совместимости с библиотеками разных приложений.

Генерация ключа

Для примера сгенерируем ключ алгоритмом ES384: openssl ecparam -name secp384r1 -genkey -noout -out private.ec.key openssl ec -in private.ec.key -pubout -out public.pem Будут сгенерированы файлы с приватным и публичным ключом. Для вставки в платформу нужен публичный ключ.

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

Авторизация запросов mSDK с помощью ролевого токена

rToken, при использовании его в авторизации, предоставляет доступ к операциям в рамках конкретного ресурса. Однако, из-за открытого формата и неизменяемого значения, вводится ограничение на используемый матчинг профилей.

Так, при использовании ролевого токена, профили ищутся по набору query-параметров. В текущей реализации backend ожидает следующие query-параметры при использовании rToken:

• provider — провайдер мобильных уведомлений
• subscription_id — токен устройства, предоставляемый провайдером

Именно по идентификатору подписки будет производиться поиск профиля в рамках БД, закреплённых за ресурсом.

Особенности

• Поиск профилей возможен только по push-токену устройства (например, FCM).
• При импорте профиля через push-подписку, он помечается как "временный".
• При регистрации мобильных событий, привязка к профилю (запись в историю событий профиля) невозможна.
• Если push-токен изменился и не был передан на сервер (например, после удаления и переустановки приложения), связь с профилем будет потеряна и будет создан новый профиль.

Использование

При использовании библиотеки Altcraft SDK токен указывается как параметр rToken класса конфигурации AltcraftConfiguration.

В дальнейшем, библиотека предоставляет его в качестве заголовка авторизации.

Авторизация запросов mSDK с помощью JWT-токена

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

Особенности

• Повышенная безопасность API-запросов. JWT выступает защитной оберткой ролевого токена, позволяя избежать неавторизованных действий. Так, ролевой токен зашивается в payload JWT-токена и лишь по предоставленным ранее (в настройках ресурса) ключам, платформа авторизует действия mSDK.
• Возможность поиска профилей по любым идентификаторам (email, телефон, custom ID), в соответствии с матчингом.
• Поддержка нескольких пользователей на одном устройстве.
• Идентификация конкретного профиля на разных устройствах.
• Восстановление доступа к профилю после переустановки приложения.

Использование

В качестве полезной нагрузки JWT, платформа ожидает следующую структуру:

{ 
"iss": "<App Name>", 
"exp": <UnixTimeUTC>, 
"rtoken": "<RoleToken>", 
"matching": "JSONString", 
}

• iss — issuer — уникальный идентификатор создателя токена
• exp — expiration time — время истечения токена в формате UNIX timestamp в секундах
• rtoken — ролевой токен, полученный при настройке ресурса в платформе
• matching— JSONString — сериализованный в строку объект, составленный в соответствии с документацией. Например: {"db_id":2,"email":"registered_db@localhost","matching":"email_profile"}.

При использовании библиотеки Altcraft SDK передаётся как имплементация интерфейса авторизации JWTInterface. В дальнейшем, библиотека также предоставляет его в качестве заголовка авторизации.

Пример того, как может выглядеть итоговый JWT: