Migrate from AppAuth to the Versola OAuth SDK

To migrate from AppAuth-Android, AppAuth-iOS or flutter_appauth (which wraps both) to the Versola OAuth SDK, you replace the request, redirect and token-storage code with one OAuthClient and one login() call. This page maps AppAuth concepts to the SDK, lists what you stop doing and what behaves differently, and shows before and after code for Android, iOS and Flutter. The condition: the SDK serves public clients that sign in through the system browser, so read What does AppAuth do that the SDK does not do? first.

Prerequisites

• An app that signs in with AppAuth-Android, AppAuth-iOS or flutter_appauth today.
• A provider client you can register as public: no secret, PKCE S256.
• The provider’s page in Providers, for example Keycloak, to check scopes, redirect URIs and sign-out.

What changes when you replace AppAuth?

• Your app stops holding authentication state. There is no AuthState to serialize and no refresh token in your hands. OAuthClient owns storage, refresh and sign-out, and you observe a session.
• Sign-in is one call, login(). PKCE, state, nonce, redirect validation, the code exchange and ID-token validation happen inside it and cannot be switched off.
• The Versola OAuth SDK protects every stored token with the Android Keystore or the iOS Keychain.
• Users sign in once after the update, because existing refresh tokens cannot be imported (see What happens to existing users and tokens?).
• Provider failures reach your app as four error categories, and the SDK repeats safe requests itself (see How does error handling change?).

How do AppAuth concepts map to the SDK?

Kotlin names are from versola.oauth (and versola.oauth.core for the error and state types), Swift names from the module OAuthClient (package product VersolaOAuth), Dart names from package:versola_oauth/versola_oauth.dart.

What do you stop doing?

• Persisting AuthState. No serialization, no SharedPreferences or Keychain code for tokens, no AuthStateManager of your own. After a restart create() restores Authenticated without network I/O, or Authorizing if the app was killed mid-browser.
• Coordinating refresh. Concurrent callers coalesce onto one refresh. A rotated refresh token is stored before the old one is forgotten and is never spent twice. invalid_grant is Reauthenticate(GrantRejected), not a retry.
• Handling PKCE, state and nonce. The SDK generates them from the platform’s secure random source, persists them before the browser opens and validates them on return. You don’t pass, store or compare them.
• Validating the ID token. It happens before the grant is persisted (see What behaves differently from AppAuth?). You don’t need a separate JWT library for it.
• Handing a redirect to the library. On Android the SDK’s activity receives it, or the Auth Tab returns it. On iOS the system session returns it. Only a cold-start Universal Link needs handleRedirect.
• Attaching tokens. The interceptor or the authenticated session adds Authorization to requests for the origins you named, refreshes once on a 401 and replays once.
• Writing retry loops around 500, 503 and 429. The SDK repeats the requests that are safe to repeat and waits as long as the provider asks (see How does error handling change?).

What behaves differently from AppAuth?

The SDK checks more than AppAuth does in the places below. A provider that worked with AppAuth can therefore fail with a Configuration error on the first run, which tells you what the provider or the client registration needs to fix.

What does AppAuth do that the SDK does not do?

The Versola OAuth SDK is a public-client, authorization-code, system-browser library. AppAuth features outside that shape have no counterpart: the three platforms declare no public symbol for them. Check this list against your current setup before you start.

• Client secrets and confidential clients. The configuration has no secret field, by design (RFC 8252 section 8.5). If your provider client uses a secret, register a secret-less public client for the app. A provider that insists on a secret from a native app is unsupported.
• Other client authentication at the token endpoint (AppAuth-Android has a ClientAuthentication type). The token request carries client_id only.
• Dynamic client registration (AppAuth RegistrationRequest / OIDRegistrationRequest). No counterpart.
• Embedded user agents. A web view cannot be passed in.
• Choosing the browser. No allow list, deny list, custom browser or custom Custom Tabs intent.
• Discovery at a custom URL (fetchFromUrl). Use explicit endpoints.
• Splitting the flow. Flutter’s authorize followed by token(code), or a manual performTokenRequest, has no counterpart. login() is atomic, and no authorization code, verifier or nonce is ever handed to the app.
• Reading or injecting the refresh token. Your backend cannot receive the app’s refresh token, and token(TokenRequest(... refreshToken: ...)) has no counterpart. refresh() spends the stored token.
• The raw ID token. claims exposes the typed claims of the validated token, and the raw token stays encrypted for id_token_hint only. If a backend needs the ID token itself, this SDK cannot supply it.
• Turning off checks. setNonce(null) and setSkipIssuerHttpsCheck(true) (AppAuth-Android), a non-https issuer, a missing iss and an unverified ID token are all refused. A provider that needs one of them can’t be used with the SDK.
• Several accounts at once. One session per configuration. A configuration with another issuer or clientId is a separate client with its own storage.
• macOS, tvOS and desktop. AppAuth-iOS documents macOS and tvOS support. The SDK targets Android and iOS, and Flutter on those two.
• A parameter on the token request. extraParameters goes on the authorization request. The token request carries what the SDK builds, plus resource when you gave resources.
• Custom user-agent or request interception beyond the HTTP client. httpClient / urlSession is the only seam.

What happens to existing users and tokens?

Existing refresh tokens cannot be imported, so every user signs in once after the update. No public declaration of the three platforms (the Android API dump, the Swift public surface of OAuthClient, the Dart exports of versola_oauth) accepts a refresh token, an ID token or a serialized state, and the configuration types have no field for one. The credential stores that hold them are internal wiring, behind the @VersolaInternalApi opt-in marker on Android and package access on iOS. The first create() finds nothing and reports Unauthenticated.

Plan the rollout around that:

1. Ship the SDK in the app update and treat the first launch as signed out. Show your sign-in screen. In most cases login() completes with the user’s existing provider session, with no password entry if the browser is still signed in.
2. Delete the old state. After the first successful login(), remove the persisted AppAuth state: the AuthState JSON in SharedPreferences or wherever your own manager put it, the archived OIDAuthState in the Keychain or in defaults, and the tokens flutter_appauth returned if you kept them (for example in a secure-storage plugin). A leftover refresh token is a credential that nobody uses and nobody guards.
3. Optionally revoke the old refresh token at the provider before you delete it, if the provider has a revocation endpoint (RFC 7009: client_id and token, no secret for a public client). The SDK can’t do it for you, because it never sees that token.
4. Keep the old redirect URI registered while old app versions are in use. If you move from a custom scheme to an https App Link or Universal Link, add the new URI. Don’t replace the old one until the old versions are gone.
5. If the old client used a secret, the SDK needs a different provider client, registered as public. Register it next to the old one and move the app over.
6. The same clientId and redirect URI can stay. The SDK keys its storage by issuer and clientId, and it does not read AppAuth’s.

How does error handling change?

AppAuth reports a failure as a platform exception type or code (AuthorizationException on Android, NSError on iOS, FlutterAppAuth exceptions in Flutter) and leaves retries to your app. The Versola OAuth SDK sorts every failure into one of four categories, and the category tells the app what to do:

When a provider answers 500, 503 or 429, the SDK repeats the requests that are safe to repeat, waits as long as Retry-After asks, and then returns one Recoverable error. Your app needs no retry loops of its own for these cases. The rules, with code for each platform, are on Server errors, 429 and Retry-After.

How do I migrate from AppAuth-Android?

The AppAuth side below is abridged from the README’s examples. The SDK side is the target API.

Before (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
}

After (Versola OAuth SDK)

1. Dependency. Remove net.openid:appauth. Add the SDK from Maven Central, with google() and mavenCentral() in your repositories. minSdk becomes 26.

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

2. Manifest. Remove the appAuthRedirectScheme placeholder and any net.openid.appauth.RedirectUriReceiverActivity filter. Add the intent filter on the SDK’s activity for your redirect URI; the snippet is on the Android page. For a verified App Link, also serve assetlinks.json on the host.

3. Create the client once, with the same issuer, client id and scopes. Use an https redirect URI if you can register one with the provider.

   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. Sign in. Replace the request, the redirect activity and the token exchange with one call:

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

5. Call your API. Replace performActionWithFreshTokens and the AuthState write-back with the interceptor on your own OkHttpClient, or with client.call(request):

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

   If you need the value, client.accessToken() returns an AccessToken. It is the escape hatch, and a token handed to your code is one you can log.

6. Observe the session instead of reading your stored state: collect client.sessionState.

7. Sign out with client.logout(). It returns LogoutOutcome(sessionEnded, tokenRevoked).

8. Delete the old AuthState storage (see What happens to existing users and tokens?).

How do I migrate from AppAuth-iOS?

Before (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
}

After (Versola OAuth SDK)

1. Dependency. Remove AppAuth from your package or Xcode project. Add the SDK’s public repository and the VersolaOAuth product, then import OAuthClient. The package needs 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 for an https redirect: Associated Domains for the host, and the apple-app-site-association file, as described on the iOS page. A private-use scheme needs none of that and logs a warning.

3. Create the client (async, once). The presentationAnchor is a closure that returns the window the browser sheet is presented from:

   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. Sign in. Delete currentAuthorizationFlow and the application(_:open:options:) plumbing:

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

   Keep one handler, only for Universal Links that arrive while the app is cold:

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

5. Call your API with the authenticated session instead of performAction:

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

   Or call try await client.accessToken() where you need the value.

6. Observe with for await state in await client.sessionStates() { ... }.

7. Sign out with await client.logout(), which returns a LogoutOutcome.

8. Delete the archived OIDAuthState (see What happens to existing users and tokens?).

How do I migrate from flutter_appauth?

Before (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>',
));

After (versola_oauth)

1. Dependency. Replace flutter_appauth in pubspec.yaml with versola_oauth. The Flutter page covers the install. Remove the plugin’s own setup: appAuthRedirectScheme on Android and the CFBundleURLTypes custom scheme on iOS, unless you keep a custom-scheme redirect.

2. Native setup in the host app. Android: the VersolaRedirectActivity intent filter. iOS: iOS 17.4 or newer, Associated Domains for an https redirect, and VersolaOAuthPlugin.presentationAnchor if the app has its own window handling. See the Flutter page.

3. Create and use:

   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. Remove your token storage. Nothing credential-shaped is kept in Dart, so delete the code that stores and refreshes tokens. accessToken() refreshes natively.

5. Sign out with client.logout(). It returns a LogoutOutcome.

6. Errors. FlutterAppAuthUserCancelledException becomes RecoverableError, and the platform exception becomes the matching category.

Dart has no authenticated HTTP client. Call your API with the value accessToken() returns, and call it again for each request or batch rather than caching it.

Migration checklist

• The provider client is public and has PKCE S256; no secret is used anywhere.
• The configured issuer equals the discovery document’s issuer member.
• offline_access is in scopes if the provider needs it for a refresh token (see Providers).
• The redirect URI is registered with the provider exactly as configured, and for https the app’s assetlinks.json or apple-app-site-association file is served.
• postLogoutRedirectUri is registered with the provider.
• No code reads, writes or sends a refresh token or a raw ID token.
• The old AuthState (or archived OIDAuthState, or Dart token storage) is deleted after the first successful login().
• Your sign-in screen handles the four error categories, and a Configuration error is not caught silently in production.

Sources

The AppAuth facts on this page were read on 2026-10-30. The SDK side comes from the SDK’s own API specification and public declarations.

• AppAuth-Android README: https://github.com/openid/AppAuth-Android. Used for configuration and discovery, the request and intents, the redirect (appAuthRedirectScheme, RedirectUriReceiverActivity), AuthState persistence and performActionWithFreshTokens, EndSessionRequest, client secrets and dynamic registration, browser allow and deny lists, the WebView statement, PKCE, the API levels, setNonce(null) and setSkipIssuerHttpsCheck.
• AppAuth-Android IdToken.java, for the ID-token checks and the statement that the signature is not verified.
• AppAuth-iOS README: https://github.com/openid/AppAuth-iOS and https://raw.githubusercontent.com/openid/AppAuth-iOS/master/README.md. Used for discovery, OIDAuthorizationRequest, OIDAuthState.authState(byPresenting:presenting:), resumeExternalUserAgentFlow, performAction, user agents, WebView, PKCE, HTTPS redirects and the webcredentials requirement, and OS floors.
• AppAuth-iOS API index, for the class list (end session, registration, token request classes): https://openid.github.io/AppAuth-iOS/docs/latest/annotated.html, and for OIDIDToken: https://openid.github.io/AppAuth-iOS/docs/latest/interface_o_i_d_i_d_token.html.
• flutter_appauth README: https://github.com/MaikuB/flutter_appauth and https://raw.githubusercontent.com/MaikuB/flutter_appauth/master/flutter_appauth/README.md.

Next steps

• Android, iOS and Flutter: set up the SDK on each platform.
• Session states and errors: the four error categories and the seven session states your sign-in screen handles.
• Server errors, 429 and Retry-After: what the SDK retries and what your app does with the rest.
• Providers: redirect URIs, scopes and sign-out for your provider, such as Keycloak.