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-quickstart --skill auth0-flutter-native

次に、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 (ベータ版) もサポートしています。これらのプラットフォーム向けには専用のクイックスタートがあります。

• Flutter Web クイックスタート — ブラウザーを対象とする Flutter アプリ向け
• Flutter Windows クイックスタート — Windows 上の Flutter デスクトップアプリ向け (ベータ版)

​

はじめに

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

   このクイックスタート向けに、新しい 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
   

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

   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 アプリを設定する

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

   1. Auth0 Dashboard に移動します
   2. Applications > Applications > Create Application をクリックします
   3. ポップアップでアプリの名前を入力し、アプリの種類として Native を選択して、Create をクリックします
   4. Application Details ページで Settings タブに切り替えます
   5. Domain と Client ID の値を控えておきます。後で必要になります

   Settings タブで、対象のプラットフォームに応じて次の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) またはバンドル識別子 (iOS/macOS) が、実際のアプリ識別子と一致していることを確認してください。認証が失敗する場合は、これらの値が同一であることを確認してください。

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

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

   Android

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

   android/app/build.gradle

   android {
       // ...
       defaultConfig {
           // 次の行を追加
           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 (bundle identifier) を設定します

   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. ログインとログアウトを実装する

   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;
     }
   }
   

   ログアウトを実装する:

   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. ユーザーが Log In をタップ → Auth0 Universal Login を表示するブラウザー/Custom Tab が開きます
   3. ユーザーが認証を完了します
   4. ブラウザーからアプリにリダイレクトされます
   5. ユーザーは認証済みとなり、認証情報が保存されます

チェックポイント

これで、Flutter アプリケーションで Auth0 のログイン機能が完全に動作するようになっているはずです。アプリは安全なブラウザベースの認証を使用し、セッションを永続化するための認証情報を自動的に保存します。

---

​

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

一般的な問題と解決策

​

Callback URL の不一致

症状: "redirect_uri_mismatch" エラーが表示される、または認証が失敗しても何も起こらないように見えます。

解決策:

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

​

Android: Chrome Custom Tab が開かない

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

修正方法:

1. manifestPlaceholders が build.gradle で正しく設定されていることを確認します
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('ログインはキャンセルされました');
  } else {
    showMessage('ログインに失敗しました: ${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('ユーザーによってログインがキャンセルされました');
    } else {
      // その他のエラーを処理
      print('ログインエラー: ${e.message}');
    }
  }
}

Future<Credentials> getCredentials() async {
  try {
    return await auth0.credentialsManager.credentials();
  } on CredentialsManagerException catch (e) {
    if (e.isNoCredentialsFound) {
      // 保存済みの認証情報がないため、ユーザーはログインする必要があります
      throw Exception('最初にログインしてください');
    } 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: ステップ 4 で設定したとおり、MainActivity は FlutterFragmentActivity を継承している必要があります。

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

​

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

API 用に特定のスコープとオーディエンスを要求します。

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'},
  );
}

​

組織 (B2B/Enterprise)

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

lib/auth_service.dart

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

// または、ユーザーに組織を選択させる
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 ファイルを参照してください。