Мобильные SDK

Versola OAuth SDK проводит вход через системный браузер, хранит сессию в защищенном хранилище платформы, обновляет ее и подставляет токен в вызовы API, так что собирать все это по частям не нужно. SDK есть для Android (Kotlin), iOS (Swift 6) и Flutter, где это обертка над двумя нативными SDK. Нужен провайдер, который подходит под контракт со страницы Руководства по провайдерам.

Как установить Versola OAuth SDK?

У каждой платформы своя зависимость и свое руководство.

Там, где в примерах стоит <version>, подставьте текущую версию SDK. Она показана в верхней панели этих страниц и на странице Releases.

Шаги настройки, объявление редиректа и работающий вход описаны в руководствах Android, iOS и Flutter.

Как это устроено

Логика протокола написана один раз для каждой нативной платформы, на Kotlin для Android и на Swift для iOS, по общей спецификации. Flutter — обертка над двумя нативными SDK, поэтому логика протокола в Dart не выполняется. Все платформы отдают один и тот же OAuthClient, те же семь состояний сессии и те же четыре категории ошибок.

Что делает SDK без лишнего кода?

Каждый пункт — правило SDK, и ни одно не отключается.

• PKCE с S256, свежие state и nonce на каждый запрос из генератора случайных чисел платформы и проверка редиректа (state, затем iss по RFC 9207, если провайдер объявляет или присылает его, затем code) до любого сетевого запроса.
• Проверка ID-токена до того, как что-либо сохранено: подпись по ключам провайдера, iss, aud и azp, exp и iat с ограниченным допуском на расхождение часов (по умолчанию 60 s, максимум 5 минут), nonce и auth_time при max_age.
• Обновление в одном полете: параллельные вызовы делят один запрос токена, а ротированный refresh-токен сохраняется раньше, чем забывается старый.
• Защищенное хранилище: файлы под noBackupFilesDir, обернутые ключом Keystore, на Android; Keychain с AfterFirstUnlockThisDeviceOnly и без синхронизации с iCloud на iOS.
• Только системный браузер: Auth Tab или Custom Tab на Android, ASWebAuthenticationSession на iOS. Передать web view нельзя.
• Токен уходит только на источники (origins), перечисленные в protectedOrigins. Запрос на любой другой источник проходит нетронутым, а редиректы на защищенных запросах не выполняются.
• DPoP (RFC 9449), если вы включили его и провайдер объявляет ES256, с неизвлекаемым ключом в аппаратном хранилище. Иначе bearer с предупреждением в логе или ошибка, если вы сделали DPoP обязательным.
• Pushed authorization requests (RFC 9126), если провайдер объявляет для них эндпоинт.
• Секрета клиента нет: нативное приложение не может его хранить, поэтому в конфигурации под него нет поля.

Если проверку не удалось завершить, операция падает с типизированной ошибкой. Выключить проверку нельзя, и ни одну не ослабляют ради того, чтобы заработал какой-то провайдер. Подробнее: Состояния сессии и ошибки.

Какие провайдеры поддерживаются?

От провайдера SDK ждет четыре вещи: discovery (или явные эндпоинты), authorization code flow с PKCE S256 для публичного клиента, ID-токен с асимметричной подписью и claim iss, равный объявленному издателю. Все остальное определяется по discovery, и SDK подстраивается под то, чего нет.

Подробности, включая то, какому провайдеру для refresh-токена нужен offline_access и у кого нет эндпоинта выхода, на странице Руководства по провайдерам.

Как тестируется SDK?

В таблице — то, что прогоняют собственные тесты SDK на каждой платформе.

Что дальше

• Android, iOS и Flutter: установка SDK и вход на вашей платформе.
• Руководства по провайдерам: контракт провайдера и то, чем вендоры отличаются.
• Состояния сессии и ошибки: семь состояний и четыре категории ошибок, общие для всех платформ.
• Ошибки сервера, 429 и Retry-After: что SDK повторяет, когда провайдер отвечает 500, 503 или 429, и какой код нужен приложению.