diff --git a/articles/quickstart/native/ios-swift/01-login.md b/articles/quickstart/native/ios-swift/01-login.md
index beebee7bdb..3bb225c88c 100755
--- a/articles/quickstart/native/ios-swift/01-login.md
+++ b/articles/quickstart/native/ios-swift/01-login.md
@@ -1,6 +1,6 @@
---
title: Login
-description: This guide demonstrates how to integrate Auth0 with any new or existing iOS / macOS application using the Auth0.swift SDK.
+description: This guide demonstrates how to integrate Auth0 with any new or existing iOS / macOS app using the Auth0.swift SDK.
seo_alias: swift
budicon: 448
topics:
@@ -19,53 +19,86 @@ useCase: quickstart
## Configure Auth0
-### 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 application. Auth0 invokes the callback URL after authenticating the user, and the logout URL after removing the session cookie.
+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 application and will get an error.
+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](${manage_url}/#/applications/${account.clientId}/settings) and add the corresponding URL to **Allowed Callback URLs** and **Allowed Logout URLs**, according to the platform of your application. If you are using a [custom domain](/customize/custom-domains), use the value of your custom domain instead of the Auth0 domain 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**.
+:::
+
+Go to the settings page of your [Auth0 application](${manage_url}/#/applications/${account.clientId}/settings) 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](/customize/custom-domains), use this instead of the Auth0 domain from the settings page.
+
+::: warning
+Make sure that the [application type](/get-started/applications) of the Auth0 application is **Native**. If you don’t have a Native Auth0 application already, [create one](/get-started/auth0-overview/create-applications/native-apps) before continuing.
+:::
#### 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 was `com.example.MyApp` and your Auth0 domain was `example.us.auth0.com`, then this value would be:
+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
```
+### Configure the associated domain
+
::: warning
-Make sure that the [application type](/get-started/applications) of the Auth0 application is **Native**. If you don’t have a Native Auth0 application already, [create one](/get-started/auth0-overview/create-applications/native-apps) before continuing.
+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 a Custom URL Scheme
+#### 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.
-Back in Xcode, go to the **Info** tab of your application 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.
+
-
+This will add your app to your Auth0 tenant's `apple-app-site-association` file.
-This registers your bundle identifer as a custom URL scheme, so the callback and logout URLs can reach your application.
+#### Add the associated domain capability
+
+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**.
+
+
+
+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.
+:::
## Install the SDK
Add the [Auth0.swift](https://github.com/auth0/Auth0.swift) SDK to your project. The library will make requests to the Auth0 Authentication and Management APIs.
-### 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:
@@ -79,7 +112,7 @@ Then, select the dependency rule and press **Add Package**..
For further reference on SPM, check its [official documentation](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app).
:::
-### Cocoapods
+### Using Cocoapods
Add the following line to your `Podfile`:
@@ -93,7 +126,7 @@ Then, run `pod install`.
For further reference on Cocoapods, check their [official documentation](https://guides.cocoapods.org/using/getting-started.html).
:::
-### Carthage
+### Using Carthage
Add the following line to your `Cartfile`:
@@ -112,10 +145,10 @@ For further reference on Carthage, check their [official documentation](https://
The Auth0.swift SDK needs the **Client ID** and **domain** of the Auth0 application to communicate with Auth0. You can find these details in the [settings page](${manage_url}/#/applications/${account.clientId}/settings) of your Auth0 application. If you are using a [custom domain](/customize/custom-domains), use the value of your custom domain instead of the value from the settings page.
<% if(typeof hideDashboardScreenshot === 'undefined' || hideDashboardScreenshot !== true) { %>
-
+
<% } %>
-Create a `plist` file named `Auth0.plist` in your application bundle with the following content:
+Create a `plist` file named `Auth0.plist` in your app bundle with the following content:
```xml
@@ -138,7 +171,7 @@ You can also configure the SDK programmatically. Check the [README](https://gith
:::
::: panel Checkpoint
-Now that you have configured Auth0.swift with the Client ID and domain, run your application to verify that it is not producing any errors related to the SDK.
+Now that you have configured Auth0.swift with the Client ID and domain, run your app to verify that it is not producing any errors related to the SDK.
:::
## Login
@@ -154,6 +187,7 @@ Then, present the [Universal Login](/authenticate/login/auth0-universal-login) p
```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):
@@ -168,21 +202,22 @@ Auth0
You can use async/await or Combine instead of the callback-based API. Check the [README](https://github.com/auth0/Auth0.swift#web-auth-login-ios--macos) to learn more.
:::
-
+
::: panel Checkpoint
Verify that pressing the **Login** button shows an [alert box](https://github.com/auth0/Auth0.swift#sso-alert-box-ios--macos) asking for consent and that choosing **Continue** opens the Universal Login page in a Safari modal. Verify that you can log in or sign up using a username and password or a social provider.
-Once that's complete, verify that the Safari modal closes automatically.
+Once that is complete, verify that the Safari modal closes automatically.
:::
## Logout
-Now that you can log in to your application, you need a way to [log out](/authenticate/login/logout). In the action of your **Logout** button, call the `clearSession()` method to clear the Universal Login session cookie.
+Now that you can log in to your app, you need a way to [log out](/authenticate/login/logout). In the action of your **Logout** button, call the `clearSession()` method to clear the Universal Login session cookie.
```swift
Auth0
.webAuth()
+ .useHTTPS() // Use a Universal Link logout URL on iOS 17.4+ / macOS 14.4+
.clearSession { result in
switch result {
case .success:
@@ -199,7 +234,7 @@ Verify that pressing the **Logout** button shows an alert box asking for consent
## Access User Profile Information
-The `Credentials` instance you obtained after logging in includes an [ID Token](/secure/tokens/id-tokens). The ID Token contains the profile information associated with the logged-in user, such as their email and profile picture. You can use these details to personalize the user interface of your application.
+The `Credentials` instance you obtained after logging in includes an [ID Token](/secure/tokens/id-tokens). The ID Token contains the profile information associated with the logged-in user, such as their email and profile picture. You can use these details to personalize the user interface of your app.
The Auth0.swift SDK includes a [utility](https://github.com/auth0/JWTDecode.swift) for decoding [JWTs](https://jwt.io/) like the ID Token. Start by importing the `JWTDecode` module in the file where you want to access the user profile information.
diff --git a/articles/quickstart/native/ios-swift/download.md b/articles/quickstart/native/ios-swift/download.md
index a850e7f1cd..72e7243cf6 100644
--- a/articles/quickstart/native/ios-swift/download.md
+++ b/articles/quickstart/native/ios-swift/download.md
@@ -1,17 +1,32 @@
+## 1. Configure code signing
+
To run the sample application, first open `SwiftSample.xcodeproj` in Xcode and go to the settings of the application target you want to run. There are two application targets available: **SwiftSample (iOS)** and **SwiftSample (macOS)**. Change the bundle identifier from the default `com.auth0.samples.SwiftSample` to another value of your choosing.
+Then, make sure the **Automatically manage signing** box is checked, and that your Apple Team is selected.
+
+## 2. Configure the associated domain
+
+> **This requires Xcode 15.3+ and a paid Apple Developer account**. If you do not have a paid Apple Developer account, skip this step, and comment out the two `useHTTPS()` calls in `MainView.swift`.
-Then, go to the settings page of your [Auth0 application](${manage_url}/#/applications/${account.clientId}/settings) and add the corresponding URL to **Allowed Callback URLs** and **Allowed Logout URLs**. If you are using a [custom domain](https://auth0.com/docs/customize/custom-domains), use the value of your custom domain instead of the Auth0 Domain from the settings page.
+Go to the **Signing and Capabilities** tab of the app's target settings. Find the `webcredentials:{YOUR_AUTH0_DOMAIN}` entry under **Associated Domains**, and replace the placeholder `{YOUR_AUTH0_DOMAIN}` value with the domain of your Auth0 application. If 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.
+
+## 3. Configure the Auth0 application
+
+Open the settings page of your [Auth0 application](${manage_url}/#/applications/${account.clientId}/settings) and add the corresponding URLs to **Allowed Callback URLs** and **Allowed Logout URLs**. 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.
For **SwiftSample (iOS)**:
```text
-YOUR_BUNDLE_IDENTIFIER://${account.namespace}/ios/YOUR_BUNDLE_IDENTIFIER/callback
+https://YOUR_AUTH0_DOMAIN/ios/YOUR_BUNDLE_IDENTIFIER/callback,
+YOUR_BUNDLE_IDENTIFIER://YOUR_AUTH0_DOMAIN/ios/YOUR_BUNDLE_IDENTIFIER/callback
```
For **SwiftSample (macOS)**:
```text
-YOUR_BUNDLE_IDENTIFIER://${account.namespace}/macos/YOUR_BUNDLE_IDENTIFIER/callback
+https://YOUR_AUTH0_DOMAIN/macos/YOUR_BUNDLE_IDENTIFIER/callback,
+YOUR_BUNDLE_IDENTIFIER://YOUR_AUTH0_DOMAIN/macos/YOUR_BUNDLE_IDENTIFIER/callback
```
+
+Then, scroll to the end of the settings page 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.
diff --git a/articles/quickstart/native/ios-swift/files/MainView.md b/articles/quickstart/native/ios-swift/files/MainView.md
index e4a147f84b..e62095b332 100644
--- a/articles/quickstart/native/ios-swift/files/MainView.md
+++ b/articles/quickstart/native/ios-swift/files/MainView.md
@@ -26,6 +26,7 @@ extension MainView {
func login() {
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):
@@ -39,6 +40,7 @@ extension MainView {
func logout() {
Auth0
.webAuth()
+ .useHTTPS() // Use a Universal Link logout URL on iOS 17.4+ / macOS 14.4+
.clearSession { result in
switch result {
case .success:
diff --git a/articles/quickstart/native/ios-swift/interactive.md b/articles/quickstart/native/ios-swift/interactive.md
index 787d69386d..bb4f426849 100644
--- a/articles/quickstart/native/ios-swift/interactive.md
+++ b/articles/quickstart/native/ios-swift/interactive.md
@@ -43,43 +43,76 @@ If you would rather explore a complete configuration, you can view a sample app
### Configure callback and logout URLs
-Auth0 invokes the callback and logout URLs to redirect users back to your application. Auth0 invokes the callback URL after authenticating the user and the logout URL after removing the session cookie. If you do not set the callback and login URLs, users will not be able to log in and out of the app, and your application will produce an error.
+Auth0 invokes the callback and logout URLs to redirect users back to your app. Auth0 invokes the callback URL after authenticating the user and the logout URL after removing the session cookie. If you do not set the callback and login URLs, users will not be able to log in and out of the app, and your app will produce an error.
-Add the corresponding URL to **Callback URLs** and **Logout URLs**, according to your app's platform. If you are using a [custom domain](/customize/custom-domains), use the value of your custom domain instead of your Auth0 tenant’s domain.
+::: 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**.
+:::
+
+Add the corresponding URLs to **Callback URLs** and **Logout URLs**, according to the platform of your app. If you have a [custom domain](/customize/custom-domains), use this instead of your Auth0 tenant’s domain.
#### 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 was `com.example.MyApp` and your Auth0 domain was `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
```
-## Configure your app
+### Configure the associated domain
+
+::: 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 of your [Auth0 application](${manage_url}/#/applications/${account.clientId}/settings), 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.
+
+
-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, click the **＋** button to add a new entry. There, enter `auth0` into the **Identifier** field and `$(PRODUCT_BUNDLE_IDENTIFIER)` into the **URL Schemes** field.
+#### Add the associated domain capability
-
+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**.
+
+
+
+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 your Auth0 tenant’s 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.
+:::
## Install the SDK
-### 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:
@@ -93,7 +126,7 @@ Then, select the dependency rule and press **Add Package**.
For further reference on SPM, check its [official documentation](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app).
:::
-### Cocoapods
+### Using Cocoapods
Add the following line to your `Podfile`:
@@ -107,7 +140,7 @@ Then, run `pod install`.
For further reference on Cocoapods, check their [official documentation](https://guides.cocoapods.org/using/getting-started.html).
:::
-### Carthage
+### Using Carthage
Add the following line to your `Cartfile`:
@@ -125,7 +158,7 @@ For further reference on Carthage, check their [official documentation](https://
The Auth0.swift SDK needs your Auth0 **domain** and **Client ID**. You can find these values in the [settings page](${manage_url}/#/applications/${account.clientId}/settings) of your Auth0 application.
-- **domain**: The domain of your Auth0 tenant. If you are using a [custom domain](/customize/custom-domains), you should set this to the value of your custom domain instead.
+- **domain**: The domain of your Auth0 tenant. If you have a [custom domain](/customize/custom-domains), use this instead of your Auth0 tenant’s domain.
- **Client ID**: The alphanumeric, unique ID of the Auth0 application you set up earlier in this quickstart.
Create a `plist` file named `Auth0.plist` in your app bundle containing the Auth0 domain and Client ID values.
@@ -140,7 +173,7 @@ You configured the Auth0.swift SDK. Run your app to verify that it is not produc
:::
:::checkpoint-failure
-If your application produces errors related to the SDK:
+If your app produces errors related to the SDK:
- Make sure you selected the correct Auth0 application
- Verify you saved your URL updates
- Ensure you set the Auth0 domain and Client ID correctly
@@ -149,7 +182,7 @@ Still having issues? Check out our [documentation](https://github.com/auth0/Auth
:::
::::
-## Add login to your app {{{ data-action=code data-code="MainView.swift#20:31" }}}
+## Add login to your app {{{ data-action=code data-code="MainView.swift#20:32" }}}
Import the `Auth0` module in the file where you want to present the login page. Then, present the [Universal Login](/authenticate/login/auth0-universal-login) page in the action of your **Login** button.
@@ -157,7 +190,7 @@ Import the `Auth0` module in the file where you want to present the login page.
You can use async/await or Combine instead of the callback-based API. Check the [README](https://github.com/auth0/Auth0.swift#web-auth-login-ios--macos) to learn more.
:::
-
+
::::checkpoint
:::checkpoint-default
@@ -177,7 +210,7 @@ Still having issues? Check out our [documentation](https://github.com/auth0/Auth
:::
::::
-## Add logout to your app {{{ data-action=code data-code="MainView.swift#33:44" }}}
+## Add logout to your app {{{ data-action=code data-code="MainView.swift#34:46" }}}
Now that you can log in to your app, you need a way to [log out](/authenticate/login/logout). In the action of your **Logout** button, call the `clearSession()` method to clear the Universal Login session cookie.
diff --git a/media/articles/native-platforms/ios-swift/ios-device-settings.png b/media/articles/native-platforms/ios-swift/ios-device-settings.png
new file mode 100644
index 0000000000..2c4f13d3b4
Binary files /dev/null and b/media/articles/native-platforms/ios-swift/ios-device-settings.png differ
diff --git a/media/articles/native-platforms/ios-swift/ios-xcode-capabilities.png b/media/articles/native-platforms/ios-swift/ios-xcode-capabilities.png
new file mode 100644
index 0000000000..40fc700acf
Binary files /dev/null and b/media/articles/native-platforms/ios-swift/ios-xcode-capabilities.png differ
diff --git a/media/articles/native-platforms/ios-swift/url-scheme.png b/media/articles/native-platforms/ios-swift/url-scheme.png
deleted file mode 100644
index 144cfd42ac..0000000000
Binary files a/media/articles/native-platforms/ios-swift/url-scheme.png and /dev/null differ
