Summary
Move signInWithOAuth, signInWithSSO and linkIdentity off url_launcher and onto a native system web authentication session (ASWebAuthenticationSession on iOS and macOS, Custom Tabs on Android) via flutter_web_auth_2. On web the current tab is redirected as today.
Motivation
Today the OAuth screen is opened with url_launcher's in-app browser. That surface does not close itself when the OAuth redirect returns to the app, so after a successful sign in the user is left on a blank in-app browser and has to dismiss it manually (#1174, also reported for Keycloak). It also cannot hand the callback back to the caller, so signInWithOAuth resolves at launch time rather than at completion.
A system web authentication session is the right primitive for this: the OS owns it, it captures the redirect to the registered callback scheme, closes itself, and returns the callback URL directly. That fixes the dismissal bug on every platform and lets the call resolve once the session is established. It also shares cookies with the system browser for single sign on, with preferEphemeral available to opt out.
Scope
- Add
flutter_web_auth_2, drop url_launcher as a direct dependency (it remains transitively via flutter_web_auth_2).
- Route
signInWithOAuth, signInWithSSO and linkIdentity through FlutterWebAuth2.authenticate on native and desktop; full page redirect on web.
- Remove the
authScreenLaunchMode / launchMode parameters and the LaunchMode export; add a preferEphemeral option.
- Derive the callback scheme from
redirectTo; forward host and path for https universal links.
Breaking changes
authScreenLaunchMode / launchMode parameters removed; LaunchMode no longer exported.
- Android apps must register the
flutter_web_auth_2 CallbackActivity for their redirect scheme in AndroidManifest.xml.
- The OAuth callback no longer flows through the
app_links deep link handler. Magic links, email confirmation and password recovery still use deep links.
Open questions
- Keep a way to force the external browser on iOS and Android, or rely on
ASWebAuthenticationSession cookie sharing plus preferEphemeral?
- Web: keep the full page redirect (current behavior, parity with
supabase-js) or adopt flutter_web_auth_2's popup model? The PR keeps the redirect.
- Confirm the hardcoded Google on Android external browser workaround can be dropped now that Custom Tabs are used.
- Desktop callback model (localhost server / webview) needs on device verification.
Implementation
Draft PR targeting the v3 branch: will link below. Fixes #1174.
Summary
Move
signInWithOAuth,signInWithSSOandlinkIdentityoffurl_launcherand onto a native system web authentication session (ASWebAuthenticationSessionon iOS and macOS, Custom Tabs on Android) viaflutter_web_auth_2. On web the current tab is redirected as today.Motivation
Today the OAuth screen is opened with
url_launcher's in-app browser. That surface does not close itself when the OAuth redirect returns to the app, so after a successful sign in the user is left on a blank in-app browser and has to dismiss it manually (#1174, also reported for Keycloak). It also cannot hand the callback back to the caller, sosignInWithOAuthresolves at launch time rather than at completion.A system web authentication session is the right primitive for this: the OS owns it, it captures the redirect to the registered callback scheme, closes itself, and returns the callback URL directly. That fixes the dismissal bug on every platform and lets the call resolve once the session is established. It also shares cookies with the system browser for single sign on, with
preferEphemeralavailable to opt out.Scope
flutter_web_auth_2, dropurl_launcheras a direct dependency (it remains transitively viaflutter_web_auth_2).signInWithOAuth,signInWithSSOandlinkIdentitythroughFlutterWebAuth2.authenticateon native and desktop; full page redirect on web.authScreenLaunchMode/launchModeparameters and theLaunchModeexport; add apreferEphemeraloption.redirectTo; forward host and path forhttpsuniversal links.Breaking changes
authScreenLaunchMode/launchModeparameters removed;LaunchModeno longer exported.flutter_web_auth_2CallbackActivityfor their redirect scheme inAndroidManifest.xml.app_linksdeep link handler. Magic links, email confirmation and password recovery still use deep links.Open questions
ASWebAuthenticationSessioncookie sharing pluspreferEphemeral?supabase-js) or adoptflutter_web_auth_2's popup model? The PR keeps the redirect.Implementation
Draft PR targeting the
v3branch: will link below. Fixes #1174.