Auth0 To Descope

Auth0 → Descope Migration Skill

This skill guides self-service migrations from Auth0 to Descope. It runs in three parts:

1. MCP Check — confirm whether the Descope Docs MCP is available and suggest installing it if not
2. Migration Plan — gather context via triage questions, analyze the codebase's auth touchpoints, and produce a human-readable MIGRATION-PLAN.md for the user to review
3. Execution — if the user confirms they want to proceed, execute the plan

Do not collapse these parts or skip ahead. The plan must be reviewed before code changes begin.

Primary references (both in this skill's directory):

• references/implementation-nuances.md — verified migration patterns for each framework, Auth0 feature-to-Descope mappings, and known gotchas
• references/flows-and-widgets.md — Descope terminology/lingo, Flow structure and templates, Widgets, SSO Setup Suite, Console-vs-code decision guide

---

Guiding Principles

Console-first. Before recommending SDK code for any user-facing auth feature, check whether the Console, a Flow, or a Widget covers the use case. Engineers integrate once (SDK setup + session validation). All subsequent auth evolution — new methods, MFA changes, UI updates — should happen in the Console without code deployments. See references/flows-and-widgets.md → Console vs. Code.

Ask, don't assume. At any design decision point — embed Flows vs. OIDC compatibility, Flow vs. custom code, Widget vs. custom page, MFA inline vs. separate enrollment, programmatic SSO vs. SSO Setup Suite — use AskUserQuestion rather than proceeding with an assumption. The cost of a wrong assumption compounds across 20+ files. Uncertainty about architecture or intent is always worth a question.

MCP over memory. When the Docs MCP is available (confirmed in Part 1), use ask-question-about-descope to verify every SDK method name, option shape, and return type before writing it. Do not fall back to "verify the exact method name in the SDK type declarations" as a hedge — just verify it directly.

---

Part 1: MCP Check (BLOCKING)

Before doing anything else, check whether the Descope Docs MCP is available by calling search-descope-docs with a simple query (e.g., "session validation").

If the tool is available: proceed to Part 2 immediately.

If the tool is not available, show this message and use AskUserQuestion to ask whether they want to install it first:

> Descope Docs MCP is not installed. > > This skill uses the Descope Docs MCP to look up current API signatures, SDK methods, and > feature availability during migration. Without it, guidance is based on static training data, > which may be stale and can produce SDK calls that don't exist. > > You can install it in a few minutes at https://docs-mcp.descope.com/ (server URL: > https://docs-mcp.descope.com/mcp). It significantly improves the accuracy of the > migration output — especially for SDK lookups and flow-specific configuration. > > Would you like to install the MCP before we continue, or proceed without it?

• If they choose to install: pause and wait. Once they confirm it's installed, re-check by calling search-descope-docs again before proceeding.
• If they choose to proceed without it: continue, but flag any SDK-specific answers as "based on last known documentation — verify against the current SDK."

Do not proceed to Part 2 until this step is resolved.

---

Part 2: Migration Plan

Part 2 has two sub-steps:

1. Triage — ask the questions needed to understand scope (migration questions go here since answers shape the plan)
2. Codebase Analysis + Plan File — scan the project, produce MIGRATION-PLAN.md, and pause for review

Step 0: Triage (BLOCKING — requires AskUserQuestion)

Use the AskUserQuestion tool to gather the information below. Do not infer answers from memory, prior conversations, or assumptions — even if you think you know. The migration path differs based on these answers; getting them wrong wastes the user's time and produces incorrect guidance.

Do not proceed to Step 0.5 until the user has answered.

First AskUserQuestion call (up to 4 questions):

1. Backend language / framework — Present the most likely options based on any cues

in the conversation (e.g., Express, Next.js, Flask/FastAPI, Go). The user can always pick "Other."

1. Migration goal — Full cut-over, incremental/phased migration, or just evaluating.
2. Existing user base — Are they migrating an app with active users in Auth0, or

starting fresh? This determines whether user migration planning is needed (password hashes, bulk import, phased vs. big-bang cutover, forced re-login on cutover).

1. Preferred migration style — Do they want to embed Descope Flows/Widgets directly (full native migration), or preserve their existing OIDC client library and point it at Descope's OIDC endpoints (OIDC compatibility layer)? Note: B2B features (Organizations/SSO/SCIM management) have no OIDC-layer equivalent and require native SDK calls regardless of path.

Second AskUserQuestion call — Auth0 feature usage (use multiSelect: true):

1. Which Auth0 features are in use? Present the highest-impact categories:

• Actions / Rules / Hooks (custom login logic)
• Organizations (multi-tenancy / B2B)
• FGA / fine-grained authorization
• Social login / Enterprise SSO

The user can add others via "Other." Follow up on anything selected — e.g., if Organizations is selected, ask about tenant-scoped SSO, SCIM, and invitations. If FGA is selected, ask about the authorization model.

Also surface in a follow-up AskUserQuestion if not yet covered:

• Token Vault / Connected Accounts usage
• M2M / client credentials apps
• Custom email templates, Log Streams, Attack Protection, custom domains

After both calls, summarize findings and flag high-complexity items (CIBA, Token Vault, FGA) before proceeding to Step 0.5.

---

Step 0.5: Engineer Review Checkpoint (BLOCKING — requires AskUserQuestion)

These questions surface blockers the framework doesn't expose. Ask even the ones you think you know. Use AskUserQuestion before proceeding to codebase analysis.

Batch into calls of up to 4 questions. Skip questions that are clearly inapplicable given Step 0 answers (e.g., skip user migration planning if they said they're starting fresh).

Access and credentials

• Do they have access to the Descope Console and a Project ID? (If not, see Step 1.5.)
• Do they need a Management Key? (Required for user CRUD, role management, ReBAC, Outbound Apps.)

Codebase scope

• Are there places in the app that read claims directly from the session token (e.g. token.email, req.auth.permissions)? These need a JWT Template configured before they'll work.
• Do they have Auth0 Actions, Rules, or Hooks? Each one needs to be recreated as a Descope Flow step or JWT Template.
• Are there multiple services or microservices validating Auth0 tokens? Each needs to be updated to validate Descope JWTs.

Deployment and risk

• Do they have multiple environments (dev / staging / prod)? Each needs its own Descope project and Project ID.
• Is there a maintenance window, or does this need to be zero-downtime?

User migration (if they indicated existing users in Step 0)

• How many users? Under 1,000 → the migration script can pull directly from the Auth0 API. Over 1,000 → Auth0 API pagination breaks; they'll need to export a JSON file via Auth0's User Import/Export extension first.
• Do they use passwords? If yes, they need to open a support ticket with Auth0 to get password hash exports — this takes time, plan for it. Without hashes, users will need to reset passwords or switch to passwordless.
• Big-bang cutover or phased? For zero-disruption, Descope supports session migration (beta) — active Auth0 sessions can be exchanged for Descope tokens without re-auth, but users must already exist in Descope. For phased, the freshlyMigrated custom attribute (set automatically by the migration script) can be used in Flow conditionals to give first-time post-migration users a special onboarding path.
• Are they aware that Auth0 sessions will be invalidated on cutover if not using session migration? Plan for a forced re-login or phased rollout.
• Point them to the descope/descope-migration script (Step 3) and recommend a dry run (--dry-run) before any live run.

Gaps to flag immediately (don't ask — flag these proactively based on Step 0 answers)

• If they're using CIBA or @auth0/ai wrappers: flag before going further — these have no Descope equivalent and require custom implementation (see Step 3).
• If they're using Auth0 Token Vault in an AI agent: the migration is Medium complexity; no SDK wrapper exists.
• If they're using Auth0 Log Streams: set up Descope's Audit Webhook Connector before cutover to avoid gaps in event logging.

Console/Flow/Widget opportunities (flag before codebase analysis, then ask):

• If the app has a custom SSO settings page: ask whether the SSO Setup Suite + Tenant Profile Widget replaces that code.
• If the app has a profile edit page or user management UI: ask whether a Descope Widget covers the use case.
• If the app has a separate MFA enrollment page: ask whether MFA should be integrated into the main sign-in Flow as a step or subflow instead (almost always cleaner in Descope).
• If any server-side code generates emails, initiates SSO, or runs logic during the auth journey: ask whether that logic can be a Flow step or Connector instead of server code.

Summarize any blockers and Console/Flow opportunities before proceeding to codebase analysis.

---

Step 1: Codebase Analysis

Scan the codebase to map every auth touchpoint before writing the plan.

Run these searches (adapt file extensions to the user's language):

# 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" {} \;

For each hit, record:

• File path and line — where the change happens
• What it does — import, route protection, claim access, logout handler, etc.
• Complexity — Low (drop-in replacement), Medium (logic rewrite), High (no equivalent)

Read package.json (or equivalent) for the exact framework version — this affects async behavior (Next.js 15 vs 14) and SDK compatibility.

If the Descope Docs MCP is available, use search-descope-docs or ask-question-about-descope to verify current SDK method names for anything you plan to reference in the plan.

---

Step 2: Write MIGRATION-PLAN.md

Write MIGRATION-PLAN.md to the working directory using the triage answers and codebase analysis.

Two audiences: the engineer needs enough technical detail to execute; the PM or tech lead needs scope, risk, and timeline without decoding jargon. Use plain English. Explain technical terms on first use. Open each section with a sentence summarizing what it means before presenting tables or evidence. Say what breaks if a risk is missed, not just that it exists. Pair complexity labels with time estimates; skew toward the lower bound — SDK swaps and mechanical rewrites are usually faster than they look, and repetitive files in a group after the first go much faster. Group execution into phases so parallel vs. sequential work is clear.

The plan must include these sections, in this order:

Overview

2–3 sentences: what's being replaced, what replaces it, and the recommended approach with a one-sentence rationale. Add one sentence on what doesn't change — user-facing login behavior, sessions, and existing accounts are preserved.

Include a Migration at a Glance table:

| | | |---|---| | Approach | Full native migration / OIDC compatibility layer | | Files changing | N source files across N areas | | Console setup | N configuration steps before launch | | User impact | No re-login required / Users will need to log in once after cutover | | Estimated engineering effort | N–N hours | | Biggest risk | One sentence naming the highest-complexity item |

---

What's Changing and Why

Prose (not a table) describing what each part of the system does today and what it does after. Example:

> Today, Auth0 handles everything related to login: it shows the login UI, issues tokens, > and validates them on every API request. After this migration, Descope takes over all of > those responsibilities. The login UI becomes a Descope component embedded in the app. > Token validation moves to the Descope SDK. The five Auth0 environment variables are > replaced by a single Descope Project ID. > > Auth0 features in use that need to carry over: [list in plain English, one clause each].

Tailor to triage findings.

---

Auth Touchpoints: What the Code Analysis Found

Open with the scope count (e.g., "11 files across 4 areas"). Group by area, not file path. Each group gets a sentence on what it does and what changes.

Session handling (3 files) — These files read and validate the current user's login state. They'll be updated to use the Descope session SDK instead of Auth0's.

| File | What it does today | What changes | |---|---|---| | lib/auth.ts:34 | Returns Auth0 session with isAuthenticated, user, claims | Rewritten to return Descope AuthenticationInfo; a thin adapter layer preserves the shape callers expect | | middleware.ts:12 | Blocks unauthenticated requests app-wide | Updated to call Descope session validation; logic is identical, SDK call changes |

Login / logout routes (2 files) — These handle the Auth0 redirect-based login flow. Descope replaces this with an embedded UI component; no redirect cycle is needed.

| File | What it does today | What changes | |---|---|---| | pages/api/auth/[...auth0].ts | Catch-all handler for OAuth callback, logout, session refresh | Deleted — Descope handles this client-side; no server route needed |

Cover all functional groupings. End with: "Total: N files. Estimated code-change effort: N–N hours."

---

Feature Migration: Auth0 → Descope

For each Auth0 feature confirmed in triage, write a short paragraph: what it's trying to accomplish, the best Descope approach for that goal, what's different, and what action is required. The best approach may be a Flow, Widget, SSO Setup Suite, or Console configuration rather than a direct SDK equivalent — reason about the intent, not just the API surface. Only recommend SDK code when programmatic control is genuinely required. Example:

> Multi-tenancy (Auth0 Organizations → Descope Tenants) > Aut

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: descope
• Source: descope/skills
• License: MIT

Install and usage instructions live in the source repository linked above.