Skip to content

v3: use a system web auth session for OAuth/SSO/linkIdentity instead of url_launcher #1402

Description

@spydon

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    plannedThis issue is planned and should not be automatically closed due to being stale.v3

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions