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 の Authorization Code Flow + 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 プラットフォームでは、C++ によるデスクトップ開発ワークロードを含む Visual Studio 2022 も必要です。

3. Auth0 を設定

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

   クイックセットアップ

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

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

   認証情報:

   • ドメイン: {yourDomain}
   • クライアントID: {yourClientId}

   CLI

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

   Dashboard

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

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

4. 環境変数を設定する

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

   pubspec.yaml で .env ファイルを Flutter のアセットとして追加します。

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

5. Windows ランナーを設定する

   Windows 認証フローでは、アプリの runner で callback を処理する仕組みが必要です。Flutter plugin は、プロトコルスキームのアクティベーションを OS から自動的に受け取らないため、シングルインスタンス化の制御と URI の転送を追加する必要があります。

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

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

   • Windows mutex を使用してシングルインスタンスを強制します。
   • コマンドライン引数として渡された auth0flutter://callback URI を取得します。
   • セカンダリ起動からの URI を、名前付きパイプ経由で実行中のインスタンスに転送します。
   • Auth0 plugin が読み取る 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. ログインとログアウトを実装する

   Windows 認証を処理するため、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 ログインに成功するが、アプリが認証情報をまったく受信しない。

対処法:

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 分後にタイムアウトする

症状: ログインが途中で止まったように見え、最終的に失敗する。

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

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

​

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

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

対処法:

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

​

WindowsWebAuthentication が見つからない

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

対処法: pubspec.yaml でベータ版が指定されていることを確認します:

dependencies:
  auth0_flutter: 2.1.0-beta.1

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

​

コールバック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=... にリダイレクトするサーバー エンドポイント (例: https://your-app.example.com/callback) を設定します。
2. Auth0 Dashboard → Application Settings で、Allowed Callback URLs を https://your-app.example.com/callback に設定します。
3. 両方の URL をログイン メソッドに渡します:

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

よりすっきりした動作にするために、サーバー ページでは “Redirecting…” を表示して自身を閉じることもできます。

カスタム スコープとオーディエンス

追加のスコープまたは API のオーディエンスをリクエストします:

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

audience パラメーターを使用する前に、Auth0 Dashboard → アプリケーション > APIs で API を設定してください。

---

​

次のステップ

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