From 6272b08edbf226bc4e5d846e957294a5f112f4e6 Mon Sep 17 00:00:00 2001 From: Rita Zerrizuela Date: Wed, 13 Mar 2024 23:09:28 +0000 Subject: [PATCH 1/8] Document the HTTPS redirect URLs feature --- README.md | 23 +++-- auth0_flutter/EXAMPLES.md | 84 +++++++++++++++++++ auth0_flutter/FAQ.md | 55 ++---------- auth0_flutter/README.md | 97 ++++++++++++---------- auth0_flutter_platform_interface/README.md | 23 +++-- 5 files changed, 164 insertions(+), 118 deletions(-) diff --git a/README.md b/README.md index 418a3d2c..acba561c 100644 --- a/README.md +++ b/README.md @@ -20,19 +20,16 @@ For general support or usage questions, use the [Auth0 Community](https://commun **Do not report security vulnerabilities on the public GitHub issue tracker.** The [Responsible Disclosure Program](https://auth0.com/responsible-disclosure-policy) details the procedure for disclosing security issues. -## What is Auth0? +--- -Auth0 helps you to: +

+ + + + Auth0 Logo + +

-- Add authentication with [multiple sources](https://auth0.com/docs/authenticate/identity-providers), either social identity providers such as **Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce** (amongst others), or enterprise identity systems like **Windows Azure AD, Google Apps, Active Directory, ADFS, or any SAML identity provider**. -- Add authentication through more traditional **[username/password databases](https://auth0.com/docs/authenticate/database-connections/custom-db)**. -- Add support for **[linking different user accounts](https://auth0.com/docs/manage-users/user-accounts/user-account-linking)** with the same user. -- Support for generating signed [JSON web tokens](https://auth0.com/docs/secure/tokens/json-web-tokens) to call your APIs and **flow the user identity** securely. -- Analytics of how, when, and where users are logging in. -- Pull data from other sources and add it to the user profile through [JavaScript Actions](https://auth0.com/docs/customize/actions). +

Auth0 is an easy-to-implement, adaptable authentication and authorization platform. To learn more check out Why Auth0?

-**Why Auth0?** Because you should save time, be happy, and focus on what really matters: building your product. - -## License - -This project is licensed under Apache License 2.0. See the [LICENSE](LICENSE) file for more information. +

This project is licensed under the MIT license. See the LICENSE file for more info.

diff --git a/auth0_flutter/EXAMPLES.md b/auth0_flutter/EXAMPLES.md index b8b3a04c..7dc413a2 100644 --- a/auth0_flutter/EXAMPLES.md +++ b/auth0_flutter/EXAMPLES.md @@ -7,6 +7,9 @@ - [Adding scopes](#adding-scopes) - [Adding custom parameters](#adding-custom-parameters) - [ID token validation](#id-token-validation) + - [Using `SFSafariViewController` (iOS only)](#using-sfsafariviewcontroller-ios-only) + - [1. Configure a custom URL scheme](#1-configure-a-custom-url-scheme) + - [2. Capture the callback URL](#2-capture-the-callback-url) - [Errors](#errors) - [Android: Custom schemes](#android-custom-schemes) - [📱 Credentials Manager](#-credentials-manager) @@ -38,6 +41,9 @@ - [Adding scopes](#adding-scopes) - [Adding custom parameters](#adding-custom-parameters) - [ID token validation](#id-token-validation) + - [Using `SFSafariViewController` (iOS only)](#using-sfsafariviewcontroller-ios-only) + - [1. Configure a custom URL scheme](#1-configure-a-custom-url-scheme) + - [2. Capture the callback URL](#2-capture-the-callback-url) - [Errors](#errors) - [Android: Custom schemes](#android-custom-schemes) @@ -239,6 +245,84 @@ await auth0Web.loginWithRedirect( +### Using `SFSafariViewController` (iOS only) + +auth0_flutter supports using `SFSafariViewController` as the browser instead of `ASWebAuthenticationSession`. You can do so by setting the `safariViewController` property during login: + +```dart +await auth0 + .webAuthentication() + .login(safariViewController: const SafariViewController()); +``` + +> 💡 `SFSafariViewController` does not support using a Universal Link as callback URL. See https://auth0.github.io/Auth0.swift/documentation/auth0/useragents to learn more about the differences between `ASWebAuthenticationSession` and `SFSafariViewController`. + +If you choose to use `SFSafariViewController`, 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 login operation. + +#### 1. Configure a custom URL scheme + +There is an `Info.plist` file in the `ios/Runner` (or `macos/Runner`, for macOS) directory of your app. Open it and add the following snippet inside the top-level `` tag. This registers your iOS/macOS bundle identifier as a custom URL scheme, so the callback URL can reach your app. + +```xml + + + + + + + + CFBundleURLTypes + + + CFBundleTypeRole + None + CFBundleURLName + auth0 + CFBundleURLSchemes + + $(PRODUCT_BUNDLE_IDENTIFIER) + + + + + + +``` + +> 💡 If you're opening the `Info.plist` file in Xcode and it is not being shown in this format, you can **Right Click** on `Info.plist` in the Xcode [project navigator](https://developer.apple.com/documentation/bundleresources/information_property_list/managing_your_app_s_information_property_list) and then select **Open As > Source Code**. + +#### 2. Capture the callback URL + +
+ Using the UIKit app lifecycle + +```swift +// AppDelegate.swift + +override func application(_ app: UIApplication, + open url: URL, + options: [UIApplication.OpenURLOptionsKey: Any]) -> Bool { + WebAuthentication.resume(with: url) + return super.application(application, open: url, options: options); +} +``` + +
+ +
+ Using the UIKit app lifecycle with Scenes + +```swift +// SceneDelegate.swift + +func scene(_ scene: UIScene, openURLContexts URLContexts: Set) { + guard let url = URLContexts.first?.url else { return } + WebAuthentication.resume(with: url) +} +``` + +
+ ### Errors
diff --git a/auth0_flutter/FAQ.md b/auth0_flutter/FAQ.md index fa640ea9..84f3303e 100644 --- a/auth0_flutter/FAQ.md +++ b/auth0_flutter/FAQ.md @@ -60,14 +60,13 @@ Alternatively, you can re-declare the `RedirectActivity` in the `android/app/src ### 2. How can I disable the iOS _login_ alert box? -![ios-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) Auth0.swift uses `ASWebAuthenticationSession` to perform web-based authentication, which is the [API provided by Apple](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession) for such purpose. That alert box is displayed and managed by `ASWebAuthenticationSession`, not by Auth0.swift, because by default this API will store the session cookie in the shared Safari cookie jar. This makes Single Sign-On (SSO) possible. According to Apple, that requires user consent. -> **Note** -> See [this blog post](https://developer.okta.com/blog/2022/01/13/mobile-sso) for a detailed overview of SSO on iOS. +> 💡 See [this blog post](https://developer.okta.com/blog/2022/01/13/mobile-sso) for a detailed overview of SSO on iOS. #### Use ephemeral sessions @@ -83,56 +82,15 @@ Note that with `useEphemeralSession: true` you don't need to call `logout()` at You still need to call `logout()` on Android, though, as `useEphemeralSession` is iOS/macOS only. -> **Warning** > `useEphemeralSession` relies on the `prefersEphemeralWebBrowserSession` configuration option of `ASWebAuthenticationSession`. +> ⚠️ `useEphemeralSession` relies on the `prefersEphemeralWebBrowserSession` configuration option of `ASWebAuthenticationSession`. #### Use `SFSafariViewController` -An alternative is to use `SFSafariViewController` instead of `ASWebAuthenticationSession`. You can do so by setting the `safariViewController` property during login: - -```dart -await auth0 - .webAuthentication() - .login(safariViewController: const SafariViewController()); -``` - -> **Note** -> 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 will work as expected. - -If you choose to use `SFSafariViewController`, 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. - -
- Using the UIKit app lifecycle - -```swift -// AppDelegate.swift - -override func application(_ app: UIApplication, - open url: URL, - options: [UIApplication.OpenURLOptionsKey: Any]) -> Bool { - WebAuthentication.resume(with: url) - return super.application(application, open: url, options: options); -} -``` - -
- -
- Using the UIKit app lifecycle with Scenes - -```swift -// SceneDelegate.swift - -func scene(_ scene: UIScene, openURLContexts URLContexts: Set) { - guard let url = URLContexts.first?.url else { return } - WebAuthentication.resume(with: url) -} -``` - -
+An alternative is to use `SFSafariViewController` instead of `ASWebAuthenticationSession`. See [EXAMPLES.md](./EXAMPLES.md#using-sfsafariviewcontroller-ios-only). ### 3. How can I disable the iOS _logout_ alert box? -![ios-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 `logout()` on iOS also needs to use `ASWebAuthenticationSession` to clear the shared session cookie, the same alert box will be displayed. @@ -148,8 +106,7 @@ final credentials = await auth0.webAuthentication().login( Otherwise, the browser modal will close right away and the user will be automatically logged in again, as the cookie will still be there. -> **Warning** -> Keeping the shared session cookie may not be an option if you have strong privacy and/or security requirements, for example in the case of a banking app. +> ⚠️ Keeping the shared session cookie may not be an option if you have strong privacy and/or security requirements, for example in the case of a banking app. ### 4. How can I change the message in the iOS alert box? diff --git a/auth0_flutter/README.md b/auth0_flutter/README.md index 628a42a7..c0980684 100644 --- a/auth0_flutter/README.md +++ b/auth0_flutter/README.md @@ -47,7 +47,7 @@ Head to the [Auth0 Dashboard](https://manage.auth0.com/#/applications/) and crea Select the **Settings** tab of your [application's page](https://manage.auth0.com/#/applications/) and ensure that **Application Type** is set to `Native`. -Then, scroll down and select the **Show Advanced Settings** link. Under **Advanced Settings**, select the **OAuth** tab and verify the following: +Scroll down and select the **Show Advanced Settings** link. Under **Advanced Settings**, select the **OAuth** tab and verify the following: - Ensure that **JsonWebToken Signature Algorithm** is set to `RS256` - Ensure that **OIDC Conformant** is enabled @@ -56,11 +56,19 @@ Finally, if you made any changes don't forget to scroll to the end and press the
-Next, configure the following URLs for your application under the **Application URIs** section of the **Settings** page, for both **Allowed Callback URLs** and **Allowed 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. + +> 💡 On iOS 17.4+ and macOS 14.4+ it is possible to use Universal Links as callback and logout URLs. When enabled, auth0_flutter 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**. + +Under the **Application URIs** section of the **Settings** page, configure the following URLs for your application for both **Allowed Callback URLs** and **Allowed Logout URLs**: - Android: `SCHEME://YOUR_DOMAIN/android/YOUR_PACKAGE_NAME/callback` -- iOS: `YOUR_BUNDLE_ID://YOUR_DOMAIN/ios/YOUR_BUNDLE_ID/callback` -- macOS: `YOUR_BUNDLE_ID://YOUR_DOMAIN/macos/YOUR_BUNDLE_ID/callback` +- iOS: `https://YOUR_DOMAIN/ios/YOUR_BUNDLE_ID/callback,YOUR_BUNDLE_ID://YOUR_DOMAIN/ios/YOUR_BUNDLE_ID/callback` +- macOS: `https://YOUR_DOMAIN/macos/YOUR_BUNDLE_ID/callback,YOUR_BUNDLE_ID://YOUR_DOMAIN/macos/YOUR_BUNDLE_ID/callback`
Example @@ -68,12 +76,20 @@ Next, configure the following URLs for your application under the **Application If your Auth0 domain was `company.us.auth0.com` and your package name (Android) or bundle ID (iOS/macOS) was `com.company.myapp`, then these values would be: - Android: `https://company.us.auth0.com/android/com.company.myapp/callback` -- iOS: `com.company.myapp://company.us.auth0.com/ios/com.company.myapp/callback` -- macOS: `com.company.myapp://company.us.auth0.com/macos/com.company.myapp/callback` +- iOS: `https://company.us.auth0.com/ios/com.company.myapp/callback,com.company.myapp://company.us.auth0.com/ios/com.company.myapp/callback` +- macOS: `https://company.us.auth0.com/macos/com.company.myapp/callback,com.company.myapp://company.us.auth0.com/macos/com.company.myapp/callback`
-Take note of the **client ID** and **domain** values under the **Basic Information** section. You'll need these values in the next step. +Take note of the **client ID** and **domain** values under the **Basic Information** section. You will need these values to configure the SDK. + +##### Configure the Team ID and bundle identifier + +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 your app's bundle identifier. + +![Screenshot of the iOS section inside the Settings page of the Auth0 application](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. #### 🌐 Web @@ -188,37 +204,34 @@ Re-declare the activity manually using `tools:node="remove"` in the `android/src > 💡 If your Android app is using [product flavors](https://developer.android.com/studio/build/build-variants#product-flavors), you might need to specify different manifest placeholders for each flavor. -##### iOS/macOS: Configure custom URL scheme +##### iOS/macOS: Add the associated domain capability -There is an `Info.plist` file in the `ios/Runner` (or `macos/Runner`, for macOS) directory of your app. Open it and add the following snippet inside the top-level `` tag. This registers your iOS/macOS bundle identifier as a custom URL scheme, so the callback and logout URLs can reach your app. +> ⚠️ 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. -```xml - - - - - - - - CFBundleURLTypes - - - CFBundleTypeRole - None - CFBundleURLName - auth0 - CFBundleURLSchemes - - $(PRODUCT_BUNDLE_IDENTIFIER) - - - - - - +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**. + +![Screenshot of the capabilities library inside Xcode](https://github.com/auth0/Auth0.swift/assets/5055789/3f7b0a70-c36c-46bf-9441-29f98724204a) + +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:YOUR_AUTH0_DOMAIN ``` -> 💡 If you're opening the `Info.plist` file in Xcode and it is not being shown in this format, you can **Right Click** on `Info.plist` in the Xcode [project navigator](https://developer.apple.com/documentation/bundleresources/information_property_list/managing_your_app_s_information_property_list) and then select **Open As > Source Code**. +
+ Example + +If your Auth0 Domain were `example.us.auth0.com`, then this value would be: + +```text +webcredentials:example.us.auth0.com +``` +
+ +If you have a [custom domain](https://auth0.com/docs/customize/custom-domains), replace `YOUR_AUTH0_DOMAIN` with your custom domain. + +> ⚠️ 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 application. #### 🌐 Web @@ -325,7 +338,7 @@ For other comprehensive examples, see the [EXAMPLES.md](EXAMPLES.md) document. ### iOS SSO Alert Box -![ios-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 authentication on iOS. @@ -395,18 +408,16 @@ To provide feedback or report a bug, please [raise an issue on our issue tracker Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/responsible-disclosure-policy) details the procedure for disclosing security issues. -## What is Auth0? +---

- + Auth0 Logo

-

- Auth0 is an easy-to-implement, adaptable authentication and authorization platform. To learn more checkout Why Auth0? -

-

- This project is licensed under the Apache 2.0 license. See the LICENSE file for more info. -

+ +

Auth0 is an easy-to-implement, adaptable authentication and authorization platform. To learn more check out Why Auth0?

+ +

This project is licensed under the MIT license. See the LICENSE file for more info.

diff --git a/auth0_flutter_platform_interface/README.md b/auth0_flutter_platform_interface/README.md index b932016c..82a18e1e 100644 --- a/auth0_flutter_platform_interface/README.md +++ b/auth0_flutter_platform_interface/README.md @@ -14,19 +14,16 @@ For general support or usage questions, use the [Auth0 Community](https://commun **Do not report security vulnerabilities on the public GitHub issue tracker.** The [Responsible Disclosure Program](https://auth0.com/responsible-disclosure-policy) details the procedure for disclosing security issues. -## What is Auth0? +--- -Auth0 helps you to: +

+ + + + Auth0 Logo + +

-- Add authentication with [multiple sources](https://auth0.com/docs/authenticate/identity-providers), either social identity providers such as **Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce** (amongst others), or enterprise identity systems like **Windows Azure AD, Google Apps, Active Directory, ADFS, or any SAML identity provider**. -- Add authentication through more traditional **[username/password databases](https://auth0.com/docs/authenticate/database-connections/custom-db)**. -- Add support for **[linking different user accounts](https://auth0.com/docs/manage-users/user-accounts/user-account-linking)** with the same user. -- Support for generating signed [JSON web tokens](https://auth0.com/docs/secure/tokens/json-web-tokens) to call your APIs and **flow the user identity** securely. -- Analytics of how, when, and where users are logging in. -- Pull data from other sources and add it to the user profile through [JavaScript Actions](https://auth0.com/docs/customize/actions). +

Auth0 is an easy-to-implement, adaptable authentication and authorization platform. To learn more check out Why Auth0?

-**Why Auth0?** Because you should save time, be happy, and focus on what really matters: building your product. - -## License - -This project is licensed under Apache License 2.0. See the [LICENSE](LICENSE) file for more information. +

This project is licensed under the MIT license. See the LICENSE file for more info.

From de15e2c9899a8247b3bffaa45043b6f6ba804b22 Mon Sep 17 00:00:00 2001 From: Rita Zerrizuela Date: Wed, 13 Mar 2024 23:32:50 +0000 Subject: [PATCH 2/8] Update code snippets --- auth0_flutter/EXAMPLES.md | 4 +++- auth0_flutter/README.md | 5 ++++- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/auth0_flutter/EXAMPLES.md b/auth0_flutter/EXAMPLES.md index 7dc413a2..eaa523f7 100644 --- a/auth0_flutter/EXAMPLES.md +++ b/auth0_flutter/EXAMPLES.md @@ -61,7 +61,9 @@ Call the `logout()` method in the `onPressed` callback of your **Logout** button If you're using your own credentials storage, make sure to delete the credentials afterward. ```dart -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); ``` diff --git a/auth0_flutter/README.md b/auth0_flutter/README.md index c0980684..a5e81dac 100644 --- a/auth0_flutter/README.md +++ b/auth0_flutter/README.md @@ -262,7 +262,10 @@ Finally, in your `index.html` add the following `