Skip to content

Commit

Permalink
Update the Flutter QS to feature HTTPS redirect URLs on iOS/macOS [SD…
Browse files Browse the repository at this point in the history 
…K-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
  • Loading branch information
@Widcket
Widcket authored Mar 20, 2024
1 parent ae528b7 commit d239c76
Show file tree
Hide file tree
Showing 8 changed files with 174 additions and 90 deletions.
86 changes: 78 additions & 8 deletions articles/quickstart/native/flutter/01-login.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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;
Expand Down
50 changes: 28 additions & 22 deletions articles/quickstart/native/flutter/_configure_urls_interactive.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
40 changes: 17 additions & 23 deletions articles/quickstart/native/flutter/download.md
View file
Original file line number Diff line number Diff line change
@@ -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`.
8 changes: 6 additions & 2 deletions articles/quickstart/native/flutter/files/main.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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;
Expand Down
Loading

0 comments on commit d239c76

Please sign in to comment.