Update the Flutter QS to feature HTTPS redirect URLs on iOS/macOS [SDK-4756] (#10385)

* Update the Flutter QS to include HTTPS redirect URLs on iOS/macOS

* Update the `download.md` instructions

* Update reference to Xcode UI

* Rework a few sentences

* Reword sentence in `download.md`

* Rephrase custom domain callout

Author: Widcket

articles/quickstart/native/flutter/01-login.md

@@ -26,7 +26,7 @@ github:
 Auth0 allows you to quickly add authentication and access user profile information in your app. This guide demonstrates how to integrate Auth0 with a Flutter app using the [Auth0 Flutter SDK](https://github.com/auth0/auth0-flutter).
 
 :::note
-The Flutter SDK currently only supports Flutter app running on Android, iOS, and macOS platforms.
+The Flutter SDK currently only supports Flutter apps for Android, iOS, and macOS.
 :::
 
 ## Getting started
@@ -35,7 +35,49 @@ This quickstart assumes you already have a [Flutter](https://flutter.dev/) app u
 
 You should also be familiar with the [Flutter command line tool](https://docs.flutter.dev/reference/flutter-cli).
 
-<%= include('_configure_urls_interactive') %>
+Finally, you will need a **Native** Auth0 application. If you don’t have a Native Auth0 application already, [create one](/get-started/auth0-overview/create-applications/native-apps) before continuing. Avoid using other application types, as they have different configurations and may cause errors.
+
+### 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.
+
+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](${manage_url}/#/applications/${account.clientId}/settings) of your Auth0 application and add the following URLs to **Allowed Callback URLs** and **Allowed Logout URLs**, depending on the platform of your app. If you have a [custom domain](/customize/custom-domains), use this instead of the Auth0 domain from the settings page.
+
+::: note
+On Android, the value of the `SCHEME` placeholder can be `https` or some other custom scheme. `https` schemes require enabling [Android App Links](https://auth0.com/docs/get-started/applications/enable-android-app-links-support).
+
+On iOS 17.4+ and macOS 14.4+ it is possible to use Universal Links (`https` scheme) as callback and logout URLs. When enabled, the SDK will fall back to using a custom URL scheme on older iOS / macOS versions –your app's [bundle identifier](https://developer.apple.com/documentation/appstoreconnectapi/bundle_ids).
+**This feature requires Xcode 15.3+ and a paid Apple Developer account**.
+:::
+
+#### Android
+
+```text
+SCHEME://${account.namespace}/android/YOUR_PACKAGE_NAME/callback
+```
+
+#### iOS
+
+```text
+https://${account.namespace}/ios/YOUR_BUNDLE_IDENTIFIER/callback,
+YOUR_BUNDLE_IDENTIFIER://${account.namespace}/ios/YOUR_BUNDLE_IDENTIFIER/callback
+```
+
+#### macOS
+
+```text
+https://${account.namespace}/macos/YOUR_BUNDLE_IDENTIFIER/callback,
+YOUR_BUNDLE_IDENTIFIER://${account.namespace}/macos/YOUR_BUNDLE_IDENTIFIER/callback
+```
+
+For example, 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
+```
 
 ## Install the Auth0 Flutter SDK
 
@@ -81,13 +123,37 @@ Run **Sync Project with Gradle Files** inside Android Studio to apply your chang
 
 ## Configure iOS/macOS
 
-If you are not developing for the iOS or macOS platform, skip this step.
+If you are not developing for the iOS or macOS platforms, skip this step.
+
+::: warning
+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
+
+Go to the [settings page](${manage_url}/#/applications/${account.clientId}/settings) of your Auth0 application, scroll to the end, 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.
+
+<p><img src="/media/articles/native-platforms/ios-swift/ios-device-settings.png" alt="Screenshot of the iOS section inside the Auth0 application settings page"></p>
 
-You need to register your bundle identifier as a custom URL scheme so the callback and logout URLs can reach your app.
+This will add your app to your Auth0 tenant's `apple-app-site-association` file.
 
-In Xcode, go to the **Info** tab of your app target settings. In the **URL Types** section, select the **＋** button to add a new entry. Then enter `auth0` into the **Identifier** field and `$(PRODUCT_BUNDLE_IDENTIFIER)` into the **URL Schemes** field.
+#### Add the associated domain capability
 
-<p><img src="/media/articles/native-platforms/ios-swift/url-scheme.png" alt="Custom URL Scheme"></p>
+Open your app in Xcode by running `open ios/Runner.xcworkspace` (or `open macos/Runner.xcworkspace` for macOS). Go to the **Signing and Capabilities** [tab](https://developer.apple.com/documentation/xcode/adding-capabilities-to-your-app#Add-a-capability) of the **Runner** target settings, and press the **+ Capability** button. Then select **Associated Domains**.
+
+<p><img src="/media/articles/native-platforms/ios-swift/ios-xcode-capabilities.png" alt="Screenshot of the capabilities library inside Xcode"></p>
+
+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**:
+
+```text
+webcredentials:${account.namespace}
+```
+
+If you have a [custom domain](/customize/custom-domains), use this instead of the Auth0 domain from the settings page.
+
+::: 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.
+:::
 
 ## Add login to your app
 
@@ -129,8 +195,10 @@ Next, redirect your users to the Auth0 Universal Login page using `webAuthentica
 if (_credentials == null) {
   ElevatedButton(
     onPressed: () async {
+      // Use a Universal Link callback URL on iOS 17.4+ / macOS 14.4+
+      // useHTTPS is ignored on Android
       final credentials =
-          await auth0.webAuthentication().login();
+          await auth0.webAuthentication().login(useHTTPS: true);
 
       setState(() {
         _credentials = credentials;
@@ -177,7 +245,9 @@ See this example of an `ElevatedButton` widget that logs the user out of the app
 ```dart
 ElevatedButton(
   onPressed: () async {
-    await auth0.webAuthentication().logout();
+    // Use a Universal Link logout URL on iOS 17.4+ / macOS 14.4+
+    // useHTTPS is ignored on Android
+    await auth0.webAuthentication().logout(useHTTPS: true);
 
     setState(() {
       _credentials = null;

articles/quickstart/native/flutter/_configure_urls_interactive.md

@@ -2,44 +2,50 @@
 
 To use Auth0 services, you need to have an application set up in the Auth0 Dashboard. The Auth0 application is where you will configure how you want authentication to work for your project.
 
-:::note
-The URLs below make use of a `SCHEME` placeholder, and this value varies depending on what platform you're working with. On Android, this can be `https` or some other custom scheme. On iOS/macOS, this is your app's [bundle identifier](https://developer.apple.com/documentation/appstoreconnectapi/bundle_ids).
-:::
-
 ### Configure an Auth0 application
 
-Use the interactive selector to create a new "Native Application", or select an existing application that represents the project you want to integrate with. Every application in Auth0 is assigned an alphanumeric, unique client ID that your application code will use to call Auth0 APIs through the SDK.
+Use the interactive selector to create a new Auth0 application or select an existing **Native** Auth0 application. Every application in Auth0 is assigned an alphanumeric, unique client ID that your application code will use to call Auth0 APIs through the SDK.
 
 Any settings you configure using this quickstart will automatically update for your application in the <a href="${manage_url}/#/">Dashboard</a>, which is where you can manage your applications in the future.
 
 If you would rather explore a complete configuration, you can view a sample app instead.
 
-### Configure Callback URLs
+### Configure the callback and logout URLs
 
-A callback URL is a URL in your app that you would like Auth0 to redirect users to after they have authenticated. If not set, users will not be returned to your app after they log in.
-
-::: note
-If you are following along with our sample project, set this to one of the following URLs, depending on your platform:
+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. 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.
 
-**Android**: `SCHEME://${account.namespace}/android/YOUR_PACKAGE_NAME/callback`
+Set the callback and logout URLs to the following values, depending on your platform.
 
-**iOS**: `YOUR_BUNDLE_ID://${account.namespace}/ios/YOUR_BUNDLE_ID/callback`
+::: note
+On Android, the value of the `SCHEME` placeholder can be `https` or some other custom scheme. `https` schemes require enabling [Android App Links](https://auth0.com/docs/get-started/applications/enable-android-app-links-support).
 
-**macOS**: `YOUR_BUNDLE_ID://${account.namespace}/macos/YOUR_BUNDLE_ID/callback`
+On iOS 17.4+ and macOS 14.4+ it is possible to use Universal Links (`https` scheme) as callback and logout URLs. When enabled, the SDK will fall back to using a custom URL scheme on older iOS / macOS versions –your app's [bundle identifier](https://developer.apple.com/documentation/appstoreconnectapi/bundle_ids).
+**This feature requires Xcode 15.3+ and a paid Apple Developer account**.
 :::
 
-### Configure Logout URLs
+#### Android
 
-A logout URL is a URL in your app that you would like Auth0 to redirect users to after they have logged out. If not set, users will not be able to log out from your app and will receive an error.
+```text
+SCHEME://${account.namespace}/android/YOUR_PACKAGE_NAME/callback
+```
 
-::: note
-If you are following along with our sample project, set this to one of the following URLs, depending on your platform:
+#### iOS
 
-**Android**: `SCHEME://${account.namespace}/android/YOUR_PACKAGE_NAME/callback`
+```text
+https://${account.namespace}/ios/YOUR_BUNDLE_IDENTIFIER/callback,
+YOUR_BUNDLE_IDENTIFIER://${account.namespace}/ios/YOUR_BUNDLE_IDENTIFIER/callback
+```
 
-**iOS**: `YOUR_BUNDLE_ID://${account.namespace}/ios/YOUR_BUNDLE_ID/callback`
+#### macOS
 
-**macOS**: `YOUR_BUNDLE_ID://${account.namespace}/macos/YOUR_BUNDLE_ID/callback`
-:::
+```text
+https://${account.namespace}/macos/YOUR_BUNDLE_IDENTIFIER/callback,
+YOUR_BUNDLE_IDENTIFIER://${account.namespace}/macos/YOUR_BUNDLE_IDENTIFIER/callback
+```
+
+For example, if your iOS bundle identifier were `com.example.MyApp` and your Auth0 domain were `example.us.auth0.com`, then this value would be:
 
-Lastly, be sure that the **Application Type** for your application is set to **Native** in the [Application Settings](${manage_url}/#/applications/${account.clientId}/settings).
+```text
+https://example.us.auth0.com/ios/com.example.MyApp/callback,
+com.example.MyApp://example.us.auth0.com/ios/com.example.MyApp/callback
+```

articles/quickstart/native/flutter/download.md

@@ -1,31 +1,25 @@
-To run the sample follow these steps:
+<!-- markdownlint-disable MD041 -->
 
-1) Set the **Allowed Callback URLs** and **Allowed Logout URLs** in the [Application Settings](${manage_url}/#/applications/${account.clientId}/settings) to the following value so it works for Android, iOS, and macOS apps:
+> On every step, if you have a [custom domain](https://auth0.com/docs/customize/custom-domains), replace the `YOUR_AUTH0_DOMAIN` placeholder with your custom domain instead of the value from the settings page.
 
-```text
-com.auth0.samples.FlutterSample://${account.namespace}/ios/com.auth0.samples.FlutterSample/callback,com.auth0.sample://${account.namespace}/android/com.auth0.sample/callback,com.auth0.sample://${account.namespace}/macos/com.auth0.sample/callback
-```
+## 1. Configure the Auth0 application
 
-2) Rename the file `.env.example` to `.env` and fill in the following values:
+Open the settings page of your Auth0 application and add the following URLs to **Allowed Callback URLs** and **Allowed Logout URLs**, depending on the platform you want to use.
 
-```sh
-AUTH0_DOMAIN=${account.namespace}
-AUTH0_CLIENT_ID=${account.clientId}
-AUTH0_CUSTOM_SCHEME=com.auth0.sample
-```
+- Android: `com.auth0.sample://YOUR_AUTH0_DOMAIN/android/com.auth0.sample/callback`
+- iOS: `https://YOUR_AUTH0_DOMAIN/ios/YOUR_BUNDLE_IDENTIFIER/callback,YOUR_BUNDLE_IDENTIFIER://YOUR_AUTH0_DOMAIN/ios/YOUR_BUNDLE_IDENTIFIER/callback`
+- macOS: `https://YOUR_AUTH0_DOMAIN/macos/YOUR_BUNDLE_IDENTIFIER/callback,YOUR_BUNDLE_IDENTIFIER://YOUR_AUTH0_DOMAIN/macos/YOUR_BUNDLE_IDENTIFIER/callback`
 
-3) Rename the file `strings.xml.example` in `android/app/src/main/res/values` to `strings.xml` and fill in the following values:
+## 2. Configure the associated domain (iOS/macOS only)
 
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<resources>
-    <string name="com_auth0_domain">${account.namespace}</string>
-    <string name="com_auth0_scheme">com.auth0.sample</string>
-</resources>
-```
+> **This following requires Xcode 15.3+ and a paid Apple Developer account**. If you do not have a paid Apple Developer account, skip this step, and set the `useHTTPS` parameter to `false` in the `login()` and `logout()` calls at `lib/example_app.dart`.
 
-4) Use the [Flutter CLI's](https://docs.flutter.dev/reference/flutter-cli) `run` command to run the app:
+Open `ios/Runner.xcodeproj` (or `macos/Runner.xcodeproj`, for macOS) in Xcode and go to the settings of the **Runner** app target. In the **Signing & Capabilities** tab, change the bundle identifier from the default `com.auth0.samples.FlutterSample` to another value of your choosing. Then, make sure the **Automatically manage signing** box is checked, and that your Apple Team is selected.
 
-```sh
-flutter run
-```
+Next, find the `webcredentials:YOUR_AUTH0_DOMAIN` entry under **Associated Domains**, and replace the `YOUR_AUTH0_DOMAIN` placeholder with the domain of your Auth0 application.
+
+Finally, open the settings page of your Auth0 application, scroll to the end, 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 the app's bundle identifier.
+
+## 3. Run the app
+
+Use the [Flutter CLI](https://docs.flutter.dev/reference/flutter-cli) to run the app: `flutter run`.

articles/quickstart/native/flutter/files/main.md

@@ -34,8 +34,10 @@ class _MainViewState extends State<MainView> {
         if (_credentials == null)
           ElevatedButton(
               onPressed: () async {
+                // Use a Universal Link callback URL on iOS 17.4+ / macOS 14.4+
+                // useHTTPS is ignored on Android
                 final credentials =
-                    await auth0.webAuthentication().login();
+                    await auth0.webAuthentication().login(useHTTPS: true);
 
                 setState(() {
                   _credentials = credentials;
@@ -48,7 +50,9 @@ class _MainViewState extends State<MainView> {
               ProfileView(user: _credentials!.user),
               ElevatedButton(
                   onPressed: () async {
-                    await auth0.webAuthentication().logout();
+                    // Use a Universal Link logout URL on iOS 17.4+ / macOS 14.4+
+                    // useHTTPS is ignored on Android
+                    await auth0.webAuthentication().logout(useHTTPS: true);
 
                     setState(() {
                       _credentials = null;