auth0-to-descope

Auth0 → Descope 移行スキル

このスキルでは、Auth0 から Descope へのセルフサービス移行を案内します。次の 3 つのパートで構成されています。

1. MCP の確認 — Descope Docs MCP が利用可能かどうかを確認し、利用できない場合はインストールを提案します
2. 移行計画 — トリアージの質問を通じて状況を把握し、コードベース内の認証関連箇所を分析して、ユーザーが確認できる MIGRATION-PLAN.md を作成します
3. 実行 — ユーザーが続行を希望すると確認した場合、計画を実行します

これらのパートをまとめたり、先に進めたりしないでください。コードの変更を始める前に、計画を確認してもらう必要があります。

主な参考資料（どちらもこのスキルのディレクトリ内にあります）：

• references/implementation-nuances.md — 各フレームワークで検証済みの移行パターン、Auth0 の機能から Descope へのマッピング、既知の注意点
• references/flows-and-widgets.md — Descope の用語・表現、Flow の構造とテンプレート、Widget、SSO Setup Suite、コンソールとコードの使い分けガイド

---

指針

まずはコンソールから。 ユーザー向けの認証機能について SDK コードを提案する前に、コンソール、Flow、Widget でユースケースに対応できるかを確認してください。エンジニアが行うのは、一度の統合（SDK のセットアップとセッションの検証）だけです。それ以降の認証の変更（新しい方式、MFA の変更、UI の更新）は、コードをデプロイせずにコンソールで行います。詳しくは references/flows-and-widgets.md → コンソールとコードの使い分けを参照してください。

推測せず、質問する。 設計上の判断が必要な場合（Flow の埋め込みと OIDC 互換性、Flow とカスタムコード、Widget とカスタムページ、MFA のインライン登録と別途登録、プログラムによる SSO と SSO Setup Suite など）は、推測で進めず AskUserQuestion を使用してください。誤った推測による影響は、20 以上のファイルにわたって積み重なります。アーキテクチャや意図が不明な場合は、必ず質問してください。

記憶より MCP を優先。 Docs MCP が利用可能であることを（パート 1 で）確認したら、SDK のメソッド名、オプションの形式、戻り値の型を記述する前に、ask-question-about-descope を使って一つずつ確認してください。「SDK の型宣言で正確なメソッド名を確認してください」といった曖昧な案内に頼らず、直接確認してください。

---

パート 1：MCP の確認（必須）

ほかの作業を始める前に、search-descope-docs を簡単なクエリ（例：「セッションの検証」）で呼び出し、Descope Docs MCP が利用可能かどうかを確認してください。

ツールが利用可能な場合： すぐにパート 2 に進んでください。

ツールが利用できない場合は、次のメッセージを表示し、AskUserQuestion を使って、最初にインストールするかどうかを尋ねてください。

Descope Docs MCP がインストールされていません。

このスキルでは、移行中に最新の API シグネチャ、SDK メソッド、機能の利用可否を確認するため、Descope Docs MCP を使用します。これがない場合、案内は静的な学習データに基づくため、古くなっている可能性があり、存在しない SDK 呼び出しを提示することがあります。

インストールには数分かかります。**https://docs-mcp.descope.com/**（サーバー URL： https://docs-mcp.descope.com/mcp）からインストールできます。これにより、移行結果の精度が大幅に向上します。特に SDK の確認や Flow 固有の設定で効果があります。

続行する前に MCP をインストールしますか。それとも、インストールせずに進めますか？

• インストールを選んだ場合：一時停止して待機してください。インストールしたという確認を受けたら、続行する前に search-descope-docs を再度呼び出して確認してください。
• インストールせずに進めることを選んだ場合：続行できますが、SDK 固有の回答には「既知の最新ドキュメントに基づいています。現在の SDK で確認してください」と明記してください。

この手順が完了するまで、パート 2 に進まないでください。

---

パート 2：移行計画

パート 2 は、次の 2 つのサブステップで構成されています。

1. トリアージ — 移行の範囲を把握するために必要な質問をしてください（回答が計画に影響するため、移行に関する質問はここで行います）
2. コードベースの分析と計画ファイル — プロジェクトをスキャンし、MIGRATION-PLAN.md を作成して、確認のために一時停止してください

ステップ 0：トリアージ（ブロッキング — AskUserQuestion が必要です）

AskUserQuestion ツールを使って、以下の情報を収集してください。記憶、過去の会話、推測から回答を導き出してはいけません。知っていると思っていても同様です。 回答によって移行の進め方が異なります。間違えると、ユーザーの時間を無駄にし、誤ったガイダンスにつながります。

ユーザーが回答するまで、ステップ 0.5 に進まないでください。

1 回目の AskUserQuestion 呼び出し（最大 4 つの質問）：

1. バックエンドの言語／フレームワーク — 会話中の手がかり（Express、Next.js、Flask／FastAPI、Go など）をもとに、最も可能性の高い選択肢を提示してください。ユーザーはいつでも「その他」を選択できます。
2. 移行の目標 — 全面移行、段階的／フェーズ分けした移行、または評価のみ。
3. 既存のユーザーベース — Auth0 にアクティブユーザーがいるアプリを移行するのか、新規に始めるのかを確認します。これにより、ユーザー移行の計画（パスワードハッシュ、一括インポート、段階的または一斉の切り替え、切り替え時の強制再ログイン）が必要かどうかが決まります。
4. 希望する移行スタイル — Descope Flows／Widgets を直接組み込む（全面的なネイティブ移行）のか、既存の OIDC クライアントライブラリを維持して Descope の OIDC エンドポイントを指定する（OIDC 互換レイヤー）のかを確認します。注：B2B 機能（Organizations／SSO／SCIM の管理）には OIDC レイヤーの同等機能がなく、どちらの方法でもネイティブ SDK の呼び出しが必要です。

2 回目の AskUserQuestion 呼び出し — Auth0 の機能の利用状況（multiSelect: true を使用）：

4. どの Auth0 機能を使用していますか？ 影響の大きいカテゴリを提示してください。

   • Actions／Rules／Hooks（カスタムログインロジック）
   • Organizations（マルチテナンシー／B2B）
   • FGA／きめ細かな認可
   • ソーシャルログイン／エンタープライズ SSO

   ユーザーは「その他」からほかの機能も追加できます。選択された項目については、さらに確認してください。たとえば、Organizations が選択された場合は、テナントスコープの SSO、SCIM、招待について質問します。FGA が選択された場合は、認可モデルについて質問します。

   また、まだ確認できていない場合は、フォローアップの AskUserQuestion で以下も確認してください。

   • Token Vault／Connected Accounts の利用状況
   • M2M／クライアントクレデンシャルアプリ
   • カスタムメールテンプレート、Log Streams、Attack Protection、カスタムドメイン

両方の呼び出しを終えたら、調査結果を要約し、ステップ 0.5 に進む前に、複雑性の高い項目（CIBA、Token Vault、FGA）を明示してください。

---

ステップ 0.5：エンジニアレビューのチェックポイント（ブロッキング — AskUserQuestion が必要）

フレームワークでは把握できない阻害要因を明らかにする質問です。分かっていると思う質問も必ず確認してください。コードベースの分析に進む前に、AskUserQuestion を使ってください。

最大 4 件の質問をまとめて呼び出してください。ステップ 0 の回答から明らかに該当しない質問は省略してください（例：新規に始めると回答した場合は、ユーザー移行の計画を省略します）。

アクセスと認証情報

• Descope Console と Project ID にアクセスできますか？（できない場合は、ステップ 1.5 を参照してください。）
• Management Key が必要ですか？（ユーザーの CRUD、ロール管理、ReBAC、Outbound Apps に必要です。）

コードベースの範囲

• セッショントークンからクレームを直接読み取る箇所（例：token.email、req.auth.permissions）はアプリ内にありますか？これらを機能させるには、事前に JWT Template を設定する必要があります。
• Auth0 Actions、Rules、Hooks を使用していますか？それぞれを Descope Flow のステップまたは JWT Template として再作成する必要があります。
• Auth0 トークンを検証するサービスやマイクロサービスが複数ありますか？それぞれで Descope JWT を検証するように更新する必要があります。

デプロイとリスク

• 複数の環境（dev／staging／prod）がありますか？それぞれに独自の Descope プロジェクトと Project ID が必要です。
• メンテナンス時間を設けますか？それとも、ダウンタイムなしで移行する必要がありますか？

ユーザー移行（ステップ 0 で既存ユーザーがいると回答した場合）

• ユーザーは何人いますか？1,000 人未満の場合、移行スクリプトで Auth0 API から直接取得できます。1,000 人を超える場合、Auth0 API のページネーションが機能しなくなるため、まず Auth0 の User Import/Export 拡張機能を使って JSON ファイルをエクスポートする必要があります。
• パスワードを使用していますか？使用している場合、パスワードハッシュのエクスポートを入手するには Auth0 にサポートチケットを提出する必要があります。時間がかかるため、余裕を持って計画してください。ハッシュがない場合、ユーザーはパスワードをリセットするか、パスワードレスに切り替える必要があります。
• 一斉に切り替えますか？それとも段階的に切り替えますか？中断を避けるには、Descope のセッション移行（ベータ版）を利用できます。既存の Auth0 セッションを再認証なしで Descope トークンに交換できますが、ユーザーはすでに Descope に存在している必要があります。段階的に移行する場合は、freshlyMigrated カスタム属性（移行スクリプトによって自動設定）を Flow の条件分岐で使用し、移行後に初めてログインするユーザーに特別なオンボーディング経路を提供できます。
• セッション移行を使用しない場合、切り替え時に Auth0 セッションが無効になることを認識していますか？強制的な再ログイン、または段階的なロールアウトを計画してください。
• descope/descope-migration スクリプト（ステップ 3）を案内し、本番実行前にドライラン（--dry-run）を行うことを推奨してください。

すぐに指摘するべき不足点（質問はせず、ステップ 0 の回答に基づいて先回りして指摘してください）

• CIBA または @auth0/ai ラッパーを使用している場合は、先に進む前に指摘してください。Descope に同等の機能はなく、カスタム実装が必要です（ステップ 3 を参照）。
• AI エージェントで Auth0 Token Vault を使用している場合、移行の複雑さは中程度です。SDK ラッパーはありません。
• Auth0 Log Streams を使用している場合、イベントログの欠落を避けるため、切り替え前に Descope の Audit Webhook Connector を設定してください。

Console／Flow／Widget の活用機会（コードベース分析の前に指摘し、その後に質問してください）

• アプリにカスタムの SSO 設定ページがある場合、SSO Setup Suite と Tenant Profile Widget でそのコードを置き換えられるか尋ねてください。
• アプリにプロフィール編集ページやユーザー管理 UI がある場合、Descope Widget でそのユースケースに対応できるか尋ねてください。
• 独立した MFA 登録ページがある場合、代わりに MFA をメインのサインイン Flow にステップまたはサブフローとして統合するか尋ねてください（Descope では、ほとんどの場合その方がすっきりします）。
• サーバーサイドのコードでメールを生成する、SSO を開始する、または認証フロー中にロジックを実行する箇所がある場合、そのロジックをサーバーコードではなく Flow のステップまたは Connector にできるか尋ねてください。

コードベースの分析に進む前に、阻害要因と Console／Flow の活用機会をまとめてください。

---

ステップ 1：コードベースの分析

計画を作成する前にコードベースをスキャンし、認証に関するすべての接点を洗い出します。

以下の検索を実行します（ファイル拡張子はユーザーの言語に合わせて調整してください）：

# Find all Auth0 import sites
grep -rn "auth0\|@auth0\|express-openid-connect\|nextjs-auth0\|auth0-fastapi\|go-oidc" \
  --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" --include="*.go" \
  --exclude-dir=node_modules --exclude-dir=.next --exclude-dir=dist --exclude-dir=venv \
  . 2>/dev/null

# Find all Auth0 env var references
grep -rn "AUTH0_\|auth0\." \
  --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" --include="*.go" \
  --include="*.env*" --include="*.yml" --include="*.yaml" --include="Dockerfile" \
  --exclude-dir=node_modules --exclude-dir=.next \
  . 2>/dev/null

# Find claim / token access patterns (things that may need JWT Template)
grep -rn "token\.\|claims\.\|req\.auth\.\|req\.oidc\.\|session()\." \
  --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" --include="*.go" \
  --exclude-dir=node_modules --exclude-dir=.next \
  . 2>/dev/null

# Find protected route declarations
grep -rn "requiresAuth\|withPageAuthRequired\|withApiAuthRequired\|require_session\|@login_required\|authMiddleware\|isAuthenticated" \
  --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" --include="*.go" \
  --exclude-dir=node_modules --exclude-dir=.next \
  . 2>/dev/null

# Check package.json / go.mod / requirements.txt for Auth0 dependencies
find . -maxdepth 3 \( -name "package.json" -o -name "go.mod" -o -name "requirements.txt" \) \
  ! -path "*/node_modules/*" -exec grep -l "auth0" {} \;

各検索結果について、次の情報を記録します。

• ファイルパスと行番号 — 変更箇所
• 役割 — インポート、ルート保護、クレームへのアクセス、ログアウトハンドラーなど
• 複雑さ — 低（そのまま置き換え可能）、中（ロジックの書き換え）、高（同等機能なし）

package.json（または同等のファイル）を読み、フレームワークの正確なバージョンを確認します。これは非同期動作（Next.js 15 と 14 の違い）や SDK の互換性に影響します。

Descope Docs MCP が利用可能な場合は、計画で参照する SDK メソッド名が最新であることを確認するため、search-descope-docs または ask-question-about-descope を使用します。

---

ステップ 2：MIGRATION-PLAN.md の作成

トリアージの回答とコードベースの分析結果を使って、作業ディレクトリに MIGRATION-PLAN.md を作成します。

対象読者は 2 種類です。エンジニアが作業を実行するのに十分な技術的詳細と、PM やテックリードが専門用語を解読せずに範囲、リスク、スケジュールを把握できる内容が必要です。平易な英語を使い、技術用語は初出時に説明します。各セクションの冒頭では、表や根拠を示す前に、そのセクションの要点をまとめる一文を書きます。リスクについては、存在するというだけでなく、見落とした場合に何が壊れるかを記載します。複雑さの区分には作業時間の見積もりを添えます。見積もりは下限寄りにしてください。SDK の置き換えや機械的な書き換えは、通常見た目ほど時間がかからず、同じ作業を複数のファイルに繰り返す場合は、最初のファイル以降は大幅に速く進みます。作業をフェーズごとにまとめ、並行作業と順次作業が分かるようにします。

計画には次のセクションを、この順序で含めます。

概要

2～3 文で、何を何に置き換えるのか、推奨する方法とその理由を 1 文で説明します。ユーザー向けのログイン動作、セッション、既存アカウントは維持され、変更されないことについても 1 文を加えます。

移行の概要の表を含めます。

アプローチ	ネイティブへの全面移行 / OIDC 互換レイヤー
変更対象ファイル	N 個の領域にわたるソースファイル N 個
コンソールの設定	リリース前に必要な設定手順 N 件
ユーザーへの影響	再ログイン不要 / 切り替え後にユーザーは 1 回ログインが必要
エンジニアリング作業の見積もり	N～N 時間
最大のリスク	最も複雑な項目を特定する一文

---

変更点とその理由

各システム要素が現在どのように機能し、移行後にどうなるかを、表ではなく文章で説明します。例：

現在、ログインに関するすべてを Auth0 が処理しています。ログイン UI の表示、トークンの発行、各 API リクエストでのトークン検証などです。この移行後は、Descope がこれらの役割をすべて担います。ログイン UI はアプリに埋め込まれた Descope コンポーネントになります。トークンの検証には Descope SDK を使用します。5 つの Auth0 環境変数は、単一の Descope Project ID に置き換えられます。

現在使用中で、引き継ぐ必要がある Auth0 の機能：[各項目を平易な英語で、1 項目につき 1 つの節として列挙します]。

トリアージの結果に合わせて内容を調整します。

---

認証関連の接点：コード分析で判明したこと

対象範囲の件数から始めます（例：「4つの領域にまたがる11ファイル」）。 ファイルパスではなく、領域ごとにまとめます。 各グループには、現在の機能と変更内容を説明する文を添えます。

セッション管理（3ファイル） — これらのファイルは、現在のユーザーのログイン状態を読み取り、検証します。Auth0 の代わりに Descope のセッション SDK を使用するよう更新します。

ファイル	現在の機能	変更内容
lib/auth.ts:34	isAuthenticated、user、claims を含む Auth0 セッションを返します	Descope の AuthenticationInfo を返すよう書き換えます。薄いアダプターレイヤーにより、呼び出し元が期待する形式を維持します
middleware.ts:12	アプリ全体で未認証のリクエストをブロックします	Descope のセッション検証を呼び出すよう更新します。ロジックは同じで、SDK の呼び出しが変わります

ログイン／ログアウトのルート（2ファイル） — これらは Auth0 のリダイレクトベースのログインフローを処理します。 Descope では埋め込み UI コンポーネントを使用するため、リダイレクトの往復は不要です。

ファイル	現在の機能	変更内容
pages/api/auth/[...auth0].ts	OAuth コールバック、ログアウト、セッション更新のキャッチオールハンドラーです	削除します — Descope がクライアント側で処理するため、サーバールートは不要です

すべての機能領域を網羅します。最後は「合計：Nファイル。推定コード変更工数：N～N時間。」で締めくくります。

---

機能の移行：Auth0 → Descope

トリアージで確認された Auth0 の機能ごとに、実現しようとしていること、その目的に最適な Descope のアプローチ、相違点、必要な作業を短い段落で説明します。最適なアプローチは、直接対応する SDK ではなく、Flow、Widget、SSO Setup Suite、または Console の設定の場合もあります。API の表面だけでなく、意図に基づいて判断します。プログラムによる制御が本当に必要な場合に限り、SDK コードを推奨します。例：

マルチテナンシー（Auth0 Organizations → Descope Tenants） Auth0 Organizations はユーザーを企業ごとにグループ化し、権限の適用範囲を設定します。Descope にも Tenants という同じ概念があり、移行スクリプトが自動的に移行します。 主な違いは、テナントのメンバーシップがセッショントークンにどのように現れるかです。Auth0 ではフラットな org_id 文字列を使いますが、Descope ではテナントごとのロールを含むネストされた tenants オブジェクトを使います。req.auth.org_id を読み取るバックエンドコードは、token.tenants を読み取るよう更新する必要があります。これは予測しやすく、機械的に変更できます。 工数：中（1～2時間）。 データは移行スクリプトで処理されます。コード変更はトークン読み取りのロジックに限定されます。

確認済みの機能のみを含めます。

---

コードを実行する前に：必須の設定

Descope の動作の一部は、コードではなくコンソールで設定します。アプリが動作する前に設定が必要な項目をすべて、チェックボックス形式で列挙してください。各項目について、何を設定するのか、なぜ必要なのか、所要時間の目安を簡潔に説明してください。「テスト開始前に必須」と「本番環境への移行前に必須」に分けてください。

テスト開始前に必須：

• Descope プロジェクトを作成する — 所要時間は 2 分です。アプリの環境変数にある Auth0 の認証情報すべてを置き換える Project ID が発行されます。
• 認証フローを作成する — Descope では、視覚的な「フロー」を使ってログイン体験（提供する認証方法とその順序）を定義します。組み込みの sign-up-or-in フローは、ほとんどのアプリで利用でき、カスタマイズせずに使い始められます。
• ユーザープロファイルのトークンテンプレートを設定する — デフォルトでは、Descope のセッショントークンにユーザーの名前、メールアドレス、プロフィール写真は含まれません。アプリでユーザープロファイル情報を表示するには、このテンプレートを設定する必要があります。設定しないと、ログイン後にユーザーの名前やメールアドレスを表示する UI の部分が何も表示されません。（約 10 分）

本番環境への移行前に必須：

• ロールを作成する：admin、member（またはコードベースで参照されているロール） — コードからロールを割り当てる前に、Descope コンソールでロールを作成しておく必要があります。
• ソーシャルログインプロバイダーを設定する（Google、GitHub など） — 各プロバイダーの OAuth 認証情報をコンソールに入力する必要があります。（プロバイダーごとに約 15 分）
• （分析で見つかった項目ごとに続ける）

---

環境変数

削除する項目と追加する項目それぞれについて、平易な説明を付けた差分表：

削除	追加	理由
AUTH0_CLIENT_ID	—	Auth0 はクライアント ID でアプリを識別します。Descope では代わりに Project ID を使用します。よりシンプルで、プロジェクト内のすべてのアプリで共有されます。
AUTH0_CLIENT_SECRET	—	不要です。Descope のブラウザー側フローではシークレットは必要ありません。
AUTH0_ISSUER_BASE_URL	—	Auth0 テナントの URL です。Project ID に置き換わります。
AUTH0_AUDIENCE	—	Auth0 で API アクセスの範囲指定に使用されます。必要に応じて、Descope ではトークンテンプレートで同等の設定ができます。
SECRET	—	Auth0 の SDK がサーバー側セッションの暗号化に使用します。Descope ではサーバー側セッションを使用しません。
—	DESCOPE_PROJECT_ID	Descope プロジェクトを識別する唯一の ID です。上記の項目すべてを置き換えます。
—	NEXT_PUBLIC_DESCOPE_PROJECT_ID	同じ値をログインコンポーネント用にブラウザーへ公開します。
—	DESCOPE_MANAGEMENT_KEY	アプリがサーバー側でユーザー、ロール、テナントを管理する場合にのみ必要です。

続けて次のように記載してください：「差し引き：変数を 5 個削除し、1～3 個追加します。Auth0 側でシークレットをローテーションする必要はありません。これらの認証情報は今後使用されなくなります。」

---

ユーザー移行（既存ユーザーの移行が必要な場合のみ）

まず移行戦略を文章で説明し、その後に手順を示してください。次の文から始めてください：「カットオーバー前に、既存ユーザー X 人を Descope に登録する必要があります。」以下を説明してください。

• 計画：一斉移行（カットオーバー前に全ユーザーを移行）か段階的な移行か、その理由
• ユーザーが経験すること：再ログインが必要か、見た目に変化があるか
• 最大の依存事項：パスワードの移行に Auth0 サポートチケットが必要な場合は、その旨を明確に説明し、数日かかる可能性があるため、チケットを直ちに起票するよう明記してください

最後に、PM が進捗を追える粒度で、移行手順の簡潔なチェックリストを付けてください。

• Auth0 サポートチケットを起票して、パスワードハッシュのエクスポートを依頼する（該当する場合）— 直ちに開始
• Auth0 からユーザーリストをエクスポートする（ユーザー数が 1,000 人を超える場合）
• Descope の開発用プロジェクトを対象に、移行スクリプトのドライランを実行する
• ドライランの出力にエラーがないか確認する
• ステージング環境、続いて本番環境を対象にライブ移行を実行する

---

トレードオフと考慮事項

スケジュール、ユーザー体験、またはスコープに影響する可能性がある事項です。各項目を平易な日本語で、内容、無視した場合の問題、対応方法の3つの要素で記述します。 それぞれを名前付きのコールアウトとしてフォーマットします。

考慮事項：トークンテンプレートを設定するまで、ログイン後にユーザープロフィールデータが表示されません Descope のセッショントークンには、デフォルトで名前、メールアドレス、プロフィール写真が含まれません。ユーザー情報を表示するアプリのすべての箇所（プロフィールページ、ナビゲーションバー、挨拶文など）で、Descope コンソールのトークンテンプレートを設定するまで、移行後に値が空欄になります。これは一度限りの設定作業であり、コードの変更は必要ありません。 対応： テストを実行する前に、Descope コンソールでトークンテンプレートを設定してください。 所要時間の見積もり：10分。

考慮事項：パスワードの移行には Auth0 へのサポートリクエストが必要です アプリがパスワードベースのログインに対応している場合は、ユーザーのハッシュ化されたパスワードを Auth0 からエクスポートし、Descope にインポートする必要があります。Auth0 はサポートチケットを通じてのみこれらを提供しており、対応に数日かかる場合があります。 対応： 開発作業と並行して、今すぐサポートチケットを作成してください。これを行わない場合、切り替え後にパスワードを使用するユーザーはパスワードをリセットする必要があります。

該当するトレードオフと考慮事項のみを含めてください。

---

実行計画

最初に、フェーズは順番に実行し、各フェーズ内のステップは並行して実行できることを1文で述べます。 続けて、所要時間の見積もりを含むラベル付きフェーズを記載します。

---

フェーズ 1 — コンソールの設定（約30～45分、コード不要） Descope コンソールにアクセスできるチームメンバーであれば誰でも、他の作業と並行して実施できます。

• Descope プロジェクトを作成し、Project ID をコピーする
• 認証フローを作成する（最初は組み込みの sign-up-or-in を使用）
• ユーザープロフィールのトークンテンプレートを設定する
• ロールを作成する：（実際に見つかったロールを列挙）
• ソーシャルログインプロバイダーを設定する：（実際に見つかったプロバイダーを列挙）

フェーズ 2 — コードの変更（約X～Y時間、エンジニア1名） ファイルを記載順に作業します。各グループの作業後にコンパイルチェックを実行します。

• pages/api/auth/[...auth0].ts を削除する — 置き換えは不要（5分）
• .env.example と CI 設定の環境変数を更新する（15分）
• lib/auth.ts のセッションヘルパーを書き換える（30分）
• _app.tsx を更新する — UserProvider を Descope の AuthProvider に置き換える（15分）
• 保護されたルートファイル8個を更新し、新しいセッションチェックを使用する（45分）
• lib/logout.ts を更新する — 2段階ログアウト（15分）
• コンパイルチェックを実施し、先に進む前に型エラーを修正する

フェーズ 3 — ユーザーの移行（約1～2時間、ドライランを含む） まず開発環境／ステージング環境に対して実行します。フェーズ4に合格するまで、本番環境に対して実行しないでください。

• （上記のユーザー移行セクションの手順）

フェーズ 4 — テスト（約30～45分）

• コンパイルがエラー0件で成功する
• サーバーが起動し、起動時にクラッシュしない
• 未認証のルートが正しくログインページにリダイレクトされる
• ログインフローが完了し、ユーザープロフィールデータが表示される（トークンテンプレートが機能していることを確認）
• ログアウトによってセッションが無効になる

フェーズ 5 — 本番環境への切り替え

• （メンテナンス時間帯、段階的なロールアウトなど、採用する戦略に応じた切り替え手順）

---

エンジニアリング作業の合計見積もり：エンジニア N 名で N～N 時間。 作業を妨げる依存関係：（サポートチケット、コンソールへのアクセスなど、クリティカルパス上の項目を列挙）

---

MIGRATION-PLAN.md を作成した後は、作業を止めてユーザーに次のように伝えてください。

MIGRATION-PLAN.md を作業ディレクトリに作成しました。見つかった認証関連のすべての箇所を整理し、最初のテスト前にコンソールで設定する必要がある内容を記載し、スケジュールに影響する可能性があるトレードオフと考慮事項を取り上げています。

変更を開始する前に内容をご確認ください。準備ができたら、お知らせください。

ユーザーが確認するまで、パート3に進まないでください。

---

パート3：実行

MIGRATION-PLAN.md のセクション8に記載された順序で計画を実行します。各ステップについて、以下の詳細なガイダンスに従ってください。

---

コンテキスト継続プロトコル

ターン間でコンテキストが失われることがあります。以下のルールに従い、移行の一貫性を保ってください。

ステップ 3.0 — コードに手を付ける前に MIGRATION-STATE.md を作成します。

以下のテンプレートを使って、作業ディレクトリに MIGRATION-STATE.md を作成してください。このファイルは移行状態の信頼できる唯一の情報源です。作業中は常に最新の状態に保ってください。

# Migration State

_Last updated: [timestamp of last completed step]_

## Project Context
- Framework: [e.g., Next.js 14, Express + React]
- Language: [TypeScript / Python / Go]
- Package manager: [npm / yarn / pnpm / pip / etc.]
- Migration path: [Path A: OIDC compat / Path B: Full native]
- Migration goal: [Full cutover / Phased / Evaluating]

## Triage Answers
- Existing users: [Yes — N users / No — greenfield]
- Password migration needed: [Yes / No]
- Auth0 features in use: [comma-separated list]
- Multiple environments: [Yes: dev/staging/prod / No]
- Zero-downtime required: [Yes / No]

## Files Inventory
_All files that need to change. Update status after each step._

| File | Change | Status |
|---|---|---|
| `pages/api/auth/[...auth0].ts` | Delete | ⬜ Pending |
| `lib/auth.ts` | Rewrite session helper | ⬜ Pending |
| `middleware.ts` | Update session check | ⬜ Pending |

## Console Setup Checklist
- [ ] Descope project created — Project ID: (fill in when done)
- [ ] JWT template configured
- [ ] Roles created: (list roles)
- [ ] Social providers configured: (list providers)

## Decisions Log
_Non-obvious decisions made during migration — preserves rationale if context is lost._

_(none yet)_

## Current Phase
Phase 1 — Console Setup (not started)

## Next Action
Complete console setup per MIGRATION-PLAN.md before making any code changes.

## Blockers
_(none)_

---

ルール 1 — ターンごとに読み直します。

各実行ターンの開始時に、コードを記述したり判断を下したりする前に、MIGRATION-PLAN.md と MIGRATION-STATE.md を読み直してください。

ルール 2 — コードを変更する前にコンテキストを確認します。

フレームワーク、移行パス、トリアージの回答、または次のステップが会話から明確でない場合は、作業を進める前に両方のファイルを読み直してください。その後、コンテキスト行を出力します。

Migration context: Next.js 14 · Path B · Phase 2, step 3/8 · Next: rewrite lib/auth.ts

この行を正確に記入できない場合は、まずファイルを読み直してください。

ルール 3 — 各ステップの直後に MIGRATION-STATE.md を更新します。

Files Inventory で該当ファイルを完了済みにし、「Current Phase」と「Next Action」を更新して、見落としやすい判断があれば Decisions Log に追記してください。次のステップに進む前に実施してください。

---

生成前プロトコル（コードを書く前に適用）

import、ラッパー型、またはヘルパーを生成する前に実行してください。省略すると、コンパイルはできても実行時に失敗するコードが生成されます。

1. import を記述する前に SDK のエクスポートを確認します。 Docs MCP が利用できる場合は、ask-question-about-descope を使って、SDK 呼び出しを記述する前に正確なメソッド名、オプションの形式、戻り値の型を確認してください。型宣言を読むより速く、確実です。メソッド名を記述して「正確な名前を確認してください」と但し書きを加えるのではなく、実際に確認してください。

Docs MCP が利用できない場合は、パッケージの型宣言（node_modules/<pkg>/dist/types/ または package.json の types フィールド）を参照し、正確なエクスポート名とシグネチャを確認してください。Go では go doc を実行してください。Python では SDK のスタブを確認してください。

型宣言を読むときは、GitHub よりローカルの node_modules/ を優先してください。インストール済みのパッケージは、実際に使われている正確なバージョンを反映しています。Descope パッケージがまだインストールされていない場合は、先にインストールしてからローカルの型宣言を参照してください。現在の環境にパッケージをインストールできない場合に限り、GitHub を参照してください。

これは、最初の import だけでなく、記述するすべての SDK 呼び出しに適用されます。オプションオブジェクトのフィールド名（sendMail と sendEmail）、フックの戻り値の形式（useDescope() は { sdk } ではなく SDK 自体を返します）、サブパスのエクスポート（/client とルート）は、いずれも同じくらい頻繁に異なります。

1a. モジュールを書き換えた後、削除したパッケージの import が残っていないか grep で検索します。

grep -r "from '@/lib/auth0'\|from '@auth0/" --include="*.ts" --include="*.tsx" .

残りの該当箇所を作業リストに追加してください。

2. 実際の戻り値の型からラッパー型を導きます。 関数の宣言済みの戻り値の型を読み、それに合うようにラッパーを作成してください。Auth0 とはフィールド名、ネスト、フラグが異なります。Auth0 をもとに推測しないでください。

3. フレームワーク固有のコードを生成する前に、依存関係のバージョンを確認します。 Next.js では、v14 の next/headers の cookies() と headers() は同期処理ですが、v15 では非同期処理です。まず package.json（または go.mod、requirements.txt）を読んでください。

4. ヘルパーを非同期にする場合は、すべての呼び出し元にも直ちに反映します。 TypeScript では、共有ユーティリティに async を付けると、await を省略している呼び出し元で気付かないまま問題が発生します。変更した関数のすべての呼び出し箇所を grep で検索し、同じ作業中に更新してください。影響範囲は 10〜20 個のファイルに及ぶことがあります。

5. package.json を編集したり npm install を実行したりする前に、公開済みパッケージのバージョンを確認します。 Auth0 のバージョン番号を流用したり、学習データに基づいてバージョンを決めたりしないでください。インストールコマンドを記述する前に、次を実行してください。

npm view @descope/node-sdk version
npm view @descope/nextjs-sdk version

npm を利用できない場合は、バージョンを "latest" のままにして、その旨を明記してください。

Step 1.5: Descope プロジェクトのセットアップとコンソールの設定

いくつかの手順では、コードでは実行できない Descope コンソールの設定が必要です。これらを設定しなくてもアプリはコンパイルできますが、実行時に動作しません。

AskUserQuestion を使って、すでに Project ID と動作する Flow があるかを確認してください。ある場合は、既存のプロジェクトでも見落としやすい項目 5～7 の確認に進んでください。

1. プロジェクトを作成し、Project ID を取得する

• console.descope.com にサインインします
• Project ID は、左上のプロジェクトセレクターと Project → Settings に表示されます。P で始まります（例：P2abc123...）。
• Next.js のクライアントサイドコードでは、NEXT_PUBLIC_DESCOPE_PROJECT_ID に設定します。サーバーサイド SDK では、DESCOPE_PROJECT_ID に設定します。

2. Management Key を取得する（必要な場合）

必要となる機能：ユーザー管理 API、ロール／権限管理、テナント操作、ReBAC （FGA）、Outbound Apps、SCIM 設定。サーバーサイドでユーザーまたはテナントの管理を行うアプリには必要です。

• コンソール → Company → Management Keys → Generate Key
• DESCOPE_MANAGEMENT_KEY として保存します。シークレットとして扱い、クライアントサイドでは決して公開しないでください。

3. Flow を選択または作成する

Flow は認証 UI の手順です。Web コンポーネントでは Flow ID を指定して参照します。

• コンソール → Authentication → Flows
• 組み込みの "sign-up-or-in" Flow は、メールアドレス／パスワード、OTP、ソーシャルログインに対応しています。ほとんどの移行でこれを使用します。
• カスタマイズするには、"sign-up-or-in" を複製して名前を変更し、ビジュアルビルダーで編集します。
• Flow ID は、編集中の URL とフローリストに表示されます。
• ライブラリには 100 以上の Flow テンプレートがあります。カスタムフローを作成する前に、既存のテンプレートを確認してください。references/flows-and-widgets.md → Flows を参照してください。
• MFA：Flow に MFA ステップを追加するか、MFA をサブフローとして組み込みます。Descope は Management SDK ではなく Flow を通じて MFA の登録を管理します。Auth0 Guardian の登録チケットに相当するものはありません。要素の種類ごとの削除に対応する SDK については、references/implementation-nuances.md → MFA セクションを参照してください。

4. 認証方法を設定する

• コンソール → Authentication → 方法を選択します（メール OTP、マジックリンク、ソーシャル、SSO など）
• ソーシャルプロバイダー（Google、GitHub など）の場合：ここで OAuth 認証情報を設定してから、プロバイダーのステップを Flow に追加します。
• エンタープライズ SSO（SAML/OIDC）の場合：コンソール → SSO → テナントごとに設定します。SSO コールバック URL と ACS URL（ソーシャル OAuth、SAML ACS、使用してはいけない URL）の正しい設定については、references/implementation-nuances.md → ソーシャルログイン／SSO セクションを参照してください。

5. JWT Template を設定する（ほぼ常に必要）

Auth0 では、トークンに email、name、picture がデフォルトで含まれます。Descope では含まれません。

• コンソール → Authorization → JWT Templates → New Template
• 次のクレームを追加します：{"email": "{{user.email}}", "name": "{{user.name}}", "picture": "{{user.picture}}"}
• テンプレートをプロジェクトに適用します。この手順を行わないと、移行後に token.email を読み取るコードは undefined を取得します。

6. コンソールでロールを作成する（RBAC を使用する場合）

Descope のロールは ID ではなく 名前 で参照されます。ロールを割り当てるコードが動作する前に、コンソールで手動作成する必要があります。

• コンソール → Authorization → RBAC → + Role
• アプリが参照するロールをそれぞれ作成します（例：admin、member）

7. カスタム属性を定義する（テナント／ユーザーのメタデータを使用する場合）

Auth0 の Organization metadata と User app_metadata は、Descope の customAttributes に対応します。SDK で設定する前に、コンソールのスキーマで事前定義してください。

• コンソール → Project → Custom Attributes

8. 環境変数のまとめ

Variable	Where to get it	Used by
DESCOPE_PROJECT_ID	コンソール → Project Settings	すべてのサーバーサイド SDK
NEXT_PUBLIC_DESCOPE_PROJECT_ID	上記と同じ値	Next.js AuthProvider（クライアントサイド）
DESCOPE_MANAGEMENT_KEY	コンソール → Company → Management Keys	Management SDK、Outbound Apps API

9. 管理 UI にウィジェットを検討する

カスタムのプロフィールページ、ユーザー管理ページ、ロール割り当て UI を移行する前に、Descope ウィジェットでユースケースをカバーできるか確認してください。references/flows-and-widgets.md → Widgets を参照してください。

コンソールの設定完了後： MIGRATION-STATE.md を更新します。Console Setup Checklist の各完了項目にチェックを入れ、Project ID をファイルに記録し、Next Action を最初のコード変更手順に設定してください。

---

Step 2: フレームワーク固有の移行

コードを書く前に、references/implementation-nuances.md を 2 回に分けて読んでください。

1. General Insights（必須） — アーキテクチャ、機能の対応関係、一般的な注意点を扱っており、フレームワークを問わずすべての移行に適用されます。
2. フレームワークのセクション（ファイルの ToC と offset を使って直接移動） — ユーザーのスタックに一致するセクションだけを読んでください。
   • Express.js → ## Express.js
   • Flask / Python、FastAPI → ## Flask / Python（FastAPI に関する注意点は、General Insights の「No drop-in middleware」サブセクションに記載されています）
   • Next.js（App Router、standalone） → ## Next.js (standalone) + ## Next.js (B2B): Migration Bug Catalog
   • Next.js + 個別の Express API サーバー → ## Next.js (with separate Express API server)
   • Go → ## Go + Encore
   • FGA または Token Vault を使用する LangChain / LangGraph / Vercel AI → ## Agentic AI Stacks

ファイルに新しいフレームワークを追加した場合は、このリストにも追加してください。

Express.js

• express-openid-connect を削除し、@descope/node-sdk と cookie-parser を追加します。
• app.use(auth(config)) を、DS Cookie を読み取り descopeClient.validateSession() を呼び出す約 20 行のカスタムミドルウェアに置き換えます。
• <descope-wc> ウェブコンポーネントをレンダリングする /login ルートを追加します（EJS、プレーン HTML など）。
• ログアウト：descopeClient.logout(refreshToken) を POST し、DS／DSR Cookie をクリアします。

主な注意点：

• express-openid-connect は CSRF と Cookie の解析を内部で処理していました。cookie-parser を明示的に追加する必要があります。
• req.oidc.user → req.user（validateSession() 後に検証済み JWT クレームから設定）
• requiresAuth() は、SDK のインポートではなく、3 行のカスタムコードです。

Flask / Python

• authlib を削除し、descope Python SDK を追加します。
• /callback ルートを完全に削除します。コード交換は不要です。
• /login は authorize_redirect() を呼び出すのではなく、Descope ウェブコンポーネントをレンダリングします。
• ログアウト：descope_client.logout(refresh_token) を呼び出し、Cookie を削除します。
• Flask の session を削除します。状態は DS／DSR Cookie に保持されます。

主な注意点：

• authlib は access_token、id_token、userinfo を Flask のサーバー側セッションに保存していました。Descope は Flask セッションを使用しません。APP_SECRET_KEY と session のインポートを削除してください。
• validate_session() は JWT クレームの辞書を返します。プロフィールのフィールドはデフォルトでは含まれません。先に JWT Template を設定してください。

Next.js

• @auth0/nextjs-auth0 → @descope/nextjs-sdk + @descope/node-sdk
• UserProvider → AuthProvider（projectId プロパティを受け取ります。NEXT_PUBLIC_ プレフィックスを付ける必要があります）
• useUser() → useSession() + useUser()（Descope ではセッション状態とユーザーデータが分離されています）
• pages/api/auth/[...auth0].tsx のキャッチオールを削除します — サーバーサイドの OIDC 処理はありません
• <Descope> コンポーネントで sign-up-or-in フローをレンダリングする /login ページを追加します。必ず onSuccess を設定してください — コンポーネントは自動でリダイレクトしません（references/implementation-nuances.md → Next.js セクションを参照）
• withPageAuthRequired → useSession() による手動チェック + リダイレクト
• withApiAuthRequired → ハンドラーの先頭で session() を呼び出し、手動で 401 を返します
• ログアウト：useDescope() フックで sdk.logout() を使用します（/api/auth/logout へのリンクは使用しません）

クライアントとサーバーでのセッションアクセス — よくあるエラーの原因：

• @descope/nextjs-sdk/server の session() — サーバーコンポーネント、サーバーアクション、API ルートのみ
• @descope/nextjs-sdk/client の useSession() + useUser() — React のクライアントコンポーネント
  • useSession() は { isAuthenticated, sessionToken, ... } を返します
  • useUser() は現在のセッションのユーザーオブジェクトを返します
• クライアントコンポーネントで session() を使うと、コンパイルは成功しますが、実行時に例外が発生します（ブラウザーのコンテキストで Cookie を読み取ろうとするためです）。Next.js の移行を完了する前に、このパターンがないか検索してください。

サーバーサイドのセッション — SDK の正確な API（生成前に確認してください）：

@descope/nextjs-sdk/server エントリがエクスポートするのは、以下のみです。

• session(config?) — サーバーコンポーネントまたはサーバーアクションで、リクエストヘッダーや Cookie からセッションを読み取ります。req 引数はありません。Promise<AuthenticationInfo | undefined> を返します。
• getSession(req, config?) — 明示的に指定した NextApiRequest から読み取ります。API ルート専用です。
• authMiddleware(options) — Next.js ミドルウェアのファクトリーです。

getServerSession は存在しません。もっともらしい名前ですが、エクスポートされていません。インポートを記述する前に、node_modules/@descope/nextjs-sdk/dist/types/server/index.d.ts を開き、エクスポート一覧を確認してください。

セッションの戻り値の型 — Auth0 形式のセッションオブジェクトではなく、AuthenticationInfo：

session() は、@descope/node-sdk の AuthenticationInfo | undefined を返します。

interface AuthenticationInfo {
  jwt: string    // raw session JWT
  token: Token   // decoded claims: { sub?, exp?, iss?, [claim: string]: unknown }
  cookies?: string[]
}

isAuthenticated、claims フィールド、user ラッパーはありません。代わりにアダプター関数を記述します。

import { session as sdkSession } from "@descope/nextjs-sdk/server"

export async function getDescopeSession() {
  const authInfo = await sdkSession()
  if (!authInfo) return null
  return { isAuthenticated: true as const, jwt: authInfo.jwt, token: authInfo.token }
}

その後、すべてのサーバーコンポーネントで SDK を直接使わず、このローカルファイルの getDescopeSession() を使ってください。

API サーバー（Express）が別にあるアプリの場合：

• express-jwt + jwks-rsa を削除し、descopeClient.validateSession() に置き換えます
• Next.js から API に DS Cookie を Authorization: Bearer <DS> として転送します
• 別途アクセストークンはありません — セッショントークンがベアラートークンです

FastAPI / Python

• auth0-fastapi を削除します（AuthConfig、自動マウントされる /api/auth/* ルート、require_session）
• カスタムの TokenVerifier クラスを追加します。Authorization ヘッダーを読み取り、Descope JWKS に対して検証し、FastAPI の Security() 依存関係としてクレームを付与します
• 自動マウントされるルートはありません。セッションストアもありません

Path A：OIDC 互換性（低リスク、段階的）

Descope は標準の OIDC エンドポイントを提供します。アプリが OIDC クライアントライブラリ （express-openid-connect、go-oidc、authlib、@auth0/nextjs-auth0 v4 など）を使用している場合は、 コードをほとんど変更せずに、Auth0 の代わりに Descope の OIDC 発行者を指定できます。

エンドポイント	Auth0	Descope
発行者	https://YOUR_DOMAIN.auth0.com	https://api.descope.com
認可	https://YOUR_DOMAIN.auth0.com/authorize	https://api.descope.com/oauth2/v1/authorize
トークン	https://YOUR_DOMAIN.auth0.com/oauth/token	https://api.descope.com/oauth2/v1/token
UserInfo	https://YOUR_DOMAIN.auth0.com/userinfo	https://api.descope.com/oauth2/v1/userinfo
JWKS	https://YOUR_DOMAIN.auth0.com/.well-known/jwks.json	https://api.descope.com/__ProjectID__/.well-known/jwks.json

Descope 用の @auth0/nextjs-auth0 v4（Auth0Client）設定：

new Auth0Client({
  domain: `https://api.descope.com/${DESCOPE_PROJECT_ID}`,
  clientId: DESCOPE_OIDC_CLIENT_ID,       // from Descope Console → Applications → OIDC App
  clientSecret: DESCOPE_OIDC_CLIENT_SECRET,
  logoutStrategy: "oidc",                 // prevents calling Auth0's /v2/logout
  secret: SESSION_ENCRYPTION_SECRET,      // still needed for server-side session encryption
})

OIDC 経由で Descope に引き継がれない Auth0 固有のパラメーター：

• screen_hint: "signup" — Auth0 固有のため、Descope では無視されます
• organization: orgId — Auth0 の組織スコープ付きログインに相当するものは、Descope の OIDC にはありません
• appClient.updateSession() — 相当するものはありません。ログイン後のセッションは読み取り専用です

適しているケース： まず IdP を切り替え、その後 Descope ネイティブの SDK にリファクタリングしたいチームに適しています。 既存の OIDC クライアントコードを維持できます。

注意点： クレームの形式が異なり、トークンの有効期間も異なる場合があります。また、どちらのパスを選んでも、Auth0 Actions は Descope Flows で再構築する必要があります。

Auth0 Organizations を使用する B2B アプリの場合： Path A で維持できるのは作業の約 20％ （ミドルウェア、getSession()、セッションルート）です。残りの 80％（管理 SDK、組織スコープ付き ログイン、サインアップフロー、クレームマッピング）は、いずれにしても全面的な移行が必要です。B2B のワークロードでは Path A による削減効果は最小限です。作業量を見積もる際に考慮してください。

Go

• go-oidc と golang.org/x/oauth2 を削除し、descope/go-sdk を追加します
• ログイン／コールバック／ログアウトのバックエンドエンドポイント（約 150 行）を削除し、トークン検証のみを残します
• セッション検証：descopeClient.Auth.ValidateSessionWithToken(ctx, token) は (bool, *descope.Token, error) を返します。Token.Claims は map[string]interface{} です
• sub クレームは、認証ハンドラーのユーザー ID に直接対応します
• 認証設定：ClientID + ClientSecret + Domain + RedirectURL から ProjectID のみになります

フレームワークのコード変更を完了したら： MIGRATION-STATE.md を更新します。Files Inventory で変更した各ファイルを Done にし、Current Phase と Next Action を更新して、特筆すべき判断（維持したアダプターの種類、非同期カスケードの範囲など）を記録します。

---

Step 2.5：コード以外のファイルの更新

ソースファイルの更新後、コード以外のファイルに Auth0 への参照がないか確認します。

.env.example / .env.template / .env.sample

# REMOVE
AUTH0_CLIENT_ID=
AUTH0_CLIENT_SECRET=
AUTH0_ISSUER_BASE_URL=
AUTH0_AUDIENCE=
AUTH0_BASE_URL=
SECRET=

# ADD
DESCOPE_PROJECT_ID=            # Console → Project Settings
NEXT_PUBLIC_DESCOPE_PROJECT_ID= # Next.js only — same value as above
DESCOPE_MANAGEMENT_KEY=        # Console → Company → Management Keys (only if using management SDK)

grep -r "AUTH0" を実行して、.env.example、Docker、CI、シェルスクリプト内のすべての環境変数参照を確認します。

README / docs

すべての .md ファイルを検索して、Auth0 への参照を確認します。最低限、次の項目を更新します。

• セットアップセクション — 「Auth0 アプリを作成する」という手順を、Descope Console でのセットアップ手順に置き換えます
• 環境変数セクション — 削減後の環境変数セットを反映します
• 実行手順 — Auth0 テナントの手順を Descope Console の手順に置き換えます
• 認証フローの図または説明 — Descope の Cookie ベースの方式を反映するように更新します

Docker / CI ファイル

Dockerfile、docker-compose.yml、.github/workflows/、および CI 設定内で AUTH0_* 環境変数の宣言を確認し、DESCOPE_* に更新します。

セットアップ／ブートストラップスクリプト

Auth0 CLI コマンド（auth0 tenants patch、auth0 actions create/deploy、auth0 roles create など）に相当する Descope CLI コマンドはありません。移行にセットアップスクリプトやシードスクリプト（例：scripts/bootstrap.mjs、scripts/seed.ts）が含まれる場合は、次の 2 つに分けます。

1. コンソールのセットアップ（スクリプト化できません）：フロー、メールテンプレート、MFA 設定、ブランディング／スタイルは Descope Console で設定します。MIGRATION-PLAN.md にフェーズ 1 のチェックリストとして記載します。
2. SDK による自動化（スクリプト化できます）：ロールの作成（management.role.create()）、テナントの作成、アクセスキーのプロビジョニングは、Descope Management SDK を使った Node.js／Python スクリプトとして維持します。

スクリプトでデプロイされる Auth0 Actions は、再評価が必要です。各 Action のロジックはコードのデプロイではなく、Console のフローステップ、Scriptlet、またはコネクターに対応付けます。Action の意図が曖昧な場合は、AskUserQuestion を使用します。

コード以外のファイルの更新が完了したら： MIGRATION-STATE.md を更新し、「Files Inventory」で環境ファイル、README、CI 設定を完了にして、「Next Action」を進めます。

---

ステップ 3：機能の移行マッピング

Auth0 Actions／Rules → Descope フロー＋JWT テンプレート

Auth0 のパターン	Descope での相当機能
トークン内のカスタムクレーム	JWT Templates
認証中のカスタムロジック	Descope Flows
ログイン後の Webhook	フロー → Connectors
ログイン時のロール割り当て	フローアクション → RBAC ロール割り当てステップ

ソーシャルログイン → Descope Social Auth

• Descope Console の Authentication → Social でプロバイダーを設定します
• フローに追加します（コードの変更は不要です）
• Descope の Web コンポーネントが、設定済みのプロバイダーを自動的に表示します

MFA 登録 → Descope フロー

MFA 登録を移行する前に： 多くの Auth0 アプリには、Auth0 Guardian がサーバー生成の登録チケット URL を使うため、独立した MFA 登録ページがあります。このパターンに Descope での相当機能はなく、Descope では独立したページが適切な方法であることはまれです。

Descope での方法：MFA ステップをサインアップ／サインインフローに直接追加します。認証フローの中で登録が行われます。または、MFA をサブフローとして埋め込みます（ユーザーが管理者である、リスクスコアがしきい値を超えるなどの条件によって起動します）。あるいは、step-up フローテンプレートを使用して、機密性の高い操作を制限します。

アクション： MFA 登録コードを書く前に、AskUserQuestion を使用して、MFA をメインのサインインフローに統合できるか確認します。references/flows-and-widgets.md → MFA 登録のセクションを参照してください。

RBAC：Auth0 のロール／権限 → Descope RBAC

Auth0	Descope
req.auth.permissions.includes('read:messages')	token.permissions.includes('read:messages')
Actions での名前空間を使用したロールクレーム	JWT 内の roles 配列（組み込み）
Management API 用の M2M トークン	Management SDK 用の DESCOPE_MANAGEMENT_KEY

SDK：descopeClient.management.role.create(name, description, permissionNames, tenantId)

マルチテナンシー：Auth0 Organizations → Descope Tenants

• Auth0 の org_id（フラットな文字列）→ Descope の tenants（ネストされたオブジェクト：{ tenantId: { roles, permissions } }）
• Auth0 の組織単位のログイン → Descope ではメールドメインまたはテナント固有の URL によって振り分けます
• Descope ではユーザーはプロジェクト単位で管理されます。テナントに関連付けられますが、テナントごとに作成されるわけではありません

エンタープライズ SSO → Descope テナント SSO

推奨アプローチ — SSO Setup Suite： 管理 SDK の SSO 呼び出しを移行する前に、SSO Setup Suite によって該当コードが不要になるかどうかを確認してください。SSO Setup Suite は、テナント管理者がテナントごとに SAML／OIDC を設定できるよう、IdP ごとの手順（Okta、Microsoft Entra ID（旧 Azure AD）、Google Workspace など）を順を追って案内するノーコードの Console ウィザードです。新しいテナントの SSO オンボーディングにエンジニアが関与する必要はありません。

AskUserQuestion を使って、このアプリにプログラムによる SSO 設定（CI/CD によるプロビジョニング、API 主導のテナントオンボーディング）が必要か、それともテナント管理者が設定ページから SSO を自分で設定するのかを尋ねてください。後者の場合、SSO Setup Suite と Tenant Profile Widget により、sso.configureSAMLByTenant() ／ configureOIDCByTenant() の呼び出しが不要になる可能性があります。

references/flows-and-widgets.md → SSO Setup Suite を参照してください。

SDK の方法（プログラムによる SSO 設定が必要な場合）：

Auth0	Descope
connections.create({ strategy: "samlp" })	management.sso.configureSAMLByTenant(tenantId, settings)
connections.create({ strategy: "oidc" })	management.sso.configureOIDCByTenant(tenantId, settings)
組織ごとの SAML 接続	テナントごとの SSO（Console → SSO または Management SDK）

Auth0 FGA (OpenFGA) → Descope ReBAC

スキーマの変換例：

# Auth0/OpenFGA
type doc
  relations
    define owner: [user]
    define viewer: [user, user:*]
    define can_view: owner or viewer

# Descope ReBAC DSL
type doc
  relation owner: user
  relation viewer: user
  permission can_view: owner or viewer

API の形式の違い：

• OpenFGA：{ user, relation, object } タプル
• Descope：{ target, targetType, relation, resource, resourceType } — 型を明示するフィールド

操作	Auth0 FGA	Descope ReBAC
関係を書き込む	fgaClient.write({ writes: [...] })	descopeClient.management.fga.createRelations([...])
チェック	fgaClient.check({ user, relation, object })	descopeClient.management.fga.check([...])
オブジェクトを一覧表示	fgaClient.listObjects(...)	descopeClient.management.authz.whatCanTargetAccessWithRelation(...)

注：@auth0/ai-langchain の FGARetriever に相当する Descope の機能はありません。候補ドキュメントごとに descopeClient.management.fga.check() を呼び出すカスタムリトリーバーを作成してください。

Token Vault／Connected Accounts → Descope Outbound Apps

クライアントで sdk.outbound.connect(appId, { redirectURL, scopes }) を使って、ユーザーがアカウントを接続します。

保存されたトークンをサーバー側で取得します：

POST https://api.descope.com/v1/mgmt/outbound/app/user/token
Authorization: Bearer {projectId}:{managementKey}
Body: { "appId": "google-calendar", "userId": "U2abc...", "scopes": [...] }

AI フレームワーク用のラッパー（@auth0/ai の withTokenVault() に相当するもの）はありません。Outbound Apps API を直接呼び出すカスタムツールラッパーを作成してください。

CIBA／非同期認証 → カスタム実装が必要

Descope にCIBA に相当する機能はありません。推奨される方法：

1. エージェントがデータベースに保留中の承認レコードを作成します
2. フロントエンドがそのレコードをポーリングするか、WebSocket を使用します
3. ユーザーが Descope Flow またはカスタム UI で承認します
4. エージェントが承認シグナルを受け取り、処理を続行します

これは移行項目の中で最も複雑です。

M2M／クライアントクレデンシャル → Descope Access Keys

Auth0 の M2M アプリはクライアントクレデンシャルグラントを使用します。Descope で相当するのは Access Keys です。Console → Access Keys で作成し、 descopeClient.auth.exchangeAccessKey() を使って JWT と交換してから、ユーザートークンと同じ方法で生成されたトークンを検証します。

ユーザー移行 → Descope 移行スクリプト

Descope には、ユーザー、ロール、権限、Auth0 の組織（→ Descope のテナント）を一度に一括インポートする Python CLI ツール（descope/descope-migration）が用意されています。

2 つのインポートモード：

• Auth0 API — ユーザー数が 1,000 人未満の場合に使用します
• JSON エクスポート — ユーザー数が 1,000 人以上の場合に使用します。Auth0 の User Import/Export extension を使ってエクスポートします

セットアップ：

git clone [email protected]:descope/descope-migration.git
cd descope-migration
python3 -m venv venv && source venv/bin/activate
pip3 install -r requirements.txt
cp .env.example .env

必要な .env 変数：

変数	取得場所
AUTH0_TOKEN	Auth0 Management API → token explorer（24 時間有効なトークン）
AUTH0_TENANT_ID	Auth0 ダッシュボードの URL
DESCOPE_PROJECT_ID	Descope Console → Project Settings
DESCOPE_MANAGEMENT_KEY	Descope Console → Company → Management Keys

必ず最初にドライランを実行してください：

python3 src/main.py auth0 --dry-run
python3 src/main.py auth0 --dry-run --from-json ./export.json --with-passwords ./password_hashes.json

移行対象： ユーザー、ロール、権限、Auth0 の組織 → Descope のテナント。

自動作成されるカスタム属性：

• connection（テキスト）— 各ユーザーの Auth0 接続タイプ
• freshlyMigrated（ブール値）— インポート時に true に設定されます。Flow の条件分岐でこれを使用し、移行したばかりのユーザーに特別な初回ログイン体験を提供できます。完了後に false に切り替えてください

セッション移行（ベータ版）： サービスを中断せずに切り替えるには、アクティブな Auth0 セッションを再認証なしで Descope トークンに交換できます。ユーザーがすでに Descope に存在している必要があります（先にインポートしてください）。セッション移行のドキュメントを参照してください。

大規模なユーザーベース（10,000 人以上）— Auth0 Action によるジャストインタイム移行： 一括エクスポート／インポートでは業務に支障が出る可能性のある大規模なユーザー集団では、Auth0 の Action を作成し、切り替え期間中、ログインのたびにユーザーデータを Descope に転送できます。これにより、強制的な再ログインを求めることなく、ユーザーを段階的にジャストインタイムで移行できます。この方法には Descope の Customer Success チームとの調整が必要です。ユーザーがサービス中断のない切り替えを希望する場合は、この方法を案内してください。

メールテンプレート → Descope Messaging Templates

Auth0 のメールテンプレートは Descope の Messaging Templates に対応します。Console で認証方式ごとに設定します。

Log Streams → Descope Audit Webhook

Auth0 の Log Streams は Descope の Audit Webhook Connector に対応します。 イベントログの欠落を防ぐため、切り替え前に設定してください。

カスタムドメイン

CNAME auth.example.com を cname.descope.com に設定し、Console で検証してから、Descope SDK に baseUrl を渡します。

Attack Protection → Descope Flow Security

Auth0 の Attack Protection は、セキュリティコネクターを使用する Descope Flow のステップに対応します。対象は Arkose Bot Manager、 Google reCAPTCHA、Fingerprint、Have I Been Pwned、AbuseIPDB です。これらは切り替え式ではなく組み合わせて使用する方式で、Flows に検出ステップを追加します。デフォルトでは設定されません。

機能の移行を完了した後： MIGRATION-STATE.md を更新し、移行した機能を記録し、保留中または追加対応が必要な機能に印を付け、次のアクションをテストに進めてください。

---

ステップ 4：重要な注意点（必ず説明すること）

JWT クレームは同じではありません

Descope のセッション JWT には、デフォルトで sub、amr、drn、tenants、roles、permissions、dct が含まれます。デフォルトでは email、name、picture は含まれません。Auth0 の ID トークンには、これらがデフォルトで含まれます。

dct（Descope Current Tenant）は、アクティブなテナント ID を保持するフラットな文字列で、Auth0 の org_id に直接対応します。ユーザーが常に単一のテナントコンテキストに属するアプリでは、token.tenants を反復処理するよりも token.dct を読み取るほうが簡単です。テナントごとのロールや権限が必要な場合は token.tenants を使用してください（これはキー付きオブジェクトです：{ [tenantId]: { roles, permissions } }）。テナント ID だけが必要な場合は token.dct を使用してください。

必要な対応： Descope Console で JWT Template を設定し、email、name、およびアプリがトークンから読み取るその他のプロフィールフィールドを追加してください。

オーディエンスの検証はオプトイン方式です

Descope のセッショントークンには、デフォルトで aud クレームがありません。API のアクセス制御に AUTH0_AUDIENCE を使用しているアプリでは、次の対応が必要です。

1. JWT Templates でカスタムの aud クレームを設定します
2. バックエンドで validateSession() に audience を渡します

ログアウトは 2 段階です

1. descopeClient.logout(refreshToken) を呼び出して、サーバー側で無効化します
2. DS と DSR の Cookie をクリアします

どちらかを省略すると、状態が不整合になります。

サーバー側のプロフィール更新は、セッショントークンにすぐには反映されません

Auth0 の appClient.updateSession() に相当するサーバー側の機能は、Descope にはありません。Management SDK を使っても、ブラウザー内の JWT はプロフィールの変更で更新されません。次の 4 つの方法があります。

1. 自動更新を待つ（デフォルトで約 5 分）— コードは不要で、ほとんどのアプリでは許容できます。
2. クライアント側で useDescope().refresh() を呼び出す — トークンをすぐに更新します。プロフィールフォームを、useDescope() フックを使うクライアントコンポーネントにする必要があります。コードの全パターンは references/implementation-nuances.md → Session refresh セクションを参照してください。
3. JWT 更新エンドポイント（POST /v1/mgmt/user/jwt/update）— サーバー側で、特定のユーザーの保存済み JWT カスタムクレームを更新します。使用する前に、現在の動作を Descope のドキュメントで確認してください。これは保存済みのクレームを更新するもので、ライブセッショントークンは更新しません。
4. User Profile Widget — アプリにプロフィール編集ページを実装する場合、この Widget を使うと、カスタムコードなしでプロフィールの更新とセッションの更新を自動的に処理できます。references/flows-and-widgets.md → Widgets を参照してください。

セッション変更イベントリスナー： refresh() を直接呼び出す代わりに、Descope クライアント SDK が公開する認証状態変更イベントを使用すると、コンポーネント間のセッション更新に対応できます。docs.descope.com/client-sdk/auth-helpers#handling-authentication-state-changes を参照してください。

Cookie 名は設定可能です（競合する場合があります）

デフォルトは DS（セッション JWT）と DSR（更新 JWT）です。同じルートドメインで複数の Descope プロジェクトを実行する場合は、Descope Console で Flow の End アクションからカスタム名を設定してください。

トークンは 2 つではなく 1 つです

Auth0 は ID トークンとアクセストークンを個別に発行します。Descope のトークンは 1 つ、つまりセッション JWT（DS Cookie）です。これを Authorization: Bearer <DS> として API サーバーに転送してください。

そのまま使えるミドルウェアはありません

Descope には express-openid-connect に相当するパッケージはありません。ミドルウェアは約 20 行のカスタムコードで実装します。

Next.js 15 では cookies() と headers() は非同期です

Next.js 15 以降では、next/headers の cookies() と headers() は Promise を返します。Cookie を読み取るサーバー側ヘルパーを生成する前に、次の手順を実行してください。

1. プロジェクトの package.json で Next.js のバージョンを確認します。
2. ≥ 15 の場合は、await cookies() を記述し、含んでいる関数に async を指定します。
3. 呼び出し元を上へたどってください。Cookie を読み取るヘルパーを非同期にすると、その呼び出し元すべてにも影響します。

非同期化の連鎖：完了前にすべての呼び出し元を確認してください

共有ユーティリティを非同期にしても、TypeScript は非 Promise に対する await をエラーにしません。そのため、await を忘れた呼び出し元は、気付かないまま Promise オブジェクトを返します。ユーティリティを非同期にした場合は、必ずすべての呼び出し箇所を grep で検索し、同じ作業中に更新してください。

環境変数の削減

Auth0：CLIENT_ID、CLIENT_SECRET、ISSUER_BASE_URL、SECRET、AUTH0_AUDIENCE（5 個以上）。 Descope：DESCOPE_PROJECT_ID のみ（管理操作には DESCOPE_MANAGEMENT_KEY も必要）。

---

ステップ 5：自動テスト

アプリを実行し、動作することを確認してください。チェックリストを渡すだけではいけません。

フェーズ 0：古いインポートの最終確認（必須）

grep -r "@auth0\|auth0\|express-openid-connect\|nextjs-auth0" \
  --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" --include="*.go" \
  --exclude-dir=node_modules --exclude-dir=.next --exclude-dir=dist \
  .

検索結果がある場合は、先に進まず、修正してください。

フェーズ 1：インストール、コンパイル、起動

npm install   # or: pip install -r requirements.txt / go mod tidy

npx tsc --noEmit    # TypeScript
go build ./...      # Go
mvn compile -q      # Java/Maven
./gradlew compileJava compileKotlin  # Java/Gradle
dotnet build        # .NET

コンパイルがエラーなしで終了するまで、先に進まないでください。

コンパイルに失敗した場合は、エラーメッセージに基づいて原因を特定してください：

• Cannot find module '@auth0/...' → 古いインポートです。フェーズ 0 を再実行してください
• Property 'X' does not exist on type 'AuthenticationInfo' → Auth0 の形式に基づいてラッパーがビルドされています。もう一度導出してください
• 'await' expression is not allowed in synchronous contexts → 非同期処理の連鎖に抜けがあります
• セッションフィールドの Object is possibly 'undefined' → null チェックまたは早期リターンを追加してください

npm run dev   # or: python main.py / go run . / flask run / etc.

フェーズ 2：既存のテストを実行する

npm test   # or: pytest / go test ./... / etc.

認証関連のテスト失敗は通常、モックまたはフィクスチャがまだ Auth0 の形式を使用しているか、JWT Template がないために欠落している JWT クレーム（例：email）をテストが検証していることを意味します。

フェーズ 3：実行中のアプリをスモークテストする

# Root path
curl -s -o /dev/null -w "%{http_code}" http://localhost:<port>/

# Unauthenticated protected route (expect 302 or 401)
curl -s -o /dev/null -w "%{http_code}" http://localhost:<port>/dashboard

# Login page loads Descope component
curl -s http://localhost:<port>/login | grep -i "descope"

# Invalid token → 401
curl -s -H "Cookie: DS=invalid_token" http://localhost:<port>/api/me

フェーズ 4：JWT クレームを検証する（JWT Template が設定されている場合）

echo "<DS_cookie_value>" | cut -d'.' -f2 | base64 -d 2>/dev/null | python3 -m json.tool

email、name、およびその他の想定されるクレームが存在することを確認してください。

フェーズ 5：結果を報告する

## Test Results

**Server startup:** ✅ Started successfully on port 3000
**Existing tests:** ✅ 12 passed / ❌ 2 failed (list failures)
**Unauthenticated /dashboard:** ✅ 302 → /login
**Unauthenticated /api/protected:** ✅ 401
**Login page loads Descope component:** ✅
**JWT claims (email, name):** ✅ Present / ❌ Missing — JWT Template not yet configured

**Blockers before going live:**
- [ ] (list anything that failed or needs manual action)

以下のすべてを満たすまで、ステップ 6 に進まないでください：

• フェーズ 0 の grep で Auth0 の参照が 0 件
• フェーズ 1 のコンパイルがエラーなしで成功
• フェーズ 1 のサーバーが起動し、実行状態を維持
• フェーズ 3 のルートパスが 2xx または 3xx を返す（5xx ではない）
• フェーズ 3 の保護されたルートが 302 または 401 を返す（500 ではない）

---

ステップ 6：移行後の概要（必須）

すべての移行で、実施内容、残っている手動セットアップ、本番環境への移行前に把握すべき動作上の違いをまとめた MIGRATION-SUMMARY.md を作成します。

MIGRATION-SUMMARY.md

1. 移行した内容 — 各 Auth0 の概念と、それに対応する Descope の代替機能を示す表

2. 動作上の違いと未解決の質問 — Auth0 と Descope の実装における重要な違いを番号付きリストにします。各項目に、Auth0 での動作、Descope での動作、必要な対応を記載します。

3. デプロイ前チェックリスト — 移行後のアプリを実行する前に必要なすべての作業を、実行可能なチェックボックス項目で示します。Console でのセットアップ作業は目立つように記載してください。コードがそれらなしでもコンパイルできるため、これらの作業は特に忘れやすいものです。

---

ステップ 7：出力形式

ユーザーの技術スタックに合わせて、番号付きの移行ガイドを Markdown で作成します。コードスニペットと該当するドキュメントへの直接リンクを使用してください。必ず MIGRATION-SUMMARY.md の成果物（ステップ 6）を含めてください。

複雑な移行（FGA、CIBA、AI ツール）では、工数が大きい項目を見積もりの複雑さ（低／中／高）とともに明示し、ユーザーが計画を立てられるようにしてください。

---

参考ファイル

• references/implementation-nuances.md — 複数のフレームワークについて、検証済みの移行パターン、コードレベルの差分、エッジケースをまとめています。
• Descope ドキュメント：https://docs.descope.com
• Auth0 移行ガイド：https://docs.descope.com/migrate/auth0
• ユーザーのインポート（カスタム）：https://docs.descope.com/migrate/custom
• Descope OIDC エンドポイント：https://docs.descope.com/getting-started/oidc-endpoints
• Descope フロー：https://docs.descope.com/flows
• JWT Templates：https://docs.descope.com/management/jwt-templates
• Access Keys（M2M）：https://docs.descope.com/management/m2m-access-keys
• Messaging Templates：https://docs.descope.com/management/messaging-templates
• Audit Webhook：https://docs.descope.com/connectors/connector-configuration-guides/network/audit-webhook
• Custom Domains：https://docs.descope.com/how-to-deploy-to-production/custom-domain
• ReBAC：https://docs.descope.com/authorization/rebac
• Outbound Apps：https://docs.descope.com/identity-federation/outbound-apps

言語別のセッション検証

• Node.js：https://docs.descope.com/getting-started/nodejs#implement-session-validation
• Python：https://docs.descope.com/getting-started/python#implement-session-validation
• Go：https://docs.descope.com/getting-started/golang#implement-session-validation
• Ruby：https://docs.descope.com/getting-started/ruby#implement-session-validation
• Java / Kotlin：https://docs.descope.com/getting-started/java#implement-session-validation
• .NET / C#：https://docs.descope.com/getting-started/dotnet#implement-session-validation
• Next.js：https://docs.descope.com/getting-started/nextjs#implement-session-validation
• React：https://docs.descope.com/getting-started/react#implement-session-validation
• Angular：https://docs.descope.com/getting-started/angular#implement-session-validation
• Vue：https://docs.descope.com/getting-started/vue#implement-session-validation
• Swift / iOS：https://docs.descope.com/getting-started/swift#implement-session-validation
• Kotlin / Android：https://docs.descope.com/getting-started/android#implement-session-validation
• Flutter：https://docs.descope.com/getting-started/flutter#implement-session-validation

SDK（GitHub）

• Node SDK：https://github.com/descope/node-sdk
• Python SDK：https://github.com/descope/python-sdk
• Go SDK：https://github.com/descope/go-sdk
• Ruby SDK：https://github.com/descope/descope-ruby-sdk
• Java SDK：https://github.com/descope/descope-java
• .NET SDK：https://github.com/descope/descope-dotnet
• Swift SDK：https://github.com/descope/swift-sdk
• Kotlin SDK：https://github.com/descope/descope-kotlin
• Flutter SDK：https://github.com/descope/descope-flutter
• JS/TS モノレポ（React、Angular、Vue、Next.js、Web Component、Web JS）：https://github.com/descope/descope-js