Auth0 移行ガイド

既存の認証プロバイダーからAuth0へユーザーと認証フローを移行します。

---

概要

このスキルを使用する場合

• 別の認証プロバイダーからAuth0へ移行する
• 既存ユーザーをまとめてインポートする
• アクティブなユーザーベースを段階的に移行する
• APIのJWT検証を更新する

使用しない場合

• Auth0で新規開始する - 既存ユーザーのいない新規プロジェクトの場合はauth0-quickstartを使用してください
• 既にAuth0を使用している - これはAuth0への移行用であり、Auth0テナント間の移行ではありません
• MFAまたは機能のみを追加する - 機能を追加するだけの場合は機能固有のスキルを使用してください

移行アプローチ

• 一括移行: ワンタイム・ユーザーインポート（小規模または非アクティブなベースの場合に推奨）
• 段階的移行: 時間をかけた遅延移行（大規模でアクティブなベースの場合に推奨）
• ハイブリッド: 非アクティブなユーザーをインポート、アクティブなユーザーを遅延移行

---

ステップ 0: 既存の認証プロバイダーを検出

プロジェクトに既に認証があるかを確認します:

コードベース内の一般的な認証関連パターンを検索します:

パターン	示すもの
signInWithEmailAndPassword, onAuthStateChanged	Firebase Auth
useUser, useSession, isSignedIn	既存の認証フック
passport.authenticate, LocalStrategy	Passport.js
authorize, getAccessToken, oauth	OAuth/OIDC
JWT, jwt.verify, jsonwebtoken	トークンベースの認証
/api/auth/, /login, /callback	認証ルート

既存の認証が検出された場合は確認します:

プロジェクトに既存の認証を検出しました。以下のどちらですか:

1. Auth0へ移行する (既存の認証を置き換える)
2. Auth0を並行して追加する (一時的に両方を保持)
3. 新規開始する (古い認証を削除し、新しいAuth0セットアップ)

---

移行ワークフロー

ステップ 1: 既存ユーザーをエクスポート

現在のプロバイダーからユーザーをエクスポートします。詳細な手順はユーザーインポートガイドを参照してください:

• Firebaseからのエクスポート
• AWS Cognitoからのエクスポート
• Supabaseからのエクスポート
• カスタムデータベースからのエクスポート

ユーザーごとに必須データ:

• メールアドレス
• メール検証ステータス
• パスワードハッシュ（利用可能な場合）
• ユーザーメタデータ/プロフィールデータ
• 作成タイムスタンプ

---

ステップ 2: Auth0へユーザーをインポート

ダッシュボード、CLI、またはManagement APIでユーザーをインポートします。

クイックスタート:

# Auth0 CLIを使用
auth0 api post "jobs/users-imports" \
  --data "connection_id=con_ABC123" \
  --data "users=@users.json"

詳細な手順:

• ユーザーJSONフォーマット
• パスワードハッシュアルゴリズム
• インポート方法
• インポート進行状況の監視
• 一般的なインポートエラー

---

ステップ 3: アプリケーションコードを移行

アプリケーションコードをAuth0 SDKを使用するように更新します。

詳細なBefore/Afterの例はコード移行パターンを参照してください:

フロントエンド:

• React移行
• Next.js移行
• Vue.js移行
• Angular移行
• React Native移行

バックエンド:

• Express.js移行
• API JWT検証

プロバイダー固有:

• FirebaseからAuth0へ
• SupabaseからAuth0へ
• ClerkからAuth0へ

コード移行後、フレームワーク固有のスキルを使用してください:

• auth0-react - Reactアプリケーション向け
• auth0-nextjs - Next.jsアプリケーション向け
• auth0-vue - Vue.jsアプリケーション向け
• auth0-angular - Angularアプリケーション向け
• auth0-express - Express.jsアプリケーション向け
• auth0-react-native - React Native/Expoアプリケーション向け

---

ステップ 4: API JWT検証を更新

APIがJWTを検証する場合は、Auth0トークンの検証に更新します。

主な違い:

• アルゴリズム: HS256 (対称) → RS256 (非対称)
• 発行者: カスタム → https://YOUR_TENANT.auth0.com/
• JWKS URL: https://YOUR_TENANT.auth0.com/.well-known/jwks.json

JWT検証の例を参照してください:

• Node.js / Express実装
• Python / Flask実装
• 主な違いと移行チェックリスト

---

段階的移行戦略

アクティブなユーザーを持つ本番アプリケーションの場合、段階的なアプローチを使用してください:

フェーズ 1: 並行認証

移行中にAuth0とレガシープロバイダーの両方をサポート:

// 移行中に両方のプロバイダーをサポート
const getUser = async () => {
  // 最初にAuth0を試す
  const auth0User = await getAuth0User();
  if (auth0User) return auth0User;

  // レガシープロバイダーにフォールバック
  return await getLegacyUser();
};

フェーズ 2: 新規ユーザーはAuth0で

• すべての新規サインアップはAuth0へ
• 既存ユーザーはレガシープロバイダーで継続
• 次回ログイン時にユーザーを移行（遅延移行）

フェーズ 3: 強制移行

• 残りのユーザーに「アカウント更新」を促す
• Auth0経由でパスワードリセットメールを送信
• レガシーシステムシャットダウンのデッドラインを設定

フェーズ 4: クリーンアップ

• レガシー認証コードを削除
• コンプライアンス用にユーザーエクスポートをアーカイブ
• ドキュメントを更新

---

一般的な移行の問題

問題	解決策
パスワードハッシュが互換性がない	遅延移行を使用してAuth0カスタムDB接続を使用
ソーシャルログインがリンクしない	同じソーシャル接続を設定、ユーザーはメールで自動リンク
カスタムクレームが不足している	Auth0 Actionsを使用してクレームを追加
トークン形式が異なる	APIをAuth0発行者でRS256 JWTを検証するように更新
セッション永続化	Auth0は回転リフレッシュトークンを使用、トークン保存を更新
ユーザーが再度ログインする必要がある	リダイレクトベースの認証では予想される動作、ユーザーに連絡

---

参考ドキュメント

ユーザーインポート

ユーザーのエクスポートとインポートの完全なガイド:

• 一般的なプロバイダーからのエクスポート
• ユーザーJSONフォーマット
• パスワードハッシュアルゴリズム
• インポート方法
• 監視とトラブルシューティング

コード移行

すべての主要なフレームワークのBefore/Afterの例:

• Reactパターン
• Next.jsパターン
• Expressパターン
• Vue.jsパターン
• Angularパターン
• React Nativeパターン
• API JWT検証

---

関連スキル

コア統合

• auth0-quickstart - 移行後の初期Auth0セットアップ

SDKスキル

• auth0-react - React SPA統合
• auth0-nextjs - Next.js統合
• auth0-vue - Vue.js統合
• auth0-angular - Angular統合
• auth0-express - Express.js統合
• auth0-react-native - React Native/Expo統合

---

参考資料

• Auth0ユーザー移行ドキュメント
• 一括ユーザーインポート
• パスワードハッシュアルゴリズム
• Management API - ユーザーインポート