Onboarding WebView blocks third-party credential providers (Passkey/WebAuthn) — propose ASWebAuthenticationSession

[chasperli]

Problem

The iOS Companion App's onboarding/auth WebView (OnboardingAuthLoginViewControllerImpl in Sources/App/Onboarding/API/OnboardingAuthLoginViewController.swift) is a plain WKWebView() with default configuration. This means:

• iOS system Passkey/WebAuthn AutoFill does not reach into the WebView
• Third-party credential providers (KeePassium, 1Password, Bitwarden) cannot serve credentials to the auth flow
• iCloud Keychain passkeys are not surfaced because the app has no Associated Domain for the user's self-hosted instance

Result: users with WebAuthn-only setups (which is the recommended Authentik posture) can't log in via the App and must fall back to TOTP.

This is the same root cause as the closed issues #3139 ("Companion app login Authentication fails" — closed not planned, Nov 2024) and #3753 ("Pangolin secure key login not working" — closed completed without fix, Jul 2025).

Context — why this matters now

OIDC adoption for HA via the christiaangoossens/hass-oidc-auth HACS integration is growing. The server side just gained mobile-app support (PR christiaangoossens/hass-oidc-auth#317, draft, planned for v1.2.0) — the integration now correctly issues the homeassistant://auth-callback redirect for clients identified as the iOS App. That confirms the server side works against WKWebView's decidePolicyFor-based deep-link interception.

But the auth UI rendering inside WKWebView remains the blocker for WebAuthn / Passkey users, regardless of which OIDC provider sits behind HA.

Proposed solution

Switch OnboardingAuthLoginViewControllerImpl from WKWebView to ASWebAuthenticationSession for the OAuth flow. Apple explicitly recommends ASWebAuthenticationSession for OAuth/OIDC (WWDC 2018 "Introducing Password AutoFill") — it shares the Safari cookie store, surfaces iOS Passkey/Autofill natively, and handles the custom-scheme callback (homeassistant://auth-callback) via its built-in completion handler.

The historical reason for the prior switch to WKWebView (issue #233, 2021) was Apple's HTTP-callback deprecation. That doesn't affect HA's flow today because the callback is always homeassistant:// (custom scheme).

Compatibility concerns and proposed hybrid

Two real limitations of ASWebAuthenticationSession that affect self-hosted setups:

1. Self-signed certificates: ASWebAuthenticationSession has no URLAuthenticationChallenge delegate. The current WKNavigationDelegate.webView(_:didReceive:completionHandler:) (lines ~94-108) handles self-signed CAs via SecurityExceptions.
2. mTLS / Client certificates: PR Allow supplying client certificates #2144 showed client-cert auth requires WKWebView.

Proposed hybrid: route through ASWebAuthenticationSession by default, fall back to the existing WKWebView controller when SecurityExceptions.hasExceptions is truthy or a ClientCertificate is configured. The default path solves WebAuthn for the 80% case (publicly-trusted certs, no mTLS); the fallback preserves the self-hosted edge cases that motivated the original switch.

Promise signature stays Promise<URL>.

Where to patch

based on authDetails.exceptions and authDetails.clientCertificate

• Sources/App/Onboarding/API/OnboardingAuthDetails.swift — already provides scheme for callbackURLScheme:

• Tests under Tests/App/Onboarding/ — add coverage for both branches

  What I can offer

I'm a user, not an iOS developer — I can test on iOS 26 with self-hosted HA + Authentik, file a follow-up issue with logs if needed, but I'm not in a position to submit the PR myself. If a maintainer or community contributor picks this up, I'll happily verify against my setup.

[bgoncal]

The app is not designed to support third party authentication methods neither is planned to start supporting, you can read more here:

#3575

[jsamuel1]

I don't believe the linked issue relates directly here.

This ticket is about not blocking external authentication at connection time.

The other ticket is about supporting external authentication (this ticket doesn't ask for support/endorsement - just to not explicitly prevent)