An iOS app using ASWebAuthenticationSession redirects to an Apple Universal Link upon successful login. However, the session does not automatically dismiss the secure browser modal when the Universal Link is triggered. This knowledge article explains the potential causes and suggests solutions.

• iOS 17.4+ / macOS 14.4+
• Auth0 Swift SDK (Auth0.swift)
• Apple Universal Links
• ASWebAuthenticationSession

Apple introduced support for using HTTPS Universal Links as callback and logout URLs within ASWebAuthenticationSession starting in iOS 17.4 and macOS 14.4. Prior to these versions, completing the authentication flow required Custom URL Schemes. Due to this architectural change, specific Xcode entitlements, AASA (Apple App Site Association) file entries, and SDK flags instruct the operating system to natively intercept the HTTPS redirect and complete the ASWebAuthenticationSession.

Follow the steps below to resolve the behavior:

1. Ensure Backward Compatibility for Pre-iOS 17.4.
   • For applications that must support iOS versions earlier than 17.4, the app will fall back to the older Custom URL Scheme approach. The Auth0 Swift SDK handles this fallback automatically, but the Auth0 application configuration must have both callback types registered in the Allowed Callback URLs (and Allowed Logout URLs) on the Auth0 dashboard.
   • For Example:

     # Custom Scheme (fallback for iOS < 17.4)
     com.company.app://LOGIN_DOMAIN/ios/com.company.app/callback
     
     # Universal Link (iOS 17.4+)
     https://LOGIN_DOMAIN/ios/com.company.app/callback

2. Configure the AASA File and Xcode Associated Domains.
   • For ASWebAuthenticationSession to intercept the HTTPS callback on iOS 17.4+, both of the following must be in place:
     1. The AASA (Apple App Site Association) file hosted at the login domain must declare the webcredentials service, in addition to applinks:

        {
          "applinks": {
            "details": [
              {
                "appIDs": ["TEAMID.com.company.app"],
                "components": [
                  { "/": "/ios/com.company.app/callback" }
                ]
              }
            ]
          },
          "webcredentials": {
            "apps": ["TEAMID.com.company.app"]
          }
        }

1. 1. 2.  In the Xcode project, go to Signing & Capabilities > Associated Domains, and add entries for the login domain:

         applinks:LOGIN_DOMAIN
         webcredentials:LOGIN_DOMAIN

• • Apple's ASWebAuthenticationSession.Callback.https API uses the webcredentials service (not applinks) to verify the association between the app and the callback domain. Without it, iOS will not route the HTTPS callback back into the active authentication session.

3. Enable HTTPS Callback in the Auth0 Swift SDK.
   • By default, the Auth0 Swift SDK configures ASWebAuthenticationSession to listen for the Custom URL Scheme. To instruct the SDK to use the new iOS 17.4+ HTTPS callback feature, append the .useHTTPS() modifier to the WebAuth call.

     import Auth0
     
     Auth0
         .webAuth()
         .useHTTPS() // <-- Required for Universal Link callback on iOS 17.4+
         .start { result in
             switch result {
             case .success(let credentials):
                 print("Successfully logged in: \(credentials.accessToken)")
             case .failure(let error):
                 print("Failed with: \(error)")
             }
         }

Verification Checklist

Before concluding that the setup is broken, verify the following:

• iOS device/simulator is running iOS 17.4 or later.
• The AASA file is served over HTTPS at https://LOGIN_DOMAIN/.well-known/apple-app-site-association with Content-Type: application/json and no redirects.
• The AASA file includes both applinks and webcredentials entries with the correct TEAMID.bundleID format.
• Xcode Associated Domains entitlement includes both applinks: and webcredentials: entries for the login domain.
• The Auth0 Dashboard has the HTTPS callback URL registered in Allowed Callback URLs (and Logout URLs if applicable).
• .useHTTPS() has been added to the Auth0.webAuth() call.
• The app has been reinstalled after entitlement changes (iOS caches AASA associations at install time).