Expose WebView navigation interception (with URL + cancel) and cookie access API in v3

[wsczx]

Wails version family

v3

Operating System

Windows

Description

In Wails v3 (v3.0.0-alpha2.117), the WebView is the only way to render a third-party login / SAML / SSO page inside the app. A common auth flow is: open an external auth URL in the WebView → the provider finishes login and redirects to a callback URL that carries a token (e.g. .../callback?token=... or http://localhost:PORT/callback?token=...) → the app must capture that token and close the WebView.

Currently there is no supported way to capture a token delivered via a redirect URL or a cookie from inside the WebView. This blocks two real scenarios:

• Mobile (iOS/Android): the app sandbox forbids binding a localhost port, so a localhost callback listener is impossible. The token must be captured from within the WebView.
• Desktop: without navigation/cookie access, the only fallback is running a localhost listener, which we want to avoid.

To Reproduce

1. Create a Wails v3 app with a WebView.
2. Load an external URL that, after some interaction, redirects to a custom callback URL containing a token (e.g. myapp://callback?token=abc).
3. Try to detect that navigation from Go/TS to extract the token and stop the navigation.
4. Observe that no public API provides the target URL during navigation, and the only navigation event (WebViewNavigationCompleted) does not include the URL.
5. Alternatively, try to read the WebView's cookies after auth completes — no public cookie API exists.

Expected behaviour

• A navigation hook that exposes the target URL and allows cancelling the navigation, e.g.

webview.OnNavigationStarting(func(url string) bool {
    if strings.HasPrefix(url, "myapp://callback") {
        token := extract(url)
        return false // cancel
    }
    return true
})

• A cookie access API, e.g. webview.GetCookies() / webview.SetCookie(...).

Screenshots

No response

Attempted Fixes

• Used the internal navigationStarting handler — it exists but is not exposed to Go/TS with the URL and cannot cancel navigation.
• Used the public WebViewNavigationCompleted event — it fires but does not include the URL.
• Worked around it on desktop by running a localhost callback listener to catch the redirect — works on desktop but is impossible on mobile (sandbox forbids port binding).

System Details

- Wails v3: v3.0.0-alpha2.117
- Go: (fill your version, e.g. go1.22.x)
- OS / Platform: macOS / Windows / Linux (desktop) + iOS / Android (mobile)
- Frontend: (e.g. vanilla JS / React / etc.)

Additional context

This is required for SSO / SAML / OAuth flows where the token is delivered via a post-login redirect or a session cookie. On mobile especially, a localhost listener is not an option, so in-WebView capture (navigation interception or cookie read) is the only viable path. A minimal, unified API across desktop and mobile would let the same auth code run everywhere.

[mortenolsrud]

Hey, we ran into this exact problem in our Wails v3 app (OIDC PKCE auth on desktop + iOS + Android). Here's what worked for us:

Short version: skip the WebView for auth entirely. Use the system browser + platform-specific callback capture.

Why system browser instead of WebView

RFC 8252 (OAuth 2.0 for Native Apps) recommends the system browser. It gives users SSO (shared cookies/sessions), and some IdPs like Google and Microsoft actively block WebView-based auth. No navigation interception or cookie APIs needed.

How we did it

Desktop (Windows/macOS/Linux):

• Open the auth URL in the system browser via platform.OpenBrowser(authURL)
• Start a temporary localhost HTTP server listening for the callback
• IdP redirects to http://localhost:PORT/callback?code=...
• Extract the code, exchange for tokens, kill the server

This is what you already have as your desktop workaround. It's actually the "correct" approach, not a hack.

Mobile (iOS/Android):

• Localhost doesn't work in the sandbox, as you noted
• Instead: claimed HTTPS redirects via Universal Links (iOS) / App Links (Android)
• You register your app to handle a specific HTTPS URL (like https://yourapp.example.com/auth/callback)
• The IdP redirects there, and the OS routes it to your app instead of the browser
• Your Go code receives the callback URL through a channel

What you need to set up:

• iOS: Associated Domains entitlement + apple-app-site-association JSON file hosted on the domain
• Android: intent-filter with android:autoVerify="true" in AndroidManifest.xml + assetlinks.json hosted on the domain
• A Platform interface that abstracts the flow so desktop uses localhost and mobile uses deep links

The architecture pattern

We added StartAuthFlow(authURL, redirectURI string) <-chan AuthResult to our Platform interface:

• Desktop impl: starts localhost server, opens browser, returns channel
• Android impl: opens browser, listens for the deep link intent, returns channel
• iOS impl: same thing with Universal Links

Auth.Login() doesn't know which transport is used. It just awaits the channel.

One gotcha: redirect URI constraints

Your IdP needs to support whatever redirect URI scheme you pick:

• Desktop: http://localhost:PORT/callback (most IdPs whitelist this for native apps)
• Mobile: https://yourdomain.com/auth/callback (a real HTTPS URL you control)
• Custom schemes like myapp://callback are NOT supported by many IdPs and are deprecated by RFC 8252

Summary

Platform	Auth UI	Callback Transport
Desktop	System browser	Localhost HTTP server
iOS	System browser	Universal Links
Android	System browser	App Links (verified HTTPS intent-filter)

So you don't actually need Wails to add WebView navigation hooks for auth. The system browser approach is more secure, gives better UX (SSO), and works today with no framework changes.

That said, a navigation hook API would be useful for other things (embedded payment flows, content gating, etc.), just not the best fit for auth.