docs: Adds quickstart doc for flutter windows SDK

main/config/navigation/quickstarts.json

@@ -48,6 +48,7 @@
         "docs/quickstart/native/react-native/index",
         "docs/quickstart/native/react-native-expo/index",
         "docs/quickstart/native/flutter/index",
+        "docs/quickstart/native/flutter-windows/index",
         "docs/quickstart/native/net-android-ios/index",
         "docs/quickstart/native/maui/index",
         "docs/quickstart/native/ionic-angular/index",

main/docs/quickstart/native/flutter-windows/index.mdx

@@ -0,0 +1,308 @@
+---
+title: Add Login to Your Flutter Windows Application
+sidebarTitle: Flutter Windows
+description: This guide demonstrates how to integrate Auth0 with a Flutter Windows desktop application using the Auth0 Flutter SDK (beta).
+mode: wide
+'og:title': 'Auth0 Flutter SDK Quickstarts: Add Login to Your Flutter Windows Application'
+'twitter:title': 'Auth0 Flutter SDK Quickstarts: Add Login to Your Flutter Windows Application'
+---
+
+import {AuthCodeBlock} from "/snippets/AuthCodeBlock.jsx";
+
+export const envSnippet = `AUTH0_DOMAIN={yourDomain}
+AUTH0_CLIENT_ID={yourClientId}`;
+
+<Note>
+**Prerequisites:**
+- Flutter SDK 3.24.0+ and Dart 3.5.0+
+- Windows 10 or newer
+- Visual Studio 2022 with **Desktop development with C++** workload
+- Auth0 account — [sign up free](https://auth0.com/signup)
+
+This feature is in **beta** (`auth0_flutter` 2.1.0-beta.1). The API may change before general availability.
+</Note>
+
+This guide walks you through adding login, logout, and user profile display to a Flutter Windows desktop app using the `auth0_flutter` SDK with OAuth 2.0 Authorization Code Flow + PKCE.
+
+## Get Started
+
+<Steps>
+  <Step title="Create a Flutter Windows project" stepNumber={1}>
+    Create a new Flutter project with Windows platform support.
+
+    ```shellscript
+    flutter create --platforms=windows my_app
+    cd my_app
+    ```
+
+    Verify Windows is available:
+
+    ```shellscript
+    flutter devices
+    ```
+
+    You should see a Windows desktop device listed.
+
+    <Tip>
+      Run `flutter doctor` to verify your environment is set up correctly and Visual Studio 2022 with C++ desktop development is detected.
+    </Tip>
+  </Step>
+
+  <Step title="Install the Auth0 Flutter SDK" stepNumber={2}>
+    Add the beta version of the SDK that includes Windows support:
+
+    ```shellscript
+    flutter pub add auth0_flutter:2.1.0-beta.1
+    flutter pub add flutter_dotenv
+    ```
+
+    Your `pubspec.yaml` should include:
+
+    <Snippet file="quickstart/native/flutter-windows/pubspec.yaml.mdx" />
+
+    <Tip>
+      The Auth0 Flutter SDK requires **Flutter 3.24.0+** and **Dart 3.5.0+**. The Windows platform additionally requires **Visual Studio 2022** with the C++ desktop development workload.
+    </Tip>
+  </Step>
+
+  <Step title="Configure Auth0" stepNumber={3}>
+    Create or configure an Auth0 application with the callback URLs required for Windows desktop authentication.
+
+    <Tabs>
+      <Tab title="Quick Setup">
+        Create a **Native** application in your Auth0 Dashboard with the following settings:
+
+        | Field | Value |
+        |-------|-------|
+        | Allowed Callback URLs | `auth0flutter://callback` |
+        | Allowed Logout URLs | `auth0flutter://callback` |
+
+        Your credentials:
+        - **Domain:** `{yourDomain}`
+        - **Client ID:** `{yourClientId}`
+      </Tab>
+
+      <Tab title="CLI">
+        ```shellscript
+        auth0 apps create \
+          --name "My Flutter Windows App" \
+          --type native \
+          --callbacks "auth0flutter://callback" \
+          --logout-urls "auth0flutter://callback"
+        ```
+      </Tab>
+
+      <Tab title="Dashboard">
+        1. Go to [Auth0 Dashboard](https://manage.auth0.com/) → **Applications > Applications**
+        2. Select **Create Application**
+        3. Name it "My Flutter Windows App" and choose **Native** as the application type
+        4. Go to the **Settings** tab of your new application
+        5. Set **Allowed Callback URLs** to `auth0flutter://callback`
+        6. Set **Allowed Logout URLs** to `auth0flutter://callback`
+        7. Scroll down and click **Save Changes**
+        8. Copy the **Domain** and **Client ID** values from the top of Application Settings
+      </Tab>
+    </Tabs>
+
+    <Info>
+      The `auth0flutter://callback` URL is a custom scheme that routes the browser callback back to your desktop application after authentication completes.
+    </Info>
+  </Step>
+
+  <Step title="Configure environment variables" stepNumber={4}>
+    Create a `.env` file in the root of your project:
+
+    <AuthCodeBlock children={envSnippet} language="shellscript" filename=".env" />
+
+    Add the `.env` file to your Flutter assets in `pubspec.yaml`:
+
+    <Snippet file="quickstart/native/flutter-windows/pubspec-assets.yaml.mdx" />
+
+    <Warning>
+      Never commit your `.env` file to version control. Add it to `.gitignore`.
+    </Warning>
+  </Step>
+
+  <Step title="Configure the Windows runner" stepNumber={5}>
+    The Windows authentication flow requires callback plumbing in your app's runner. The Flutter plugin does not automatically receive protocol-scheme activations from the OS — you must add single-instance enforcement and URI forwarding.
+
+    Replace the contents of `windows/runner/main.cpp`:
+
+    <Snippet file="quickstart/native/flutter-windows/main.cpp.mdx" />
+
+    This code:
+    - Enforces single-instance via a Windows mutex
+    - Captures `auth0flutter://callback` URIs passed as command-line arguments
+    - Forwards URIs from secondary launches to the running instance via a named pipe
+    - Sets the `PLUGIN_STARTUP_URL` environment variable for the Auth0 plugin to read
+  </Step>
+
+  <Step title="Register the custom URL scheme" stepNumber={6}>
+    Register `auth0flutter` as a custom URL scheme so Windows routes callback URIs to your app.
+
+    Create a file `windows/url_scheme.reg`:
+
+    <Snippet file="quickstart/native/flutter-windows/url_scheme.reg.mdx" />
+
+    Replace `C:\path\to\your\app.exe` with the actual path to your built executable. During development this is typically:
+
+    ```text
+    build\windows\x64\runner\Debug\my_app.exe
+    ```
+
+    Double-click the `.reg` file to import it into the Windows Registry.
+
+    <Info>
+      For production distribution, register the custom URL scheme programmatically in your app's installer (MSIX, Inno Setup, etc.) rather than relying on a `.reg` file.
+    </Info>
+
+    **Verify the scheme works:**
+
+    Open Command Prompt and run:
+
+    ```shellscript
+    start auth0flutter://test
+    ```
+
+    Your app should launch (or come to the foreground if already running).
+  </Step>
+
+  <Step title="Implement login and logout" stepNumber={7}>
+    Create `lib/auth_service.dart` to handle Windows authentication:
+
+    <Snippet file="quickstart/native/flutter-windows/auth_service.dart.mdx" />
+
+    <Info>
+      The Auth0 Flutter Windows SDK does not currently support credential management. You must manually store credentials if you need sessions to persist across app restarts.
+    </Info>
+  </Step>
+
+  <Step title="Show user profile information" stepNumber={8}>
+    Create the main app UI in `lib/main.dart`:
+
+    <Snippet file="quickstart/native/flutter-windows/main.dart.mdx" />
+  </Step>
+
+  <Step title="Run your application" stepNumber={9}>
+    Build and run the app:
+
+    ```shellscript
+    flutter run -d windows
+    ```
+
+    **Expected flow:**
+
+    1. App launches with a **Log In** button
+    2. Click **Log In** → your system browser opens the Auth0 Universal Login page
+    3. Complete authentication in the browser
+    4. Browser redirects to `auth0flutter://callback` → your app comes to the foreground
+    5. User's name, email, and profile picture are displayed
+
+    <Warning>
+      Ensure the custom URL scheme is registered (Step 6) before testing. Without it, the browser callback cannot reach your application.
+    </Warning>
+  </Step>
+</Steps>
+
+<Check>
+  **Checkpoint**
+
+  You should now have a fully functional Auth0 login experience in your Flutter Windows application. The app opens the system browser for Auth0 Universal Login, receives the callback via the custom URL scheme, and displays the authenticated user's profile.
+</Check>
+
+---
+
+## Troubleshooting & Advanced Usage
+
+<Accordion title="Common Issues & Solutions">
+  ### Browser opens but app doesn't receive callback
+
+  **Symptom**: Auth0 login succeeds in browser but the app never receives the credentials.
+
+  **Fix:**
+  1. Open Registry Editor → `HKEY_CURRENT_USER\Software\Classes\auth0flutter\shell\open\command` and confirm the path to your `.exe`
+  2. Test with `start auth0flutter://test` in Command Prompt — your app should launch
+  3. Ensure `windows/runner/main.cpp` includes the pipe server and mutex code
+  4. Check that no stale instances are running in Task Manager
+  5. Rebuild completely: `flutter clean && flutter run -d windows`
+
+  ### Authentication times out after 5 minutes
+
+  **Symptom**: Login appears to hang and eventually fails.
+
+  **Fix:** The app never received the callback URI. Verify:
+  1. The registry entry points to the correct executable path
+  2. The mutex name `auth0flutter_single_instance_mutex` is consistent in `main.cpp`
+  3. No firewall or antivirus is blocking the named pipe
+  4. Kill all stale instances and rebuild
+
+  ### Second app instance launches instead of forwarding URI
+
+  **Symptom**: A new window opens instead of the existing app receiving the callback.
+
+  **Fix:**
+  1. Kill all running instances in Task Manager
+  2. Ensure the mutex name is consistent in `main.cpp`
+  3. Rebuild: `flutter clean && flutter run -d windows`
+
+  ### WindowsWebAuthentication not found
+
+  **Symptom**: Compilation error referencing `windowsWebAuthentication`.
+
+  **Fix:** Ensure your `pubspec.yaml` specifies the beta version:
+  ```yaml
+  dependencies:
+    auth0_flutter: 2.1.0-beta.1
+  ```
+  Run `flutter pub get` to update.
+
+  ### Callback URL mismatch error
+
+  **Symptom**: Error "redirect_uri_mismatch" from Auth0.
+
+  **Fix:**
+  1. Verify **Allowed Callback URLs** in [Auth0 Dashboard](https://manage.auth0.com/) → Application Settings is exactly `auth0flutter://callback`
+  2. Ensure the `appCustomURL` parameter in your code matches: `'auth0flutter://callback'`
+  3. Check for trailing slashes or whitespace
+</Accordion>
+
+<Accordion title="Using an Intermediary Server">
+  When Auth0 redirects directly to a custom scheme, the browser may show a prompt or leave a blank tab. For a smoother experience, use an intermediary HTTPS server:
+
+  1. Set up a server endpoint (e.g., `https://your-app.example.com/callback`) that redirects to `auth0flutter://callback?code=...&state=...`
+  2. In [Auth0 Dashboard](https://manage.auth0.com/) → Application Settings, set **Allowed Callback URLs** to `https://your-app.example.com/callback`
+  3. Pass both URLs to the login method:
+
+  ```dart
+  final result = await auth0.windowsWebAuthentication().login(
+    appCustomURL: 'auth0flutter://callback',
+    redirectUrl: 'https://your-app.example.com/callback',
+  );
+  ```
+
+  The server page can display "Redirecting..." and close itself for a cleaner experience.
+</Accordion>
+
+<Accordion title="Custom Scopes and Audience">
+  Request additional scopes or an API audience:
+
+  ```dart
+  final result = await auth0.windowsWebAuthentication().login(
+    appCustomURL: 'auth0flutter://callback',
+    scopes: {'openid', 'profile', 'email', 'read:messages'},
+    audience: 'https://your-api.example.com',
+  );
+  ```
+
+  Configure the API in [Auth0 Dashboard](https://manage.auth0.com/) → **Applications > APIs** before using the `audience` parameter.
+</Accordion>
+
+---
+
+## Next Steps
+
+- [Auth0 Flutter SDK on GitHub](https://github.com/auth0/auth0-flutter) — source code and issue tracker
+- [Auth0 Flutter SDK on pub.dev](https://pub.dev/packages/auth0_flutter) — API reference
+- [Flutter quickstart (Android, iOS, macOS, Web)](https://auth0.com/docs/quickstart/native/flutter) — other platform guides
+- [Token Storage Best Practices](https://auth0.com/docs/secure/tokens/token-storage) — secure credential management
+- [Auth0 Universal Login](https://auth0.com/docs/authenticate/login/auth0-universal-login) — customize the login experience