Миграция с AppAuth на Versola OAuth SDK

Чтобы перейти с AppAuth-Android, AppAuth-iOS или flutter_appauth (он оборачивает обе библиотеки) на Versola OAuth SDK, код запроса, redirect и хранения токенов заменяют одним OAuthClient и одним вызовом login(). На странице сопоставлены понятия AppAuth и SDK, перечислено, что вы перестаете делать и что ведет себя иначе, и показан код до и после для Android, iOS и Flutter. Условие: SDK рассчитан на публичные клиенты, которые входят через системный браузер, поэтому сначала прочитайте Что умеет AppAuth, но не умеет SDK?

Предварительные требования

• Приложение, которое сейчас входит через AppAuth-Android, AppAuth-iOS или flutter_appauth.
• Клиент у провайдера, который можно зарегистрировать как публичный: без секрета, с PKCE S256.
• Страница вашего провайдера в разделе Провайдеры, например Keycloak: там scope, redirect URI и выход.

Что меняется, когда вы заменяете AppAuth?

• Приложение больше не хранит состояние аутентификации. Нет AuthState, который нужно сериализовать, и нет refresh token у вас в руках. Хранение, обновление и выход ведет OAuthClient, а вы наблюдаете за сессией.
• Вход — один вызов, login(). PKCE, state, nonce, проверка redirect, обмен кода и проверка ID token происходят внутри него и не отключаются.
• Versola OAuth SDK защищает каждый сохраненный токен через Android Keystore или iOS Keychain.
• После обновления пользователи входят один раз, потому что существующие refresh token импортировать нельзя (см. Что будет с текущими пользователями и токенами?).
• Сбои провайдера приходят в приложение в виде четырех категорий ошибок, а безопасные запросы SDK повторяет сам (см. Как меняется обработка ошибок?).

Как понятия AppAuth соответствуют понятиям SDK?

Имена Kotlin взяты из versola.oauth (типы ошибок и состояний — из versola.oauth.core), имена Swift — из модуля OAuthClient (продукт пакета VersolaOAuth), имена Dart — из package:versola_oauth/versola_oauth.dart.

Что вы перестаете делать?

• Хранить AuthState. Ни сериализации, ни кода для токенов в SharedPreferences или Keychain, ни собственного AuthStateManager. После перезапуска create() без сетевых запросов восстанавливает Authenticated, а если приложение убили посреди браузера — Authorizing.
• Координировать обновление. Параллельные вызывающие сливаются в один refresh. Новый refresh token сохраняется раньше, чем забывается старый, и дважды не тратится. invalid_grant — это Reauthenticate(GrantRejected), а не повод для повтора.
• Возиться с PKCE, state и nonce. SDK генерирует их из защищенного источника случайных чисел платформы, сохраняет до открытия браузера и проверяет при возврате. Вы их не передаете, не храните и не сравниваете.
• Проверять ID token. Проверка идет до того, как грант сохраняется (см. Что в поведении отличается от AppAuth?). Отдельная JWT-библиотека для нее не нужна.
• Передавать redirect библиотеке. На Android его принимает activity SDK или возвращает Auth Tab. На iOS его возвращает системная сессия. handleRedirect нужен только для Universal Link при холодном старте.
• Подставлять токены. Interceptor или аутентифицированная сессия добавляет Authorization к запросам на названные вами origin, один раз обновляет токен при 401 и один раз повторяет запрос.
• Писать циклы повторов вокруг 500, 503 и 429. SDK повторяет запросы, которые безопасно повторять, и ждет столько, сколько просит провайдер (см. Как меняется обработка ошибок?).

Что в поведении отличается от AppAuth?

В местах ниже SDK проверяет больше, чем AppAuth. Поэтому провайдер, который работал с AppAuth, при первом запуске может дать ошибку Configuration: она показывает, что нужно исправить у провайдера или в регистрации клиента.

Что умеет AppAuth, но не умеет SDK?

Versola OAuth SDK — библиотека для публичных клиентов, потока authorization code и системного браузера. У возможностей AppAuth, которые в эту схему не входят, аналогов нет: публичных символов для них нет ни на одной из трех платформ. Сверьте список со своей текущей настройкой до начала работы.

• Секреты клиентов и конфиденциальные клиенты. Поля для секрета в конфигурации нет, так задумано (RFC 8252, раздел 8.5). Если клиент у провайдера использует секрет, зарегистрируйте для приложения отдельный публичный клиент без секрета. Провайдер, который требует секрет от нативного приложения, не поддерживается.
• Другая аутентификация клиента на token endpoint (в AppAuth-Android есть тип ClientAuthentication). Запрос токена несет только client_id.
• Динамическая регистрация клиента (RegistrationRequest / OIDRegistrationRequest в AppAuth). Аналога нет.
• Встроенные user agent. Web view передать нельзя.
• Выбор браузера. Нет ни списка разрешенных, ни списка запрещенных, ни своего браузера, ни своего intent для Custom Tabs.
• Discovery по своему URL (fetchFromUrl). Используйте явные эндпоинты.
• Разделение потока. У Flutter authorize с последующим token(code) и у ручного performTokenRequest аналога нет. login() атомарен, и приложению ни код авторизации, ни verifier, ни nonce не отдаются.
• Чтение и подстановка refresh token. Ваш бэкенд не получит refresh token приложения, а у token(TokenRequest(... refreshToken: ...)) аналога нет. refresh() расходует сохраненный токен.
• Сырой ID token. claims отдает типизированные claims проверенного токена, а сам токен хранится зашифрованным только для id_token_hint. Если бэкенду нужен именно ID token, этот SDK его дать не может.
• Отключение проверок. setNonce(null) и setSkipIssuerHttpsCheck(true) (AppAuth-Android), issuer не по https, отсутствующий iss и непроверенный ID token отклоняются. Провайдер, которому нужно что-то из этого, с SDK работать не сможет.
• Несколько аккаунтов одновременно. Одна сессия на конфигурацию. Конфигурация с другим issuer или clientId — отдельный клиент со своим хранилищем.
• macOS, tvOS и десктоп. AppAuth-iOS документирует поддержку macOS и tvOS. SDK рассчитан на Android и iOS, а Flutter — на эти две платформы.
• Параметр в запросе токена. extraParameters уходит в запрос авторизации. Запрос токена несет то, что собирает SDK, и resource, если вы задали resources.
• Свой user agent и перехват запросов за пределами HTTP-клиента. Единственная точка вмешательства — httpClient / urlSession.

Что будет с текущими пользователями и токенами?

Существующие refresh token импортировать нельзя, поэтому каждый пользователь входит один раз после обновления. Ни одно публичное объявление трех платформ (дамп API Android, public-поверхность OAuthClient в Swift, экспорты versola_oauth в Dart) не принимает refresh token, ID token или сериализованное состояние, и в типах конфигурации нет поля для них. Хранилища, где лежат эти данные, — внутренняя обвязка за маркером @VersolaInternalApi на Android и package-доступом на iOS. Первый create() ничего не находит и сообщает Unauthenticated.

Планируйте выкатку с учетом этого:

1. Выпустите SDK в обновлении приложения и считайте первый запуск входом с нуля. Покажите свой экран входа. В большинстве случаев login() завершается по уже существующей сессии пользователя у провайдера: пароль вводить не нужно, если браузер еще авторизован.
2. Удалите старое состояние. После первого успешного login() сотрите сохраненное состояние AppAuth: JSON AuthState в SharedPreferences или там, куда его положил ваш менеджер, архивированный OIDAuthState в Keychain или в defaults и токены, которые вернул flutter_appauth, если вы их сохраняли (например, в плагине secure storage). Забытый refresh token — это учетные данные, которыми никто не пользуется и которые никто не охраняет.
3. При желании отзовите старый refresh token у провайдера до удаления, если у него есть эндпоинт отзыва (RFC 7009: client_id и token, для публичного клиента без секрета). SDK сделать это за вас не может, потому что этот токен он никогда не видит.
4. Не снимайте старый redirect URI с регистрации, пока в ходу старые версии приложения. Если вы переходите с пользовательской схемы на https App Link или Universal Link, добавьте новый URI. Старый не заменяйте, пока старые версии не исчезнут.
5. Если старый клиент использовал секрет, SDK нужен другой клиент у провайдера, зарегистрированный как публичный. Зарегистрируйте его рядом со старым и переведите приложение на него.
6. clientId и redirect URI могут остаться прежними. SDK хранит данные под ключом из issuer и clientId и хранилище AppAuth не читает.

Как меняется обработка ошибок?

AppAuth сообщает о сбое типом исключения или кодом платформы (AuthorizationException на Android, NSError на iOS, исключения FlutterAppAuth во Flutter), а повторы оставляет приложению. Versola OAuth SDK относит каждый сбой к одной из четырех категорий, и категория подсказывает приложению, что делать:

Когда провайдер отвечает 500, 503 или 429, SDK повторяет запросы, которые безопасно повторять, ждет столько, сколько просит Retry-After, и только потом возвращает одну ошибку Recoverable. Своих циклов повторов для этих случаев приложению не нужно. Правила и код для каждой платформы — на странице Ошибки сервера, 429 и Retry-After.

Как перейти с AppAuth-Android?

Часть про AppAuth ниже сокращена из примеров README. Часть про SDK — целевой API.

До (AppAuth-Android)

// build.gradle: manifestPlaceholders = ['appAuthRedirectScheme': 'com.example.app']
AuthorizationServiceConfiguration.fetchFromIssuer(Uri.parse("https://id.example.com")) { config, ex ->
    val request = AuthorizationRequest.Builder(
        config!!, "example-app", ResponseTypeValues.CODE, Uri.parse("com.example.app:/oauth"),
    ).setScope("openid profile").build()
    // performAuthorizationRequest(request, completionIntent, cancelIntent), then in the
    // completion activity: AuthorizationResponse.fromIntent(intent), AuthState.update(...),
    // authService.performTokenRequest(resp.createTokenExchangeRequest(), callback)
}

// Later, with state restored from AuthState.jsonDeserialize(json):
authState.performActionWithFreshTokens(authService) { accessToken, idToken, ex ->
    // write the updated AuthState back, then call the API with accessToken
}

После (Versola OAuth SDK)

1. Зависимость. Удалите net.openid:appauth. Подключите SDK из Maven Central: в репозиториях должны быть google() и mavenCentral(). minSdk становится 26.

   dependencies {
       implementation("io.versola:oauth-android:<version>")
   }

2. Манифест. Удалите плейсхолдер appAuthRedirectScheme и любой фильтр на net.openid.appauth.RedirectUriReceiverActivity. Добавьте intent filter на activity SDK для вашего redirect URI, фрагмент есть на странице Android. Для проверенного App Link еще отдайте assetlinks.json на хосте.

3. Создайте клиент один раз, с тем же issuer, client id и scope. Используйте https redirect URI, если его можно зарегистрировать у провайдера.

   val client = OAuthClient.create(
       context,
       OAuthConfiguration(
           issuer = "https://id.example.com",
           clientId = "example-app",
           redirectUri = "https://app.example.com/oauth",
           postLogoutRedirectUri = "https://app.example.com/signed-out",
           scopes = setOf("openid", "profile"),
           protectedOrigins = setOf("https://api.example.com"),
       ),
   )

4. Вход. Запрос, activity для redirect и обмен токена заменяются одним вызовом:

   scope.launch {
       try {
           client.login()
       } catch (e: VersolaError) {
           // Recoverable, Reauthenticate, StepUp or Configuration
       }
   }

5. Вызовы вашего API. performActionWithFreshTokens и запись AuthState обратно замените interceptor в своем OkHttpClient или client.call(request):

   val http = OkHttpClient.Builder()
       .addInterceptor(client.interceptor())
       .build()

   Если нужно само значение, client.accessToken() возвращает AccessToken. Это запасной выход: токен, попавший в ваш код, можно по ошибке залогировать.

6. Наблюдайте за сессией вместо чтения своего сохраненного состояния: подпишитесь на client.sessionState.

7. Выход — client.logout(). Он возвращает LogoutOutcome(sessionEnded, tokenRevoked).

8. Удалите старое хранилище AuthState (см. Что будет с текущими пользователями и токенами?).

Как перейти с AppAuth-iOS?

До (AppAuth-iOS)

OIDAuthorizationService.discoverConfiguration(forIssuer: issuer) { configuration, error in
    guard let configuration else { return }
    let request = OIDAuthorizationRequest(
        configuration: configuration, clientId: clientID,
        clientSecret: clientSecret,  // the README's sample passes a secret; a public client has none
        scopes: [OIDScopeOpenID, OIDScopeProfile], redirectURL: redirectURI,
        responseType: OIDResponseTypeCode, additionalParameters: nil)
    appDelegate.currentAuthorizationFlow =
        OIDAuthState.authState(byPresenting: request, presenting: self) { authState, error in
            // keep authState
        }
}

func application(_ app: UIApplication, open url: URL,
                 options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    if let flow = self.currentAuthorizationFlow {
        try? flow.resumeExternalUserAgentFlow(url)  // abridged: the README also handles the error
        self.currentAuthorizationFlow = nil
        return true
    }
    return false
}

authState?.performAction { accessToken, idToken, error in
    // call the API with accessToken
}

После (Versola OAuth SDK)

1. Зависимость. Уберите AppAuth из пакета или проекта Xcode. Добавьте публичный репозиторий SDK и продукт VersolaOAuth, затем import OAuthClient. Пакету нужна iOS 17.4.

   dependencies: [
       .package(url: "https://github.com/versolauth/versola-sdk", from: "<version>"),
   ],
   targets: [
       .target(
           name: "App",
           dependencies: [.product(name: "VersolaOAuth", package: "versola-sdk")]
       ),
   ]

2. Entitlements для https redirect: Associated Domains для хоста и файл apple-app-site-association, как описано на странице iOS. Приватной схеме все это не нужно, но она пишет предупреждение.

3. Создайте клиент (асинхронно, один раз). presentationAnchor — замыкание, которое возвращает окно, из которого показывается лист браузера:

   let configuration = try OAuthConfiguration(
       issuer: "https://id.example.com",
       clientId: "example-app",
       redirectUri: "https://app.example.com/oauth",
       postLogoutRedirectUri: "https://app.example.com/signed-out",
       scopes: ["openid", "profile"],
       protectedOrigins: ["https://api.example.com"]
   )
   let client = try await OAuthClient.create(
       configuration: configuration,
       presentationAnchor: { window }  // a UIWindow the app owns
   )

4. Вход. Удалите currentAuthorizationFlow и обвязку application(_:open:options:):

   do {
       try await client.login()
   } catch let error as OAuthError {
       // .recoverable, .reauthenticate, .stepUp or .configuration
   }

   Оставьте один обработчик, только для Universal Link, которые приходят при холодном старте приложения:

   .onOpenURL { url in
       Task { _ = await client.handleRedirect(url) }
   }

5. Вызовы вашего API идут через аутентифицированную сессию вместо performAction:

   let session = try client.authenticatedSession()
   let (data, response) = try await session.data(for: URLRequest(url: apiURL))

   Или вызовите try await client.accessToken() там, где нужно само значение.

6. Наблюдайте через for await state in await client.sessionStates() { ... }.

7. Выход — await client.logout(), он возвращает LogoutOutcome.

8. Удалите архивированный OIDAuthState (см. Что будет с текущими пользователями и токенами?).

Как перейти с flutter_appauth?

До (flutter_appauth)

final appAuth = FlutterAppAuth();
final result = await appAuth.authorizeAndExchangeCode(
  AuthorizationTokenRequest(
    '<client_id>',
    '<redirect_url>',
    issuer: '<issuer>',
    scopes: ['openid', 'profile', 'offline_access'],
  ),
);
// You store result's tokens, and later refresh with
// appAuth.token(TokenRequest('<client_id>', '<redirect_url>', refreshToken: ..., ...)).
await appAuth.endSession(EndSessionRequest(
  idTokenHint: '<idToken>',
  postLogoutRedirectUrl: '<postLogoutRedirectUrl>',
  issuer: '<issuer>',
));

После (versola_oauth)

1. Зависимость. Замените flutter_appauth в pubspec.yaml на versola_oauth. Установка описана на странице Flutter. Уберите собственную настройку плагина: appAuthRedirectScheme на Android и пользовательскую схему CFBundleURLTypes на iOS, если только вы не оставляете redirect на пользовательскую схему.

2. Нативная настройка в приложении-хосте. Android: intent filter для VersolaRedirectActivity. iOS: iOS 17.4 или новее, Associated Domains для https redirect и VersolaOAuthPlugin.presentationAnchor, если в приложении своя работа с окнами. См. страницу Flutter.

3. Создание и использование:

   final client = await OAuthClient.create(const OAuthConfiguration(
     issuer: 'https://id.example.com',
     clientId: 'example-app',
     redirectUri: 'https://app.example.com/oauth',
     postLogoutRedirectUri: 'https://app.example.com/signed-out',
     scopes: {'openid', 'profile'},
   ));
   
   client.sessionStates().listen((state) => print(state));
   
   try {
     await client.login();
     final token = await client.accessToken(); // the only credential that crosses the bridge
   } on StepUpError catch (e) {
     await client.stepUp(e);
   } on ReauthenticateError {
     // sign in again
   } on RecoverableError {
     // retry, or ask the user again
   } on ConfigurationError {
     // a deployment mistake
   }

4. Уберите свое хранилище токенов. В Dart не остается ничего, похожего на учетные данные, поэтому удалите код, который хранит и обновляет токены. accessToken() обновляет токен нативно.

5. Выход — client.logout(). Он возвращает LogoutOutcome.

6. Ошибки. FlutterAppAuthUserCancelledException превращается в RecoverableError, а платформенное исключение — в подходящую категорию.

Аутентифицированного HTTP-клиента в Dart нет. Вызывайте свой API со значением, которое возвращает accessToken(), и запрашивайте его заново для каждого запроса или пачки запросов, а не кэшируйте.

Чек-лист миграции

• Клиент у провайдера публичный, у него включен PKCE S256, и нигде не используется секрет.
• Настроенный issuer равен члену issuer в документе discovery.
• offline_access указан в scopes, если провайдеру он нужен для refresh token (см. Провайдеры).
• Redirect URI зарегистрирован у провайдера точно так, как настроен, а для https отдаются assetlinks.json или файл apple-app-site-association приложения.
• postLogoutRedirectUri зарегистрирован у провайдера.
• Никакой код не читает, не пишет и не отправляет refresh token или сырой ID token.
• Старый AuthState (или архивированный OIDAuthState, или хранилище токенов в Dart) удален после первого успешного login().
• Ваш экран входа обрабатывает четыре категории ошибок, а ошибка Configuration в продакшене не перехватывается молча.

Источники

Факты об AppAuth на этой странице прочитаны 2026-10-30. Часть про SDK основана на собственной спецификации API SDK и его публичных объявлениях.

• README AppAuth-Android: https://github.com/openid/AppAuth-Android. Использован для конфигурации и discovery, запроса и intent, redirect (appAuthRedirectScheme, RedirectUriReceiverActivity), хранения AuthState и performActionWithFreshTokens, EndSessionRequest, секретов клиентов и динамической регистрации, списков разрешенных и запрещенных браузеров, утверждения про WebView, PKCE, уровней API, setNonce(null) и setSkipIssuerHttpsCheck.
• AppAuth-Android IdToken.java: проверки ID token и утверждение, что подпись не проверяется.
• README AppAuth-iOS: https://github.com/openid/AppAuth-iOS и https://raw.githubusercontent.com/openid/AppAuth-iOS/master/README.md. Использован для discovery, OIDAuthorizationRequest, OIDAuthState.authState(byPresenting:presenting:), resumeExternalUserAgentFlow, performAction, user agent, WebView, PKCE, HTTPS redirect и требования webcredentials, минимальных версий ОС.
• Индекс API AppAuth-iOS, список классов (end session, регистрация, запрос токена): https://openid.github.io/AppAuth-iOS/docs/latest/annotated.html, и OIDIDToken: https://openid.github.io/AppAuth-iOS/docs/latest/interface_o_i_d_i_d_token.html.
• README flutter_appauth: https://github.com/MaikuB/flutter_appauth и https://raw.githubusercontent.com/MaikuB/flutter_appauth/master/flutter_appauth/README.md.

Что дальше

• Android, iOS и Flutter: настройка SDK на каждой платформе.
• Состояния сессии и ошибки: четыре категории ошибок и семь состояний сессии, которые обрабатывает ваш экран входа.
• Ошибки сервера, 429 и Retry-After: что SDK повторяет сам и что делает с остальным приложение.
• Провайдеры: redirect URI, scope и выход для вашего провайдера, например Keycloak.