Flutter アプリにログインを追加

このガイドでは、Auth0 Flutter SDK を使用して、あらゆる Flutter アプリに Auth0 を統合する方法を説明します。

AI を使って Auth0 を統合

Claude Code、Cursor、GitHub Copilot などの AI コーディングアシスタントを使えば、agent skills を利用して、数分で Auth0 認証を自動的に追加できます。

インストール:

npx skills add auth0/agent-skills --skill auth0

次に、AI アシスタントに以下のように依頼します:

Add Auth0 authentication to my Flutter app

AI アシスタントが、Auth0 アプリケーションの作成、資格情報の取得、auth0_flutter SDK 依存関係の追加、Android と iOS のコールバック URL の設定に加え、安全な資格情報ストレージを使用した Web Auth のログイン/ログアウト実装まで自動的に行います。agent skills の完全なドキュメント →

このガイドでは、Auth0 Flutter SDK を使用して Flutter アプリケーションに Auth0 を統合する方法を説明します。Android、iOS、macOS プラットフォーム向けの設定を扱います。

Auth0 Flutter SDK は Web と Windows (ベータ版) にも対応しています。これらのプラットフォーム向けには、専用の Quickstart があります。

• Flutter Web Quickstart — ブラウザー向け Flutter アプリ用
• Flutter Windows Quickstart — Windows 上で動作する Flutter デスクトップアプリ向け (ベータ版)

​

はじめに

1. 新しいFlutterプロジェクトを作成

   このQuickstart向けに、新しいFlutterプロジェクトを作成します。

   ターミナルで:

   1. ワークスペースのディレクトリに移動します
   2. 次を実行します: flutter create auth0_flutter_sample
   3. プロジェクトのディレクトリに移動します: cd auth0_flutter_sample
   4. IDEで開きます:
      • VS Code: code .
      • Android Studio: open -a "Android Studio" .

   # 新しいFlutterプロジェクトを作成する
   flutter create auth0_flutter_sample
   
   # プロジェクトディレクトリに移動する
   cd auth0_flutter_sample
   
   # VS Codeで開く
   code .
   

   これにより、最新のプロジェクト構成を採用したモダンな Flutter アプリが作成されます。flutter doctor を実行して、環境が正しくセットアップされていることを確認してください。

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

   Flutter CLI を使用して、Auth0 Flutter SDK をプロジェクトに追加します。

   flutter pub add auth0_flutter
   

   これにより、auth0_flutter が pubspec.yaml の依存関係に追加されます。

   pubspec.yaml

   dependencies:
     auth0_flutter: ^2.0.0-beta.1
   

   Auth0 Flutter SDK では、Flutter 3.24.0+ と Dart 3.5.0+ が必要です。flutter doctor を実行して、お使いの環境がこれらの要件を満たしていることを確認してください。

3. Auth0 Appを設定する

   次に、Auth0 テナントで新しいアプリを作成し、コールバック URL を設定します。

   1. Auth0 Dashboard に移動します
   2. アプリケーション > アプリケーション > Create Application をクリックします
   3. ポップアップでアプリ名を入力し、アプリの種類として Native を選択して Create をクリックします
   4. アプリケーションの詳細ページで 設定 タブに切り替えます
   5. Domain と Client ID の値を控えておきます。これらは後で使用します

   設定 タブで、対象のプラットフォームに応じて以下の URL を設定します。

   Allowed Callback URLs:

   Android

   https://{yourDomain}/android/{yourPackageName}/callback
   

   iOS

   https://{yourDomain}/ios/{yourBundleIdentifier}/callback,
   {yourBundleIdentifier}://{yourDomain}/ios/{yourBundleIdentifier}/callback
   

   macOS

   https://{yourDomain}/macos/{yourBundleIdentifier}/callback,
   {yourBundleIdentifier}://{yourDomain}/macos/{yourBundleIdentifier}/callback
   

   Allowed Logout URLs:

   上記のコールバック設定で使用したものと同じ URL を Allowed Logout URLs フィールドに追加します。

   Allowed Callback URLs は、認証後にユーザーを安全にアプリケーションへ戻すための重要なセキュリティ対策です。一致する URL がない場合、ログインプロセスは失敗します。

   Allowed Logout URLs は、サインアウト後にシームレスなユーザー体験を提供するために不可欠です。一致する URL がない場合、ログアウト後にユーザーはアプリケーションへリダイレクトされません。

   たとえば、Auth0 ドメインが example.us.auth0.com で、Android のパッケージ名が com.example.myapp の場合、Android のコールバック URL は次のようになります: https://example.us.auth0.com/android/com.example.myapp/callback

   重要: コールバック URL 内のパッケージ名 (Android) またはバンドル ID (iOS/macOS) が、実際のアプリ識別子と一致していることを確認してください。認証に失敗する場合は、これらの値が完全に一致しているか確認してください。

4. アプリケーションを設定する

   認証フローを有効にするには、プラットフォームごとの設定が必要です。対象とする各プラットフォームについて、以下の手順に従ってください。

   Android

   android/app/build.gradle ファイルを開き、android > defaultConfig 内に次の manifest placeholders を追加します。

   android/app/build.gradle

   android {
       // ...
       defaultConfig {
           // Add the following line
           manifestPlaceholders += [auth0Domain: "{yourDomain}", auth0Scheme: "https"]
       }
       // ...
   }
   

   {yourDomain} は、ご利用の Auth0 ドメイン (例: example.us.auth0.com) に置き換えてください。

   https スキーム

   コールバック URL に https スキームを使用するには、ご利用のアプリケーションで Android app links を設定してください。

   生体認証を使用する場合 (任意) :

   生体認証を使用する予定がある場合は、MainActivity.kt を更新し、FlutterFragmentActivity を継承するようにしてください。

   android/app/src/main/kotlin/.../MainActivity.kt

   import io.flutter.embedding.android.FlutterFragmentActivity
   
   class MainActivity: FlutterFragmentActivity() {
   }
   

   iOS

   iOS 17.4+ で Universal Links (HTTPS コールバック URL) を使用するには、Associated Domain を設定します。

   1. Xcode でアプリを開きます: open ios/Runner.xcworkspace
   2. Runner ターゲットを選択し、Signing & Capabilities に移動します
   3. + Capability をクリックし、Associated Domains を追加します
   4. 次のエントリを追加します: webcredentials:{yourDomain}
   5. Auth0 Dashboard で Settings > Advanced Settings > Device Settings に移動します
   6. iOS セクションで、Team ID と App ID (バンドル識別子) を設定します

   Universal Links の設定は任意です。Universal Links のサポートが不要な場合は、この手順はスキップしてください。SDK は自動的にカスタム URL スキームにフォールバックします。

   macOS

   iOS と同じ手順に従いますが、代わりに macos/Runner.xcworkspace を開いてください。

   Android: auth0Domain の値がご利用の Auth0 ドメインと完全に一致していることを確認してください。認証に失敗する場合は、この値が Auth0 Dashboard に表示されているドメインと同一か確認してください。

   iOS/macOS: Universal Links を利用するには、有料の Apple Developer アカウントと iOS 17.4+/macOS 14.4+ が必要です。これより古いバージョンでは、SDK は自動的にカスタム URL スキームにフォールバックします。

5. Implement Login とロゴアウト

   Universal Login は、アプリケーションに認証を設定する最も簡単な方法です。最適なユーザー体験、高いセキュリティ、そして最も充実した機能を利用できるため、これを使用することをお勧めします。

   ログインを実装する:

   Auth0 Flutter SDK をインポートし、Auth0 インスタンスを作成します。

   lib/auth_service.dart

   import 'package:auth0_flutter/auth0_flutter.dart';
   
   class AuthService {
     final auth0 = Auth0('{yourDomain}', '{yourClientId}');
   
     Future<Credentials> login() async {
       final credentials = await auth0.webAuthentication().login(useHTTPS: true);
   
       // アクセストークン -> credentials.accessToken
       // ID トークン -> credentials.idToken
       // ユーザープロファイル -> credentials.user
   
       return credentials;
     }
   }
   

   Implement ログアウト:

   lib/auth_service.dart

   Future<void> logout() async {
     await auth0.webAuthentication().logout(useHTTPS: true);
   
     // ユーザーはログアウトしました
     // 資格情報はセキュアストレージから削除されました
   }
   

   iOS/macOS: useHTTPS: true パラメータを指定すると、セキュリティ強化のために、iOS 17.4+ および macOS 14.4+ で Universal Links が有効になります。

   Android: カスタムスキームを使用している場合は、このスキームを login メソッドに渡してください。これにより、SDK はログインページへの遷移と、そこからの復帰を正しく処理できます。

   await auth0.webAuthentication(scheme: 'YOUR CUSTOM SCHEME').login();
   
6. ユーザープロファイル情報の表示

   ユーザープロファイルは、ユーザーのログイン時に自動的に取得されます。Credentials オブジェクトには user プロパティがあり、ID トークンをデコードして取得したすべてのユーザープロファイル情報が格納されます。

   lib/profile_screen.dart

   void displayUserProfile(Credentials credentials) {
     final user = credentials.user;
     
     print('User ID: ${user.sub}');
     print('Email: ${user.email}');
     print('Name: ${user.name}');
     print('Picture: ${user.pictureUrl}');
     print('Nickname: ${user.nickname}');
   }
   

   特定のユーザープロファイル項目にアクセスするには、ログイン時に適切なスコープをリクエストしてください。デフォルトのスコープは openid、profile、email、offline_access です。

7. アプリを起動する

   Flutter アプリケーションをビルドして実行します。

   ターミナルで:

   # 利用可能なデバイスを一覧表示する
   flutter devices
   
   # Androidで実行する
   flutter run -d android
   
   # iOSシミュレーターで実行する
   flutter run -d ios
   
   # macOSで実行する
   flutter run -d macos
   

   想定されるフロー:

   1. アプリがログインUIを表示して起動する
   2. ユーザーがログインをタップする → ブラウザーまたはカスタムタブで Auth0 Universal Login が開く
   3. ユーザーが認証を完了する
   4. ブラウザーからアプリにリダイレクトされる
   5. ユーザーは認証され、資格情報が保存される

チェックポイント

これで、Flutterアプリケーションで Auth0 によるログインを問題なく利用できるようになりました。このアプリは、安全なブラウザベースの認証を使用し、セッションを維持するための資格情報を自動的に保存します。

---

​

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

よくある問題と解決策

​

コールバックURLの不一致

症状: “redirect_uri_mismatch” エラーが表示される、または認証が失敗しても何も表示されません。

解決策:

1. Auth0 Dashboard の Allowed Callback URLs がアプリの設定と完全に一致しているか確認する
2. スキーム (https:// と http://) を確認する
3. パッケージ名 (Android) またはバンドル識別子 (iOS/macOS) が正しいことを確認する
4. 末尾のスラッシュが付いていないか確認する

​

Android: Chrome Custom Tab が開かない

症状: login() を呼び出しても何も起こりません。

対処法:

1. build.gradle で manifestPlaceholders が正しく設定されていることを確認する
2. AndroidManifest.xml にインターネット権限があることを確認する:
   <uses-permission android:name="android.permission.INTERNET" />
   
3. Chrome または別のブラウザーが端末にインストールされていることを確認する

​

iOS: 「App で開く」アラート

症状: アプリで開くかどうかを確認するアラートが表示されます。

対処法: これは ASWebAuthenticationSession の想定どおりの動作です。表示させないようにするには:

• Universal Links を使用する (iOS 17.4 以降と有料の Apple Developer アカウントが必要)
• または useEphemeralSession: true を設定する (SSO を無効化) :

await auth0.webAuthentication().login(
  useHTTPS: true,
  useEphemeralSession: true,
);

​

ユーザーによって認証がキャンセルされた

エラー処理で適切に対応します:

try {
  final credentials = await auth0.webAuthentication().login(useHTTPS: true);
  // ログイン成功時の処理
} on WebAuthenticationException catch (e) {
  if (e.code == 'USER_CANCELLED') {
    showMessage('Login was cancelled');
  } else {
    showMessage('Login failed: ${e.message}');
  }
}

資格情報の管理

Auth0 Flutter SDK には、ユーザーの資格情報を安全に保存する組み込みの Credentials Manager が含まれています。モバイルプラットフォームでは、資格情報は暗号化され、プラットフォームの安全なストレージ (iOS/macOS では Keychain、Android では暗号化された SharedPreferences) に保存されます。

​

保存済みの資格情報を確認する

ユーザーにログインを求める前に、有効な資格情報がすでにあるか確認します:

lib/auth_service.dart

Future<bool> checkAuthentication() async {
  return await auth0.credentialsManager.hasValidCredentials();
}

​

保存済みの資格情報を取得する

アクセストークンやユーザー情報にアクセスするために資格情報を取得します。Credentials Manager は、可能であれば期限切れのトークンを自動的に更新します:

lib/auth_service.dart

Future<Credentials> getCredentials() async {
  return await auth0.credentialsManager.credentials();
}

ログイン後に資格情報を手動で保存する必要はありません。SDK が自動的に処理します。また、トークンを手動で更新する必要もありません。必要に応じて Credentials Manager が更新します。

エラー処理

適切に認証エラーを処理して、優れたユーザー体験を提供しましょう。

lib/auth_service.dart

import 'package:auth0_flutter/auth0_flutter.dart';

Future<void> login() async {
  try {
    final credentials = await auth0.webAuthentication().login(useHTTPS: true);
    // ログイン成功時の処理
  } on WebAuthenticationException catch (e) {
    if (e.code == 'USER_CANCELLED') {
      // ユーザーがログインをキャンセルした
      print('Login cancelled by user');
    } else {
      // その他のエラーを処理する
      print('Login error: ${e.message}');
    }
  }
}

Future<Credentials> getCredentials() async {
  try {
    return await auth0.credentialsManager.credentials();
  } on CredentialsManagerException catch (e) {
    if (e.isNoCredentialsFound) {
      // 保存された資格情報がないため、ユーザーはログインする必要がある
      throw Exception('Please log in first');
    } else if (e.isTokenRenewFailed) {
      // リフレッシュトークンの有効期限が切れているため、再認証が必要
      return await auth0.webAuthentication().login(useHTTPS: true);
    }
    rethrow;
  }
}

高度な Flutter 連携

​

生体認証による資格情報のセキュリティ強化

モバイルで資格情報へのアクセスに生体認証を実装します。

lib/secure_auth_service.dart

class SecureAuthService {
  final auth0 = Auth0('{yourDomain}', '{yourClientId}');
  
  Future<void> enableBiometrics() async {
    // ローカル認証を有効化（Face ID、Touch ID、指紋）
    await auth0.credentialsManager.enableLocalAuthentication(
      title: 'Authenticate to access your account',
      cancelTitle: 'Cancel',
      fallbackTitle: 'Use passcode',
    );
  }
  
  Future<Credentials> getCredentialsWithBiometrics() async {
    // 以降は生体認証が必要になります
    return await auth0.credentialsManager.credentials();
  }
}

Android: Step 4 の設定どおり、MainActivity は FlutterFragmentActivity を継承している必要があります。

iOS/macOS: Info.plist に NSFaceIDUsageDescription を追加する必要があります。

​

カスタムスコープと audience

API に対して特定のスコープと audience をリクエストします。

lib/auth_service.dart

Future<Credentials> loginWithCustomScopes() async {
  return await auth0.webAuthentication().login(
    useHTTPS: true,
    scopes: {'openid', 'profile', 'email', 'offline_access', 'read:posts'},
    audience: 'https://myapi.example.com',
    parameters: {'prompt': 'login'},
  );
}

​

Organizations (B2B/Enterprise)

特定の organization 内でユーザーを認証します。

lib/auth_service.dart

Future<Credentials> loginWithOrganization(String organizationId) async {
  return await auth0.webAuthentication().login(
    useHTTPS: true,
    organizationId: organizationId,
  );
}

// または、ユーザーに organization を選択させる
Future<Credentials> loginWithOrganizationName(String organizationName) async {
  return await auth0.webAuthentication().login(
    useHTTPS: true,
    organizationName: organizationName,
  );
}

本番デプロイ

​

App Store 公開の準備

• シームレスな認証のために Universal Links (iOS) と App Links (Android) を設定する
• 複数の画面サイズと OS バージョンでテストする
• ネットワーク障害に備えた適切なエラーハンドリングを実装する
• コード難読化を使用する場合は、Android に ProGuard ルールを追加する
• プラットフォームごとの App Store / Play Store ポリシーに従う

​

セキュリティに関する考慮事項

• 本番環境での資格情報の保存には、組み込みの Credentials Manager を使用する
• 機密性の高い操作では生体認証を有効にする
• API セキュリティをさらに強化するために、証明書ピンニングを検討する
• 適切なトークン更新処理を実装する
• サポート対象のプラットフォームでは、Universal Links に useHTTPS: true を使用する

---

​

次のステップ

DPoP、生体認証、パスワードレスログインなどの高度なシナリオを含む、さまざまな機能に対応した詳しいコード例については、SDK リポジトリ内の EXAMPLES.md ファイルをご覧ください。