Document WebAuthentication

Sources/SafariUI/SafariUI.docc/SafariUI.md

@@ -4,7 +4,7 @@ SafariServices in SwiftUI
 
 ## Overview
 
-`SafariUI` is a package that wraps [`SafariServices`](https://developer.apple.com/documentation/safariservices/) for use with SwiftUI applications. Currently, it contains a single SwiftUI view, called `SafariView`, which wraps [`SFSafariViewController`](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller).
+`SafariUI` is a package that allows you to display instances of Safari inside your SwiftUI applications. Use ``WebAuthentication`` when using Safari to authenticate users, and ``SafariView`` for a standard Safari experience.
 
 ## Topics
 

Sources/SafariUI/SafariUI.docc/SafariView.md

@@ -6,7 +6,7 @@
 
 ## Overview
 
-The view includes Safari features such as Reader, AutoFill, Fraudulent Website Detection, and content blocking. The user's activity and interaction with `SafariView` are not visible to your app, which cannot access AutoFill data, browsing history, or website data. You do not need to secure data between your app and Safari. If you would like to share data between your app and Safari, so it is easier for a user to log in only one time, use [`ASWebAuthenticationSession`](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession) instead.
+The view includes Safari features such as Reader, AutoFill, Fraudulent Website Detection, and content blocking. The user's activity and interaction with `SafariView` are not visible to your app, which cannot access AutoFill data, browsing history, or website data. You do not need to secure data between your app and Safari. If you would like to share data between your app and Safari, so it is easier for a user to log in only one time, use ``WebAuthentication`` instead.
 
 - Important: In accordance with [App Store Review Guidelines](https://developer.apple.com/app-store/review/guidelines/), this view must be used to visibly present information to users; the view may not be hidden or obscured by other views or layers. Additionally, an app may not use `SafariView` to track users without their knowledge and consent.
 

Sources/SafariUI/SafariUI.docc/WebAuthentication.md

@@ -0,0 +1,17 @@
+#  ``WebAuthentication``
+
+@Metadata {
+    @DocumentationExtension(mergeBehavior: append)
+}
+
+## Overview
+
+Use a `WebAuthentication` instance to authenticate a user through a web service, including one run by a third party. Initialize the session with a URL that points to the authentication webpage. When the user starts the authentication session, the operating system shows a modal view telling them which domain the app is authenticating with and asking whether to proceed. If the user proceeds with the authentication attempt, a browser loads and displays the page, from which the user can authenticate. In iOS, the browser is a secure, embedded web view. In macOS, the system opens the user’s default browser if it supports web authentication sessions, or Safari otherwise.
+
+On completion, the service sends a callback URL to the session with an authentication token. The session passes this URL back to the app through a completion handler. `AuthenticationSession` ensures that only the calling app’s session receives the authentication callback, even when more than one app registers the same callback URL scheme.
+
+`WebAuthentication` is not a normal SwiftUI view. Unlike ``SafariView``, **must** be presented using one of the following included view modifiers:
+
+- ``SwiftUI/View/webAuthentication(_:webAuthentication:)-74m38``
+- ``SwiftUI/View/webAuthentication(_:webAuthentication:)-5x82p``
+- ``SwiftUI/View/webAuthentication(_:id:webAuthentication:)``