SDK для реализации функций аутентификатора в сторонних мобильных приложениях

Общая часть

SDK (Software Development Kit) – это набор инструментов, библиотек, документации и примеров кода, которые позволяют разработчикам создавать программное обеспечение для определенной платформы или в конкретной среде. Другими словами, SDK, предоставленное разработкой, дает всё необходимое для разработки приложений, включая:

• инструменты для написания, тестирования и отладки кода; 
• документацию по платформе; 
• а также примеры кода, которые позволяют быстро изучить основные принципы работы с SDK.

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

Спецификация методов и описание последовательности их вызовов

Привязка аккаунта по QR-коду: bindNewAccountViaQR(serverPath, signature, bindRequest)

Для авторизации часто используется один из способов – отсканировать QR-код с помощью другого устройства. Ниже указан набор параметров для реализации такой привязки аккаунта.

Разработчик приложения выполняет следующие операции при работе с SDK:

• Получение QR-кода.
• Преобразование полученного QR-кода в строку.
• Выпуск RSA-ключа и сохранение его в локальном хранилище.
• Отображение информации об успешной привязке пользователю.

Входные данные:

• serverPath – адрес сервера, issuer – значение, получаемое из QR-кода.
• signature – подписанная приватным ключом из локального хранилища строка RandomBind, полученная после преобразования QR-кода.
• bindRequest
  • transactionId – идентификатор транзакции
  • publicKey – публичный ключ RSA пары
  • deviceInfo – объект типа DeviceInfo
    • identifier – UUID значение
    • name – наименование устройства
    • version – версия устройства
    • platform – платформа устройства, принимает следующие значения в зависимости от платформы:
      • Android.
      • HarmonyOS (для устройств на базе HUAWEI).
      • iOS.
    • deviceToken - токен, полученный из Firebase-сервиса.

Результат приходит в виде HTTP-ответа на запросы:

• HttpResponse:
  • Статус ответа.
  • Структура с информацией о привязке.

Разработчик приложения выполняет следующие действия:

• Обработку ответа сервера.
• При успешной привязке аккаунта, сохраняет сведения в локальном хранилище приложения.
• Производит расшифровку EncryptedSecret по указанному алгоритму:
  
  • SHA-256 – encryption Oaep with MGF1-SHA256.
  • SHA-512 – encryption Oaep with MGF1-SHA512.
• Сохраняет расшифрованный секрет TOTP в безопасном хранилище, для дальнейшего формирования TOTP-кода.

Получение строки для привязки аккаунта по одноразовому коду: getJsonInfoViaTempCode(serverPath, tempCode)

Для авторизации часто используется один из способов – ввод одноразового кода, полученного пользователем. Ниже указан набор параметров для реализации такой привязки аккаунта.

Разработчик приложения выполняет:

• Подключение хранилища Cloud Storage for Firebase.
• Получение одноразового кода из коллекции в хранилище Firebase.

Входные данные:

• serverPath – адрес сервера.
• tempCode – одноразовый код.

Результат приходит в виде HTTP-ответа на запросы:

• HttpResponse
  • Статус ответа
  • Строка с параметрами, для привязки аккаунта
    • issuer – адрес сервера.
    • secret – TOTP-секрет.
    • randomBind – случайным образом сгенерированная строка для формирования подписи на привязку аккаунта.
    • randomUnbind – случайным образом сгенерированная строка для формирования подписи на удаление привязки.
    • organizationName – наименование организации.
    • transactionId – идентификатор транзакции.
    • enc – алгоритм, используемый для расшифровки секрета.

Разработчик приложения выполняет:

• Обработку ответа сервера.
• Преобразование строки для привязки аккаунта.
• Формирование запроса привязки аккаунта.

Получение требований безопасности сервера: getSecurityPolicyRequest(serverPath)

При обмене данными необходимо учитывать требования безопасности сервера.

Входные данные:

• serverPath – адрес сервера

Результат приходит в виде HTTP-ответа на запросы:

• HttpResponse
  • Статус ответа.
  • Структура с информацией об имеющихся требований безопасности.

Разработчик приложения выполняет:

• Сохраняет требования в локальном хранилище приложения

Обработка запроса на аутентификацию: handleAuthPushRequest(serverPath, signature, pushId, bindingId, approveType)

Разработчик приложения выполняет:

• Реализация метода OnMessageReceived средствами Firebase, для получения запросов на аутентификацию.
• Получение и обработка запроса.
• Формирование пуш-уведомления для отображения пользователю.
• Поиск активной привязки по BindingId.

Входные данные:

• serverPath – адрес сервера.
• signature – подписанная приватным ключом строка RandomString.
• pushId – идентификатор уведомления, полученный в теле запроса на аутентификацию.
• bindingId – идентификатор привязки, полученный после привязки.
• approveType - тип подтверждения, принимает значение approve/deny.

Результат приходит в виде HTTP-ответа на запросы:

• HttpResponse.

Разработчик приложения выполняет:

• Обработку ответа сервера.

Внедрение сборки в мобильное приложение iOS

Через Xcode

File -> Add packages -> https://devenv.avanpost.ru/published/mobile-authenticator-sdk.git.

Через Package.swift

Чтобы интегрировать AvanpostSDK в ваш проект при помощи Package.swift, нужно указать зависимость:

dependencies: [
  .package(url: "https://devenv.avanpost.ru/published/mobile-authenticator-sdk.git", .branch("master"),

Внедрение jar сборки в мобильное приложение Android

Необходимо найти файт build.gradle (файл сборки на уровне проекта, который определяет конфигурации сборки на уровне проекта). Когда вы включаете внешние библиотеки, вам необходимо упомянуть об этом в файле gradle уровня приложения, чтобы включить их в свой проект в качестве зависимостей приложения. В него следует добавить строку подключения для осуществленной сборки:

implementation(fileTree(mapOf(
"dir" to "<путь к файлу>AvanpostSDK.jar",
"include" to listOf("*.aar", "*.jar")
)))

Для вызова методов необходимо вызвать класс AvanpostHttpClient и импортировать пакет sdk:

import ru.avanpost.authenticator.avanpostsdk.AvanpostHttpClient