Flutter Windows アプリケーションにログイン機能を追加する

このガイドでは、Auth0 Flutter SDK（ベータ版）を使用して、Flutter Windows デスクトップアプリケーションに Auth0 を統合する方法を説明します。

前提条件:

• Flutter SDK 3.24.0+ と Dart 3.5.0+。
• Windows 10 以降。
• Desktop development with C++ ワークロードを含む Visual Studio 2022。
• Auth0 アカウント — 無料でサインアップ。

この機能はベータ版です (auth0_flutter 2.1.0-beta.1) 。API は一般提供前に変更される可能性があります。

このガイドでは、OAuth 2.0 の認可コードフロー + PKCEを使用して、auth0_flutter SDK で Flutter の Windows デスクトップアプリにログイン、ログアウト、ユーザープロファイルの表示を追加する方法を説明します。

​

はじめる

1. Flutter の Windows プロジェクトを作成する

   Windows プラットフォーム対応の新しい Flutter プロジェクトを作成します。

   flutter create --platforms=windows my_app
   cd my_app
   

   Windows が利用可能か確認します:

   flutter devices
   

   Windows デスクトップ デバイスが一覧に表示されるはずです。

   flutter doctor を実行して、環境が正しく設定されており、C++ によるデスクトップ開発を含む Visual Studio 2022 が検出されていることを確認します。

2. Auth0 Flutter SDKをインストールする

   Windows をサポートする SDK のベータ版を追加します:

   flutter pub add auth0_flutter:2.1.0-beta.1
   flutter pub add flutter_dotenv
   

   pubspec.yaml には次の内容を含めてください。

   Auth0 Flutter SDK には Flutter 3.24.0+ と Dart 3.5.0+ が必要です。また、Windows プラットフォームでは、Visual Studio 2022 に加えて C++ によるデスクトップ開発ワークロードも必要です。

3. Auth0を設定する

   Windows デスクトップでの認証に必要なコールバック URL を設定して、Auth0 アプリケーションを作成または設定します。

   クイック設定

   Auth0 Dashboard で、次の設定を使用して Native アプリケーションを作成します。

   項目	値
   Allowed Callback URLs	auth0flutter://callback
   Allowed Logout URLs	auth0flutter://callback

   資格情報:

   • Domain: {yourDomain}
   • Client ID: {yourClientId}

   CLI

   auth0 apps create \
     --name "My Flutter Windows App" \
     --type native \
     --callbacks "auth0flutter://callback" \
     --logout-urls "auth0flutter://callback"
   

   Auth0 Dashboard

   1. Auth0 Dashboard に移動し、アプリケーション > アプリケーション を選択します。
   2. Create Application を選択します。
   3. 名前を “My Flutter Windows App” にし、アプリケーションの種類として Native を選択します。
   4. 新しいアプリケーションの 設定 タブを開きます。
   5. Allowed Callback URLs に auth0flutter://callback を設定します。
   6. Allowed Logout URLs に auth0flutter://callback を設定します。
   7. 下にスクロールして 変更を保存 をクリックします。
   8. Application Settings の上部にある Domain と Client ID の値をコピーします。

   auth0flutter://callback URL は、認証の完了後にブラウザーのコールバックをデスクトップアプリケーションへ戻すためのカスタムスキームです。

4. 環境変数を設定する

   プロジェクトのルートに .env ファイルを作成します。

   pubspec.yaml で .env ファイルを Flutter のassetsに追加します。

   .env ファイルは絶対にバージョン管理にコミットしないでください。.gitignore に追加してください。

5. Windows runner を設定する

   Windows Authenticationフローでは、アプリの runner でコールバックを受け渡す処理が必要です。Flutterプラグインは、OS からのプロトコルスキームによる起動を自動では受け取らないため、単一インスタンスの制御と URI の転送を追加する必要があります。

   windows/runner/main.cpp の内容を次のように置き換えます。

   このコードでは、次のことを行います。

   • Windows の mutex を使って単一インスタンスを強制します。
   • コマンドライン引数として渡された auth0flutter://callback URI を取得します。
   • 2 回目以降の起動で渡された URI を、名前付きパイプ経由で実行中のインスタンスに転送します。
   • Auth0プラグインが読み取れるように、PLUGIN_STARTUP_URL 環境変数を設定します。
6. カスタムURLスキームを登録する

   Windows でコールバック URI がアプリにルーティングされるよう、auth0flutter をカスタム URL スキームとして登録します。

   windows/url_scheme.reg ファイルを作成します。

   C:\path\to\your\app.exe は、ビルドした実際の実行可能ファイルのパスに置き換えてください。開発中は通常、次の場所になります。

   build\windows\x64\runner\Debug\my_app.exe
   

   .reg ファイルをダブルクリックして、Windows レジストリにインポートします。

   本番環境向けに配布する場合は、.reg ファイルに頼るのではなく、アプリのインストーラー (MSIX、Inno Setup など) でカスタム URL スキームをプログラムから登録してください。

   スキームが正しく機能することを確認します。

   コマンド プロンプトを開き、次を実行します。

   start auth0flutter://test
   

   アプリが起動するか、すでに起動している場合は前面に表示されます。

7. Implementでのログインとログアウト

   Windows Authentication を処理する lib/auth_service.dart を作成します。

   Auth0 Flutter Windows SDK は現在、資格情報の管理をサポートしていません。アプリの再起動後もセッションを維持する必要がある場合は、資格情報を手動で保存する必要があります。

8. ユーザープロファイル情報を表示

   lib/main.dart にメイン アプリの UI を作成します:

9. アプリケーションを起動する

   アプリをビルドして実行します：

   flutter run -d windows
   

   想定されるフロー:

   1. アプリが起動し、ログイン ボタンが表示されます。
   2. ログイン を選択します。システムブラウザーで Auth0 Universal Login ページが開きます。
   3. ブラウザーで認証を完了します。
   4. ブラウザーが auth0flutter://callback にリダイレクトし、アプリがフォアグラウンドに戻ります。
   5. ユーザーの名前、メールアドレス、プロフィール画像が表示されます。

   テストの前に、カスタム URL スキームが登録されていること (手順 6) を確認してください。登録されていないと、ブラウザーのコールバックがアプリケーションに戻りません。

チェックポイント

これで、Flutter Windows アプリケーションで Auth0 のログイン機能が完全に動作するようになっているはずです。アプリは Auth0 Universal Login のためにシステムブラウザーを開き、カスタム URL スキーム経由でコールバックを受け取り、認証されたユーザーのプロファイルを表示します。

---

​

トラブルシューティングと高度な使い方

よくある問題と解決策

​

ブラウザーは開くが、アプリがコールバックを受信しない

症状: ブラウザーでの Auth0 login は成功するものの、アプリが資格情報を受け取りません。

対処法:

1. レジストリ エディターを開き、HKEY_CURRENT_USER\Software\Classes\auth0flutter\shell\open\command で .exe へのパスが正しいことを確認します。
2. コマンド プロンプトで start auth0flutter://test を実行してテストします。アプリが起動するはずです。
3. windows/runner/main.cpp にパイプ サーバーとミューテックスのコードが含まれていることを確認します。
4. タスク マネージャーで古いインスタンスが残っていないことを確認します。
5. flutter clean && flutter run -d windows を実行して、完全に再ビルドします。

​

5 分後に認証がタイムアウトする

症状: Login が止まったように見え、最終的に失敗します。

対処法: アプリがコールバック URI を受信できていません。次を確認してください:

1. レジストリ エントリが正しい実行ファイル パスを指していること。
2. main.cpp 内のミューテックス名 auth0flutter_single_instance_mutex が統一されていること。
3. ファイアウォールまたはアンチウイルスが名前付きパイプをブロックしていないこと。
4. 古いインスタンスをすべて終了し、再ビルドすること。

​

URI を転送せずに 2 つ目のアプリ インスタンスが起動する

症状: 既存のアプリがコールバックを受信する代わりに、新しいウィンドウが開きます。

対処法:

1. タスク マネージャーで実行中のインスタンスをすべて終了します。
2. main.cpp 内のミューテックス名が統一されていることを確認します。
3. 次のコマンドで再ビルドします: flutter clean && flutter run -d windows。

​

WindowsWebAuthentication が見つからない

症状: windowsWebAuthentication を参照するコンパイル エラーが発生します。

対処法: pubspec.yaml で Beta 版が指定されていることを確認してください:

dependencies:
  auth0_flutter: 2.1.0-beta.1

更新するには flutter pub get を実行します。

​

Callback URL の不一致エラー

症状: Auth0 から “redirect_uri_mismatch” エラーが返されます。

対処法:

1. Auth0 Dashboard → Application Settings の Allowed Callback URLs が正確に auth0flutter://callback になっていることを確認します。
2. コード内の appCustomURL パラメーターが 'auth0flutter://callback' と一致していることを確認します。
3. 末尾のスラッシュや空白が入っていないか確認します。

中継サーバーを使用する

Auth0 がカスタム スキームに直接リダイレクトすると、ブラウザーにプロンプトが表示されたり、空白のタブが残ったりすることがあります。よりスムーズに利用するには、中継用の HTTPS サーバーを使用してください:

1. auth0flutter://callback?code=...&state=... にリダイレクトするサーバー endpoint (例: https://your-app.example.com/callback) を設定します。
2. Auth0 Dashboard → Application Settings で、Allowed Callback URLs を https://your-app.example.com/callback に設定します。
3. login メソッドに両方の URL を渡します:

final result = await auth0.windowsWebAuthentication().login(
  appCustomURL: 'auth0flutter://callback',
  redirectUrl: 'https://your-app.example.com/callback',
);

サーバー ページには “Redirecting…” と表示し、自動的に閉じるようにすると、よりすっきりした体験になります。

カスタム スコープと audience

追加のスコープや API の audience をリクエストします:

final result = await auth0.windowsWebAuthentication().login(
  appCustomURL: 'auth0flutter://callback',
  scopes: {'openid', 'profile', 'email', 'read:messages'},
  audience: 'https://your-api.example.com',
);

audience パラメーターを使用する前に、Auth0 Dashboard → Applications > APIs で API を設定してください。

---

​

次のステップ

• Auth0 Flutter SDK on GitHub — ソースコードと Issue トラッカー。
• Auth0 Flutter SDK on pub.dev — API リファレンス。
• Flutter quickstart (Android, iOS, macOS, Web) — 他のプラットフォーム向けガイド。
• Token Storage Best Practices — 認証情報の安全な管理。
• Auth0 Universal Login — ログイン体験をカスタマイズ。