Conversation
The Built-in IdP now supports TOTP-based multi-factor authentication (tailor-platform/sdk#1541, #1561, #1562; platform-core-services MFA work through #12233 / #12257). The user-facing guides under `docs/guides/` did not reflect the new surface, so app developers had no way to learn how to enable, enforce, or self-service MFA without reading the SDK reference page. This documents the consumer-facing behavior in the two guides that are docs-repo-native: - `docs/guides/auth/integration/built-in-idp.md` — add a Multi-Factor Authentication (TOTP) section under userAuthPolicy, splitting the two flows that are easy to conflate: (a) inline enrollment that the IdP /signin page handles itself when `requireMfa: true`, and (b) self-service factor management via `_requestMfaSettingsUrl`, which issues a per-user MFA settings page URL. Documents `enableMfa`, `requireMfa`, `allowedReturnOrigins`, `mfaIssuer`, the cross-field constraints, the `permission.unenrollMfa` requirement, and the two new GraphQL operations plus the `mfaEnrolled` / `mfaFactorIds` fields on the User type. Also extends the User Management op list. - `docs/guides/function/managing-idp-users.md` — extend the runtime `tailor.idp.Client` interface block with `User.mfaEnrolled`, `User.mfaFactorIds`, `UnenrollMfaInput`, and `client.unenrollMfa()`, plus an Unenroll MFA Factor section showing the typical admin recovery flow. `docs/sdk/services/idp.md` is intentionally not edited here — it is auto-synced from the SDK repo by the `sdk-docs-sync` workflow, and the SDK-side page already covers the SDK-shaped surface (gqlOperations MFA fields, schema constraints, runtime API).
Fix two issues raised in Copilot review on #148: - built-in-idp.md: the `requireMfa` option description said unenrolled users must complete enrollment "via the MFA settings page", which contradicts the inline /signin enrollment flow described two paragraphs above. Rewrite to point at the inline flow and note that the application does not need to call _requestMfaSettingsUrl to bootstrap enrollment. - managing-idp-users.md: note that `unenrollMfa` additionally requires read access to the target user (enforced at the dataplane RPC, mirroring the built-in-idp guide), so a namespace that denies `read` cannot use `unenrollMfa` either.
…ports Address Copilot review on c288b80: - managing-idp-users.md: prose said `unenrollMfa` removes a single factor while the only example unenrolled every factor via `Promise.all`, which a copy/paste would reproduce by mistake. Lead with the single-factor case (the API's actual unit) and present the full-reset loop as an explicit second example for the lost-device recovery flow. Pluralize the "no enrolled MFA factors" reason string while there. - built-in-idp.md: drop unused imports (`defineConfig`, `defineAuth`, `user`) from the MFA configuration snippet so the imports actually match what the snippet declares.
Address Copilot review on 979a5b0: `Client.unenrollMfa()` returns `Promise<boolean>`, but both new examples discarded the result and returned `{ success: true }` unconditionally. That breaks the convention established by `deleteUser` / `sendPasswordResetEmail` elsewhere in this guide and would mask a false return from the API. - Single-factor example now captures and returns the boolean (`const success = await idpClient.unenrollMfa(...); return { success }`). - Reset-all example collects the per-factor booleans via `Promise.all` and aggregates with `results.every(Boolean)`.
anukiransolur
approved these changes
Jun 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The Built-in IdP now supports TOTP-based multi-factor authentication (tailor-platform/sdk#1541, #1561, #1562), but the user-facing guides under
docs/guides/did not yet describe it. This documents the consumer-facing behavior so app developers can enable, enforce, and self-service MFA without having to read the SDK reference.Changes
docs/guides/auth/integration/built-in-idp.md— add a Multi-Factor Authentication (TOTP) section underuserAuthPolicy. Splits the two flows that are easy to conflate:requireMfa: true) — the IdP/signinpage handles QR + verify inline before completing the OIDC callback. No application-side code is needed to bootstrap enrollment.enableMfa: true) —_requestMfaSettingsUrlissues an MFA settings page URL bound to the calling user; the app redirects them to it to add or remove their own factors.Documents
enableMfa/requireMfa/allowedReturnOrigins/mfaIssuer, the cross-field constraints, thepermission.unenrollMfarequirement, and the two new GraphQL operations plus themfaEnrolled/mfaFactorIdsfields on the User type. Also extends the User Management operation list to include_requestMfaSettingsUrland_unenrollMfa.docs/guides/function/managing-idp-users.md— extend the runtimetailor.idp.Clientinterface block withUser.mfaEnrolled,User.mfaFactorIds,UnenrollMfaInput, andclient.unenrollMfa(), and add an Unenroll MFA Factor section showing the typical admin recovery flow.docs/sdk/services/idp.mdis intentionally not edited here. It is auto-synced from the SDK repo by thesdk-docs-syncworkflow, and the SDK-side page already covers the SDK-shaped surface (gqlOperationsMFA fields, schema constraints, runtime API).Verification
pnpm build✅ (pages render, the new#multi-factor-authentication-totpanchor resolves)pnpm lint✅ (no new issues)npx tsx scripts/validate-schema.mts✅tailor-platform/sdk@main(packages/sdk/src/runtime/idp.ts,packages/sdk/src/parser/service/idp/schema.ts) — therequireMfa: trueflow enrolls users inline at/signin, so the doc reflects that rather than directing apps to call_requestMfaSettingsUrlfor initial enrollment.