Skip to content

Introduces <TaskSetupMfa /> component and the setup-mfa session task #3022

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
octoper wants to merge 5 commits into
base: core-3
Choose a base branch
from
Open

Introduces <TaskSetupMfa /> component and the setup-mfa session task #3022

octoper wants to merge 5 commits into from

Conversation

@octoper
Copy link
Member

@octoper octoper commented Jan 30, 2026 •
edited by alexisintech
Loading

🔎 Previews:

TODO:

  • Add a custom flow example on how to fulfill the session task

What does this solve?

This PR adds documentation for the new setup-mfa session task feature, which allows applications to require all users to set up multi-factor authentication after signing in or signing up. This simplifies the MFA enforcement flow by using Clerk's session task system instead of requiring developers to write custom middleware.

What changed?

clerk/javascript#7626

New Documentation:

  • Created comprehensive component reference for <TaskSetupMfa /> with examples for Next.js, React, React Router, TanStack React Start, and JavaScript SDK
  • Added setup-mfa task to the session tasks table and guides

Updated Documentation:

  • Completely rewrote the "Force multi-factor authentication (MFA) for all users" guide (force-mfa.mdx) to use the new session task approach instead of the complex middleware approach
  • The new guide is much simpler: enable MFA strategies in Dashboard → toggle "Require multi-factor authentication" → optionally customize the task route
  • Updated session tasks documentation to include the new setup-mfa task
  • Updated custom flows guide to reference MFA setup flows for the setup-mfa task
  • Added manifest entry for the new component documentation

Technical Changes:

  • Removed middleware-based approach (no more custom session token claims or middleware logic needed)
  • Documentation now uses the prebuilt <TaskSetupMfa /> component which handles the entire flow automatically

@octoper octoper requested a review from a team as a code owner January 30, 2026 13:35
@vercel
Copy link

vercel bot commented Jan 30, 2026 •
edited
Loading

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
clerk-docs Ready Ready Preview Feb 3, 2026 11:52pm

Request Review

@octoper octoper marked this pull request as draft January 30, 2026 13:37
@octoper octoper self-assigned this Jan 30, 2026
@alexisintech alexisintech self-assigned this Jan 30, 2026
@octoper
Intorduces <TaskSetupMfa /> and setup-mfa session task
a722ab8
@octoper
Enhance MFA documentation with UI component image and clarify session…
b40bd84 
… task details
@octoper
Add setup MFA session task guide and update related documentation
f5f8475 
- Introduced a new guide for building a custom flow for the setup MFA session task.
- Updated links in the session tasks table and MFA requirement documentation to point to the new guide.
- Made minor formatting adjustments in various documentation files for clarity.
@octoper octoper force-pushed the vaggelis/introduce-setup-mfa-session-task branch from 2bcab1d to f5f8475 Compare February 2, 2026 16:35
@octoper octoper marked this pull request as ready for review February 2, 2026 16:35
@octoper octoper added the Blocked label Feb 2, 2026
@alexisintech alexisintech changed the title Intorduces <TaskSetupMfa /> component and the setup-mfa session task Introduces <TaskSetupMfa /> component and the setup-mfa session task Feb 3, 2026
@alexisintech
Copy link
Member

alexisintech commented Feb 3, 2026 •
edited
Loading

I've posted my docs review!

  • updated the Multi-factor authenticator section in /auth-strategies/sign-up-sign-in-options to be the source of truth for setting up MFA and enabling the Require setting.
    • deleted the /force-mfa guide in favor of this section
  • updated the session tasks guide to have searchable keywords for each of the session tasks
  • consolidated the /manage-sms-based-mfa and /manage-totp-based-mfa guides
    • now it just the /manage-mfa guide
    • this creates a single source of truth for a custom flow for managing MFA
    • ensured the flows handle completing a user's setup-mfa task
      Screenshot 2026-02-03 at 17 44 48
    • added that the authentication checks don't block "signed-out" users from the pages
      Screenshot 2026-02-03 at 17 44 56
    • tested the nextjs examples, they're working great. just need to test expo once chris has updated the expo sdk to a working state. the expo examples are the nextjs examples, just translated to react native, but i still want to test them!
    • deleted the /setup-mfa-session-task guide in favor of this /manage-mfa guide
  • added necessary redirects for the deleted files

TODO:

  • Alexis: test expo examples once chris has updated the expo sdk to a working state (but this is nonblocking. i plan to test all of expo examples in the core 3 branch, so its fine to merge this into the core 3 branch)

@alexisintech
Copy link
Member

alexisintech commented Feb 3, 2026

@SarahSoutoul @manovotny I've finished my docs review, could I get more eyes on this before we merge into core 3 branch :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@SarahSoutoul SarahSoutoul Awaiting requested review from SarahSoutoul

Assignees

@octoper octoper

@alexisintech alexisintech

Labels

Blocked

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@octoper @alexisintech