Перейти к основному содержимому
Документация для версии v74

Работа с ролевым и 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:

Последнее обновление