[iOS] Universal links do not return the user to the app when you set the redirect URI to it

[Marc-Antoine-Soucy]

Checklist

• I have looked into the Readme and the documentation, and have not found a suitable solution or answer.
• I have looked into the API documentation and have not found a suitable solution or answer.
• I have searched the issues and have not found a suitable solution or answer.
• I have searched the Auth0 Community forums and have not found a suitable solution or answer.
• I agree to the terms within the Auth0 Code of Conduct.

Description

Following a client request informing us that auth0 is encouraging people to switch from custom schemes to https based callbacks, I tried to switch the app from custom schemes to app links and universal links. On android, it worked.

On iOS, I have an issue where the browser, instead of navigating to the app, it navigates to the website inside of the web authentication browser after you finish authenticating.

I have verified that the universal link works from the "note" app, and I left some logs for when this happens. These logs are not present when I finish authenticating with auth0.

Reproduction

Have a functioning app that uses auth0 for authentication, add associated domains capabilities, override ContinueUserActivity, change the redirect URI's to the universal link Uri with:

auth0ClientOptions.RedirectUri = redirectUri;
auth0ClientOptions.PostLogoutRedirectUri = redirectUri;

Additional context

I can see that in the documentation for .net iOS/android, there are only the instructions for using custom schemes. I'm not entirely sure if this should have been opened as a feature request.

Is this something not supported right now, and is there a plan to support it in the future?

auth0-oidc-client-net version

4.4.0

.NET version

9

Platform

iOS

Platform version(s)

The phone is: ios 26.3

[swlasse]

I can confirm the same issue is happening for me on .NET MAUI. The authentication session window is not dismissed on login or logout when using HTTPS universal link callbacks on iOS. Environment: .NET 10, Auth0.OidcClient.MAUI 1.4.0, iPadOS 26.5.

[swlasse]

First, thanks for raising this issue! I've done some more digging on this, and as far as I can tell, the root cause seems to be in MAUI's WebAuthenticator which is used by the Auth0 SDK here.

MAUI's WebAuthenticator on iOS uses ASWebAuthenticationSessionCallback.Create(scheme) when setting up the authentication session, and when using a HTTPS callback URL it passes "https" as the scheme (as far as I can tell). Now, according to Apple's documentation, the single-parameter customScheme(_:) overload is intended for custom URL schemes, whereas the two-parameter https(host:path:) overload is designed for HTTPS callbacks. This explains why the auth session doesn't recognize the HTTPS callback URL and hence doesn't dismiss the browser.

Proposed fix in the MAUI source: Use ASWebAuthenticationSessionCallback.Create(host, path) when the scheme of the callback URL is HTTPS:

var callback = scheme == "https"
    ? ASWebAuthenticationSessionCallback.Create(callbackUrl.Host, callbackUrl.AbsolutePath)
    : ASWebAuthenticationSessionCallback.Create(scheme);

I'll create an issue with the MAUI team for this so we can discuss further.

Lessons learned when using claimed HTTPS URLs for auth callbacks (documentation on this is sparse):

• webcredentials:yourdomain.com must be added to the Associated Domains entitlement. As far as I can tell, applinks: is only needed if you separately use universal links / deep links. For the HTTPS auth callback itself, only webcredentials: is required. See "hints" on this here and here.
• The apple-app-site-association file must include a matching webcredentials section (for iOS to verify the domain can be used as auth callback for a given app).
• Use iOS 17.4 as the minimum deployment target (the ASWebAuthenticationSession.Callback API was introduced in iOS 17.4).

To verify the approach, I've built a custom IBrowser implementation that bypasses MAUI's WebAuthenticator on iOS and calls the ASWebAuthenticationSessionCallback.Create(host, path) overload directly. I then passed that to the Auth0Client via the Auth0ClientOptions.Browser property and tested the whole thing with success on iPadOS 26.5 using .NET 10 and Auth0.OidcClient.MAUI version 1.4.0.

This is of course just a workaround - I'll focus on driving a dialog with the MAUI team to investigate further and hopefully get a proper fix upstream (assuming my investigation is sound).