skip to content

In AuthenticationServices on iOS 17.4 and later, how does ASWebAuthenticationSession.Callback let a web sign-in finish on an https URL, and what must be set up?

level: middleimportance: should knowfreq 40%

answer

  1. more than a scheme to match
  2. customScheme(_:) versus https(host:path:)
  3. the host must be associated
  4. webcredentials entry and AASA file
  5. #available(iOS 17.4, *) fallback

basics

~10 s

From iOS 17.4, init(url:callback:completionHandler:) takes an ASWebAuthenticationSession.Callback; .https(host:path:) ends the session when the page navigates to that host and path, and the host must be associated with the app through a webcredentials associated domain.

solid answer

~40 s

Before iOS 17.4 the only way to end a web sign-in was a custom scheme passed as `callbackURLScheme`. iOS 17.4 added `init(url:callback:completionHandler:)` and `ASWebAuthenticationSession.Callback`, with two factories: `.customScheme(_:)` and `.https(host:path:)`. With the https form, when the session's browser navigates to a URL with that host and path, the session closes and passes the URL to the completion handler, so the studio can register an ordinary `https` redirect such as `https://studio.example.com/oauth/ios-callback`. The header requires the host to be associated with the app through associated web credentials domains: a `webcredentials:studio.example.com` entry in the Associated Domains entitlement and an `apple-app-site-association` file listing the app under `webcredentials`. An app that still deploys to iOS 17.0 wraps the new initializer in `#available(iOS 17.4, *)` and keeps the scheme initializer, which the SDK marks to be deprecated, for older devices.

code

swift · 24 lines
swift
import AuthenticationServices
import UIKit

@available(iOS 17.4, *)
@MainActor
func makePortalSession(
    authorizeURL: URL,
    anchor: any ASWebAuthenticationPresentationContextProviding,
    onCode: @escaping (String) -> Void
) -> ASWebAuthenticationSession {
    // studio.example.com must also appear as webcredentials:studio.example.com
    let callback = ASWebAuthenticationSession.Callback.https(
        host: "studio.example.com", path: "/oauth/ios-callback")
    let session = ASWebAuthenticationSession(url: authorizeURL, callback: callback) { url, error in
        guard error == nil, let url,
              let code = URLComponents(url: url, resolvingAgainstBaseURL: false)?
                .queryItems?.first(where: { $0.name == "code" })?.value
        else { return }
        onCode(code)
    }
    session.presentationContextProvider = anchor
    session.additionalHeaderFields = ["X-Studio-Client": "ios"]  // names must start with X-
    return session
}

go deeper

for a junior

Recall the two Callback factories, customScheme(_:) and https(host:path:), and that the Callback initializer needs iOS 17.4.

for a middle

Explain how the session decides a navigation is the callback, why the https host needs a webcredentials association, and how to branch with #available.

for a senior

Plan the migration: register both redirect URIs, keep the scheme path for older devices, and verify the association file reaches Apple's CDN before release.

for a principal

Decide when the deployment target and the identity provider allow dropping the custom scheme, and who owns the association file the sign-in now depends on.

## Two ways to say where sign-in ends An `ASWebAuthenticationSession` needs to know which URL means "sign-in is over". The browser keeps navigating until it reaches that URL; then the session dismisses the browser view and hands the URL to the completion handler. | Initializer | Available | How the end URL is described | |---|---|---| | `init(url:callbackURLScheme:completionHandler:)` | iOS 12 | a custom scheme string, such as `yogastudio` | | `init(url:callback:completionHandler:)` | **iOS 17.4** | an `ASWebAuthenticationSession.Callback` object | In the iOS 27.1 SDK the scheme initializer carries a deprecation marking of the to-be-deprecated kind, with the message to use the callback initializer instead. It is superseded, not removed, and it still builds without a deprecation warning. ## The Callback type `ASWebAuthenticationSession.Callback` (iOS 17.4) is a small object that evaluates navigations. It has two factory methods: - **`.customScheme(_:)`** matches URLs with the given custom scheme, which is the old behaviour in the new shape. - **`.https(host:path:)`** matches `https` URLs with the given host and path. Apple's description is that when the session navigates to a matching URL, it passes that URL to the completion handler. The object also has **`matchesURL(_:)`**, which checks whether a main-frame navigation URL matches. It exists mainly for browsers that implement web authentication sessions, but it is handy in a unit test or while debugging a redirect that never completes. Why bother with https? An identity provider may allow only https redirect URIs for a client, and an https URL on the studio's own domain is something the studio controls. The protocol reasoning about claimed https redirects belongs with the OAuth redirect material; on iOS the practical point is that the session can now end on such a URL. ## The association the https form needs The header for `https(host:path:)` says the host **must be associated with the app using associated web credentials domains**. That is the same association passkeys and shared passwords use: 1. Add the **Associated Domains** capability and list `webcredentials:studio.example.com`. The format is `<service>:<fully qualified domain>`, with no path, query or trailing slash. 2. Serve `https://studio.example.com/.well-known/apple-app-site-association` over https with a valid certificate and no redirects, with a `webcredentials` section whose `apps` array holds `<Team ID>.<bundle ID>`. 3. Remember the delivery path: since iOS 14 devices fetch the file from Apple's content delivery network, which requests it within 24 hours, and devices check for updates about once a week after installation. An `applinks` entry for universal links is a different service and does not satisfy this requirement. When an https callback never completes, check the `webcredentials` entry and the file before anything else. ## Supporting older releases Most apps still deploy to iOS 17.0 or 18, so the call site branches: - `if #available(iOS 17.4, *)` builds a `Callback`, either `.https(host:path:)` or `.customScheme(_:)`. - The `else` branch uses `init(url:callbackURLScheme:completionHandler:)`, which cannot express an https callback. Devices below 17.4 therefore need a custom-scheme redirect registered with the provider as well. - Keep both redirect URIs registered with the identity provider until the deployment target reaches 17.4. ## Debugging a callback that never fires When the portal shows its success page and the sheet stays open, the session has not seen a matching navigation. Work through it in order: 1. Compare the redirect URI registered with the provider with the host and path given to `https(host:path:)`, character for character, including the leading slash of the path. 2. Pass the URL the portal actually redirects to into `matchesURL(_:)` in a test to see whether the callback object accepts it. 3. Confirm the redirect really is an `https` URL on that host, not an intermediate page that redirects again with a different path. 4. Check the `webcredentials` entitlement entry and the association file, and allow for the delay before Apple's CDN has the current file. ## Other 17.4 additions worth knowing - **`additionalHeaderFields`** (iOS 17.4) sets extra headers on the request that loads the initial URL; every header name must start with `X-`. - The SwiftUI environment value `webAuthenticationSession` has `authenticate(using:callback:preferredBrowserSession:additionalHeaderFields:)`, which takes the same `Callback` and returns the callback URL from an `async` call. - Everything else, including `prefersEphemeralWebBrowserSession`, `presentationContextProvider`, `start()` and `cancel()`, works the same whichever initializer created the session.

  • What does the SDK say about init(url:callbackURLScheme:completionHandler:) today?
    Its header marks it with a to-be-deprecated availability and the message to use `init(url:callback:completionHandler:)` instead. It still builds without a warning, and an app deploying below iOS 17.4 needs it for those devices.
  • Your app already has an applinks entry for studio.example.com. Is that enough for the https callback?
    No. The https callback requires the host to be associated through web credentials, so the entitlement needs `webcredentials:studio.example.com` and the site's association file needs a `webcredentials` section listing the app. Universal links are a separate service.
  • What is additionalHeaderFields for, and what rule does it impose?
    Added in iOS 17.4, it sets extra header fields on the request that loads the initial URL, such as a client marker the portal reads. Every header name must start with the `X-` prefix.

  • The https callback works on iOS 17.0 as long as the Info.plist lists the domain.
  • An applinks entry for the host is enough for an https callback.
  • callbackURLScheme accepts "https" to get the same behaviour as Callback.https(host:path:).
  • The callbackURLScheme initializer is already deprecated and produces a warning in the iOS 27.1 SDK.
  • The Callback object needs the authorization server to know the app's bundle ID.

Assumes the iOS 27.1 SDK; ASWebAuthenticationSession.Callback and init(url:callback:completionHandler:) are iOS 17.4, and the callbackURLScheme initializer is marked to be deprecated.