Document the HTTPS callbacks feature [SDK-4751] (#833)

Documentation.docc/WebAuth/UserAgents.md

@@ -8,6 +8,8 @@ Web-based authentication needs an in-app browser. Auth0.swift offers the choice
 
 `ASWebAuthenticationSession` is an API provided specifically for performing web-based authentication. It is not meant for general-purpose browsing, and exposes a pretty limited API. `ASWebAuthenticationSession` can be used with or without ephemeral sessions enabled –through the [`prefersEphemeralWebBrowserSession`](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession/3237231-prefersephemeralwebbrowsersessio) option.
 
+> Note: `ASWebAuthenticationSession` supports using Universal Links as callback and logout URLs on iOS 174+ and macOS 14.4+.
+
 ### Without ephemeral sessions (the default)
 
 ```swift
@@ -21,7 +23,7 @@ Auth0
 By default, Auth0.swift uses `ASWebAuthenticationSession` with `prefersEphemeralWebBrowserSession` set to `false`. This means that:
 
 - The session cookie will be shared with the Safari app.
-- An alert box will be shown when logging in –and logging out– asking for consent, as the session cookie will be placed in a shared jar. This alert box is displayed and managed by `ASWebAuthenticationSession`, not Auth0.swift, and unfortunately it's not customizable.
+- An alert box will be shown when logging in –and logging out– asking for consent, as the session cookie will be placed in a shared jar. This alert box is displayed and managed by `ASWebAuthenticationSession`, not Auth0.swift, and unfortunately it is not customizable.
 
 #### You want this if...
 
@@ -70,6 +72,8 @@ Auth0
 - No consent alert box will be shown, as the session cookie won't be placed in a shared cookie jar.
 - All the features that rely on the persistence of cookies –like "Remember this device"– **will work** as expected.
 
+> Note: `SFSafariViewController` does not support using Universal Links as callback URLs.
+
 #### You want this if...
 
 - **You need SSO between your app and your website**, when your website is accessed through another `SFSafariViewController` instance in your app.

EXAMPLES.md

@@ -683,7 +683,7 @@ Auth0
 
 ### Renew credentials
 
-Use a [refresh token](https://auth0.com/docs/secure/tokens/refresh-tokens) to renew the user's credentials. It's recommended that you read and understand the refresh token process beforehand.
+Use a [refresh token](https://auth0.com/docs/secure/tokens/refresh-tokens) to renew the user's credentials. It is recommended that you read and understand the refresh token process beforehand.
 
 ```swift
 Auth0
@@ -1035,7 +1035,7 @@ Auth0
 > [!CAUTION]
 > Set this flag only when **DEBUGGING** to avoid leaking user's credentials in the device log.
 
-With a successful authentication you'll see something similar to the following:
+With a successful authentication you should see something similar to the following:
 
 ```text
 ASWebAuthenticationSession: https://example.us.auth0.com/authorize?.....
@@ -1293,6 +1293,7 @@ Auth0
             DispatchQueue.main.async {
                 Auth0
                     .webAuth()
+                    .useHTTPS() // Use a Universal Link callback URL on iOS 17.4+ / macOS 14.4+
                     .connection(connection)
                     .scope(scope)
                     .useEphemeralSession() // Otherwise a session cookie will remain

FAQ.md

@@ -3,6 +3,8 @@
 - [1. How can I disable the _login_ alert box?](#1-how-can-i-disable-the-login-alert-box)
   - [Use ephemeral sessions](#use-ephemeral-sessions)
   - [Use `SFSafariViewController`](#use-sfsafariviewcontroller)
+    - [1. Configure a custom URL scheme](#1-configure-a-custom-url-scheme)
+    - [2. Capture the callback URL](#2-capture-the-callback-url)
 - [2. How can I disable the _logout_ alert box?](#2-how-can-i-disable-the-logout-alert-box)
 - [3. How can I change the message in the alert box?](#3-how-can-i-change-the-message-in-the-alert-box)
 - [4. How can I programmatically close the alert box?](#4-how-can-i-programmatically-close-the-alert-box)
@@ -11,7 +13,7 @@
 
 ## 1. How can I disable the _login_ alert box?
 
-![sso-alert](https://user-images.githubusercontent.com/5055789/198689762-8f3459a7-fdde-4c14-a13b-68933ef675e6.png)
+![Screenshot of the SSO alert box](https://user-images.githubusercontent.com/5055789/198689762-8f3459a7-fdde-4c14-a13b-68933ef675e6.png)
 
 Under the hood, Auth0.swift uses `ASWebAuthenticationSession` by default to perform web-based authentication, which is the [API provided by Apple](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession) for such purpose.
 
@@ -54,7 +56,20 @@ Auth0
 > [!IMPORTANT]
 > Since `SFSafariViewController` does not share cookies with the Safari app, SSO will not work either. But it will keep its own cookies, so you can use it to perform SSO between your app and your website as long as you open it inside your app using `SFSafariViewController`. This also means that any feature that relies on the persistence of cookies –like "Remember this device"– will work as expected.
 
-If you choose to use the `SFSafariViewController` Web Auth provider, you need to perform an additional bit of setup. Unlike `ASWebAuthenticationSession`, `SFSafariViewController` will not automatically capture the callback URL when Auth0 redirects back to your app, so it's necessary to manually resume the Web Auth operation.
+> [!NOTE]
+> `SFSafariViewController` does not support using Universal Links as callback URLs.
+
+If you choose to use the `SFSafariViewController` Web Auth provider, you need to perform an additional bit of setup. Unlike `ASWebAuthenticationSession`, `SFSafariViewController` will not automatically capture the callback URL when Auth0 redirects back to your app, so it is necessary to manually resume the Web Auth operation.
+
+#### 1. Configure a custom URL scheme
+
+In Xcode, go to the **Info** tab of your app target settings. In the **URL Types** section, click the **＋** button to add a new entry. There, enter `auth0` into the **Identifier** field and `$(PRODUCT_BUNDLE_IDENTIFIER)` into the **URL Schemes** field.
+
+![Screenshot of the URL Types section inside the app target settings](https://user-images.githubusercontent.com/5055789/198689930-15f12179-15df-437e-ba50-dec26dbfb21f.png)
+
+This registers your bundle identifier as a custom URL scheme, so the callback URL can reach your app.
+
+#### 2. Capture the callback URL
 
 <details>
   <summary>Using the UIKit app lifecycle</summary>
@@ -96,7 +111,7 @@ SomeView()
 
 ## 2. How can I disable the _logout_ alert box?
 
-![sso-alert](https://user-images.githubusercontent.com/5055789/198689762-8f3459a7-fdde-4c14-a13b-68933ef675e6.png)
+![Screenshot of the SSO alert box](https://user-images.githubusercontent.com/5055789/198689762-8f3459a7-fdde-4c14-a13b-68933ef675e6.png)
 
 Since `clearSession(federated:)` needs to use `ASWebAuthenticationSession` as well to clear the shared session cookie, the same alert box will be displayed. 
 
@@ -119,11 +134,11 @@ Otherwise, the browser modal will close right away and the user will be automati
 
 ## 3. How can I change the message in the alert box?
 
-Auth0.swift has no control whatsoever over the alert box. Its contents cannot be changed. Unfortunately, that's a limitation of `ASWebAuthenticationSession`.
+Auth0.swift has no control whatsoever over the alert box. Its contents cannot be changed. Unfortunately, that is a limitation of `ASWebAuthenticationSession`.
 
 ## 4. How can I programmatically close the alert box?
 
-Auth0.swift has no control whatsoever over the alert box. It cannot be closed programmatically. Unfortunately, that's a limitation of `ASWebAuthenticationSession`. 
+Auth0.swift has no control whatsoever over the alert box. It cannot be closed programmatically. Unfortunately, that is a limitation of `ASWebAuthenticationSession`. 
 
 ---
 

README.md

@@ -36,11 +36,11 @@ Migrating from v1? Check the [Migration Guide](V2_MIGRATION_GUIDE.md).
 
 ### Installation
 
-#### Swift Package Manager
+#### Using the Swift Package Manager
 
 Open the following menu item in Xcode:
 
-**File > Add Packages...**
+**File > Add Package Dependencies...**
 
 In the **Search or Enter Package URL** search box enter this URL: 
 
@@ -50,7 +50,7 @@ https://github.com/auth0/Auth0.swift
 
 Then, select the dependency rule and press **Add Package**.
 
-#### Cocoapods
+#### Using Cocoapods
 
 Add the following line to your `Podfile`:
 
@@ -60,7 +60,7 @@ pod 'Auth0', '~> 2.6'
 
 Then, run `pod install`.
 
-#### Carthage
+#### Using Carthage
 
 Add the following line to your `Cartfile`:
 
@@ -79,7 +79,7 @@ Auth0.swift needs the **Client ID** and **Domain** of the Auth0 application to c
 > [!IMPORTANT]
 > Make sure that the Auth0 application type is **Native**. Otherwise, you might run into errors due to the different configuration of other application types.
 
-#### Configure Client ID and Domain with a plist
+#### Configure the Client ID and Domain with a plist
 
 Create a `plist` file named `Auth0.plist` in your app bundle with the following content:
 
@@ -96,7 +96,7 @@ Create a `plist` file named `Auth0.plist` in your app bundle with the following
 </plist>
 ```
 
-#### Configure Client ID and Domain programmatically
+#### Configure the Client ID and Domain programmatically
 
 <details>
   <summary>For Web Auth</summary>
@@ -130,39 +130,84 @@ Auth0
 
 ### Configure Web Auth (iOS / macOS)
 
-#### Configure callback and logout URLs
+#### Configure the callback and logout URLs
 
 The callback and logout URLs are the URLs that Auth0 invokes to redirect back to your app. Auth0 invokes the callback URL after authenticating the user, and the logout URL after removing the session cookie.
 
 Since callback and logout URLs can be manipulated, you will need to add your URLs to the **Allowed Callback URLs** and **Allowed Logout URLs** fields in the settings page of your Auth0 application. This will enable Auth0 to recognize these URLs as valid. If the callback and logout URLs are not set, users will be unable to log in and out of the app and will get an error.
 
-Go to the settings page of your [Auth0 application](https://manage.auth0.com/#/applications/) and add the corresponding URL to **Allowed Callback URLs** and **Allowed Logout URLs**, according to the platform of your app. If you have a [custom domain](https://auth0.com/docs/customize/custom-domains), replace `YOUR_AUTH0_DOMAIN` with your custom domain instead of the value from the settings page.
+Go to the settings page of your [Auth0 application](https://manage.auth0.com/#/applications/) and add the corresponding URLs to **Allowed Callback URLs** and **Allowed Logout URLs**, according to the platform of your app. If you have a [custom domain](https://auth0.com/docs/customize/custom-domains), replace `YOUR_AUTH0_DOMAIN` with your custom domain instead of the value from the settings page.
+
+> [!NOTE]
+> On iOS 17.4+ and macOS 14.4+ it is possible to use Universal Links as callback and logout URLs. When enabled, Auth0.swift will fall back to using a custom URL scheme on older iOS / macOS versions.
+>
+> **This feature requires Xcode 15.3+ and a paid Apple Developer account**.
 
 ##### iOS
 
 ```text
+https://YOUR_AUTH0_DOMAIN/ios/YOUR_BUNDLE_IDENTIFIER/callback,
 YOUR_BUNDLE_IDENTIFIER://YOUR_AUTH0_DOMAIN/ios/YOUR_BUNDLE_IDENTIFIER/callback
 ```
 
 ##### macOS
 
 ```text
+https://YOUR_AUTH0_DOMAIN/macos/YOUR_BUNDLE_IDENTIFIER/callback,
 YOUR_BUNDLE_IDENTIFIER://YOUR_AUTH0_DOMAIN/macos/YOUR_BUNDLE_IDENTIFIER/callback
 ```
 
-For example, if your iOS bundle identifier was `com.example.MyApp` and your Auth0 Domain was `example.us.auth0.com`, then this value would be:
+<details>
+  <summary>Example</summary>
+
+If your iOS bundle identifier were `com.example.MyApp` and your Auth0 Domain were `example.us.auth0.com`, then this value would be:
 
 ```text
+https://example.us.auth0.com/ios/com.example.MyApp/callback,
 com.example.MyApp://example.us.auth0.com/ios/com.example.MyApp/callback
 ```
+</details>
+
+#### Configure an associated domain
+
+> [!IMPORTANT]
+> This step requires a paid Apple Developer account. It is needed to use Universal Links as callback and logout URLs.
+> Skip this step to use a custom URL scheme instead.
+
+##### Configure the Team ID and bundle identifier
+
+Scroll to the end of the settings page of your Auth0 application and open **Advanced Settings > Device Settings**. In the **iOS** section, set **Team ID** to your [Apple Team ID](https://developer.apple.com/help/account/manage-your-team/locate-your-team-id/), and **App ID** to your app's bundle identifier.
+
+![Screenshot of the iOS section inside the Auth0 application settings page](https://github.com/auth0/Auth0.swift/assets/5055789/7eb5f6a2-7cc7-4c70-acf3-633fd72dc506)
+
+This will add your app to your Auth0 tenant's `apple-app-site-association` file.
+
+##### Add the associated domain capability
 
-#### Configure custom URL scheme
+In Xcode, go to the **Signing and Capabilities** [tab](https://developer.apple.com/documentation/xcode/adding-capabilities-to-your-app#Add-a-capability) of your app's target settings, and press the **+ Capability** button. Then select **Associated Domains**.
 
-Back in Xcode, go to the **Info** tab of your app target settings. In the **URL Types** section, click the **＋** button to add a new entry. There, enter `auth0` into the **Identifier** field and `$(PRODUCT_BUNDLE_IDENTIFIER)` into the **URL Schemes** field.
+![Screenshot of the capabilities library inside Xcode](https://github.com/auth0/Auth0.swift/assets/5055789/3f7b0a70-c36c-46bf-9441-29f98724204a)
 
-![url-scheme](https://user-images.githubusercontent.com/5055789/198689930-15f12179-15df-437e-ba50-dec26dbfb21f.png)
+Next, add the following [entry](https://developer.apple.com/documentation/xcode/configuring-an-associated-domain#Define-a-service-and-its-associated-domain) under **Associated Domains**:
 
-This registers your bundle identifier as a custom URL scheme, so the callback and logout URLs can reach your app.
+```text
+webcredentials:YOUR_AUTH0_DOMAIN
+```
+
+<details>
+  <summary>Example</summary>
+
+If your Auth0 Domain were `example.us.auth0.com`, then this value would be:
+
+```text
+webcredentials:example.us.auth0.com
+```
+</details>
+
+If you have a [custom domain](https://auth0.com/docs/customize/custom-domains), replace `YOUR_AUTH0_DOMAIN` with your custom domain.
+
+> [!NOTE]
+> For the associated domain to work, your app must be signed with your team certificate **even when building for the iOS simulator**. Make sure you are using the Apple Team whose Team ID is configured in the settings page of your Auth0 application.
 
 ### Web Auth login (iOS / macOS)
 
@@ -177,6 +222,7 @@ Then, present the [Universal Login](https://auth0.com/docs/authenticate/login/au
 ```swift
 Auth0
     .webAuth()
+    .useHTTPS() // Use a Universal Link callback URL on iOS 17.4+ / macOS 14.4+
     .start { result in
         switch result {
         case .success(let credentials):
@@ -192,7 +238,7 @@ Auth0
 
 ```swift
 do {
-    let credentials = try await Auth0.webAuth().start()
+    let credentials = try await Auth0.webAuth().useHTTPS().start()
     print("Obtained credentials: \(credentials)")
 } catch {
     print("Failed with: \(error)")
@@ -206,6 +252,7 @@ do {
 ```swift
 Auth0
     .webAuth()
+    .useHTTPS() // Use a Universal Link callback URL on iOS 17.4+ / macOS 14.4+
     .start()
     .sink(receiveCompletion: { completion in
         if case .failure(let error) = completion {
@@ -227,6 +274,7 @@ Call the `clearSession()` method in the action of your **Logout** button. Once t
 ```swift
 Auth0
     .webAuth()
+    .useHTTPS() // Use a Universal Link logout URL on iOS 17.4+ / macOS 14.4+
     .clearSession { result in
         switch result {
         case .success:
@@ -243,7 +291,7 @@ Auth0
 
 ```swift
 do {
-    try await Auth0.webAuth().clearSession()
+    try await Auth0.webAuth().useHTTPS().clearSession()
     print("Session cookie cleared")
     // Delete credentials
 } catch {
@@ -258,6 +306,7 @@ do {
 ```swift
 Auth0
     .webAuth()
+    .useHTTPS() // Use a Universal Link logout URL on iOS 17.4+ / macOS 14.4+
     .clearSession()
     .sink(receiveCompletion: { completion in
         switch completion {
@@ -274,7 +323,7 @@ Auth0
 
 ### SSO alert box (iOS / macOS)
 
-![sso-alert](https://user-images.githubusercontent.com/5055789/198689762-8f3459a7-fdde-4c14-a13b-68933ef675e6.png)
+![Screenshot of the SSO alert box](https://user-images.githubusercontent.com/5055789/198689762-8f3459a7-fdde-4c14-a13b-68933ef675e6.png)
 
 Check the [FAQ](FAQ.md) for more information about the alert box that pops up **by default** when using Web Auth.