Skip to content

docs: migrate kratos passwordless, mfa, and debug docs to deployment structure#2675

Open
hperl wants to merge 9 commits into
masterfrom
kratos-auth-deployment-structure
Open

docs: migrate kratos passwordless, mfa, and debug docs to deployment structure#2675
hperl wants to merge 9 commits into
masterfrom
kratos-auth-deployment-structure

Conversation

@hperl

@hperl hperl commented Jul 12, 2026

Copy link
Copy Markdown
Member

Migrates the kratos passwordless and MFA documentation to the deployment structure from AGENTS.md, so Ory Network and OEL readers each keep their own sidebar navigation instead of sharing one doc that can only belong to a single sidebar.

  • Page bodies move to shared partials under src/components/Shared/kratos/{passwordless,mfa}/ (including their static assets).
  • Thin shell pages under docs/network/kratos/... and docs/oel/kratos/... import the partials; canonicals on both point to the Network URL per the default canonical rule.
  • The Network sidebar now lists the Network shells; the OEL sidebar gains an Authentication category (which also finally lists the previously orphaned oel/kratos/mfa-overview shell), fixing the missing OEL navigation context for feature docs.
  • The previously half-migrated MFA overview is completed: the shared partial is refreshed from the newer co-mingled page (which had drifted ahead) and the old page is removed.
  • Links between migrated pages use SameDeploymentLink; inbound links across the docs are updated accordingly.
  • vercel.json: 14 new redirects for the old URLs plus 10 existing destinations retargeted to flatten redirect chains.
  • Debug section (merged in via docs: migrate kratos debug docs to deployment structure #2678): the four docs/kratos/debug/* pages were autogenerated into both the OEL and OSS sidebars, so one deployment always hijacked the other's navigation. They now use the same shared-partial + shell structure for OEL and OSS with the self-hosted canonical exception (OEL self-canonical, OSS canonical → OEL, no Network shells), and the old URLs redirect to the OEL pages.

Related Issue or Design Document

Part of #2674 (device authentication follows as a separate PR once #2673 lands).

Checklist

  • I have read the contributing guidelines and signed the CLA.
  • I have referenced an issue containing the design document if my change introduces a new feature.
  • I have read the security policy.
  • I confirm that this pull request does not address a security vulnerability.
  • I have added tests that prove my fix is effective or that my feature works.
  • I have added the necessary documentation within the code base (if appropriate).

Further comments

Notes for reviewers:

  • docs: add device authentication with PIN and biometrics guide #2673 coordination: this PR deletes docs/kratos/mfa/01_overview.mdx (its content lives on in the refreshed shared partial, with the "Device binding" → "Device authentication" rename pre-applied). docs: add device authentication with PIN and biometrics guide #2673 edits that file with the same rename, so it simply drops that hunk on rebase. The deviceauthn page and both of its sidebar entries are deliberately untouched here — docs: add device authentication with PIN and biometrics guide #2673 owns them.
  • Redirect destination style: new and retargeted vercel.json destinations use path-relative /docs/network/... form, matching the newest existing entries (older entries use absolute https://www.ory.com/...).
  • oss= overrides in the MFA overview partial: six shells import it (network/oel/oss × top-level + quickstarts). Since this PR intentionally creates no OSS sub-page shells, the partial's SameDeploymentLinks carry oss= overrides pointing OSS readers at the Network pages; without them the OSS pages would have broken links.
  • Old URLs (/docs/kratos/passwordless/*, /docs/kratos/mfa/*) 308-redirect to the new Network URLs; the custom passkeys-mobile-web-implementation slug is dropped in favor of the plain passkeys-mobile slug (covered by a redirect).
  • Full docusaurus build passes; the only remaining warnings are pre-existing (/docs/reference/openapi/* links and two stale /docs/reference/api#operation/... anchors that exist on master too).

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • Reorganized passwordless and multi-factor authentication content in the sidebars, including adding a clearer Authentication section and updating doc paths across OEL and OSS.
    • Updated in-app documentation links for passkeys, one-time codes, and the MFA overview cards.
    • Refreshed Kratos troubleshooting content by adding dedicated pages and removing older duplicates.
  • Bug Fixes
    • Updated legacy documentation redirects to consistently route MFA and passwordless topics to the current network documentation URLs (including WebAuthn/FIDO-YubiKey, TOTP, and step-up authentication).

hperl and others added 7 commits July 12, 2026 20:13
Shared partials under src/components/Shared/kratos/passwordless with
Network and OEL shell pages, per the migration pattern in AGENTS.md.
Part of #2674.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Shared partials under src/components/Shared/kratos/mfa with Network and
OEL shell pages; the previously half-migrated MFA overview partial is
refreshed from the newer co-mingled page, which is removed.
Part of #2674.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Network sidebar uses the network shells; the OEL sidebar gains an
Authentication category so self-hosted readers keep OEL navigation
context (#2674).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
SameDeploymentLink keeps readers in their deployment; the welcome page
cards point at the Network shells. Part of #2674.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The shared kratos MFA overview partial is imported by the OSS deployment
shell, but the migration created MFA/passwordless sub-page shells only for
Network and OEL. On OSS the SameDeploymentLink targets resolved to
non-existent /docs/oss/kratos/... pages, producing broken links. Add oss=
overrides pointing to the Network pages (matching the OSS shell canonical and
the vercel.json redirects). Network/OEL behaviour is unchanged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Prettier's 80-column reflow orphaned "Go to" as its own paragraph
before the ConsoleLink tags; reword so the tags stay mid-line.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@hperl hperl requested a review from vinckr as a code owner July 12, 2026 19:51
Copilot AI review requested due to automatic review settings July 12, 2026 19:51
@hperl hperl self-assigned this Jul 12, 2026
@hperl hperl requested review from piotrmsc and wassimoo as code owners July 12, 2026 19:51

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR migrates Ory Kratos passwordless and MFA documentation into the per-deployment “shell + shared partial” structure so that Ory Network and OEL readers keep stable, deployment-specific sidebar navigation while sharing the same page bodies.

Changes:

  • Moved passwordless + MFA page bodies into shared partials under src/components/Shared/kratos/... and added thin shell pages under docs/network/... and docs/oel/... with Network canonicals.
  • Updated Network and OEL sidebars to point at the new deployment shell doc IDs (and added an OEL “Authentication” category).
  • Updated internal links and Vercel redirects to point old URLs to the new Network routes and reduce redirect chaining.

Reviewed changes

Copilot reviewed 43 out of 64 changed files in this pull request and generated no comments.

Show a summary per file
File Description
vercel.json Retargets existing redirects and adds new ones from legacy kratos passwordless/MFA URLs to Network deployment URLs.
src/pages/_assets/welcome-content.tsx Updates homepage “docs” links to the new Network deployment routes for passkeys/OTP/MFA overview.
src/components/Shared/kratos/passwordless/07_code.mdx Converts passwordless OTP page into a shared partial (no frontmatter) and updates links to stable doc routes.
src/components/Shared/kratos/passwordless/06_passkeys-mobile.mdx Converts passkeys mobile guide into a shared partial and updates cross-page links to deployment-aware links.
src/components/Shared/kratos/passwordless/05_passkeys.mdx Converts passkeys overview into a shared partial and updates image/link paths for the new shared location.
src/components/Shared/kratos/passwordless/00_overview.mdx Adds new shared partial for passwordless overview content.
src/components/Shared/kratos/passwordless/_static/ax-registration-code.png Adds static asset under shared passwordless partials.
src/components/Shared/kratos/mfa/30_sms.mdx Converts MFA via SMS/email into a shared partial and updates links/image paths.
src/components/Shared/kratos/mfa/25_lookup-secrets.mdx Converts lookup secrets page into a shared partial and updates image paths.
src/components/Shared/kratos/mfa/20_webauthn-fido-yubikey.mdx Converts WebAuthn MFA page into a shared partial and updates links/image paths.
src/components/Shared/kratos/mfa/15_totp.mdx Converts TOTP MFA page into a shared partial and updates image paths.
src/components/Shared/kratos/mfa/05_step-up-authentication.mdx Converts step-up auth page into a shared partial and updates links to stable API/doc routes.
src/components/Shared/kratos/01_mfa-overview.mdx Refreshes shared MFA overview and switches internal links to SameDeploymentLink with OSS overrides.
sidebars-oel.ts Adds an “Authentication” category listing OEL shells for passwordless and MFA content.
sidebars-network.ts Switches Network sidebar entries from co-mingled doc IDs to Network deployment shell doc IDs.
docs/oel/kratos/passwordless/07_code.mdx Adds OEL shell page for passwordless OTP, importing the shared partial and setting canonical to Network.
docs/oel/kratos/passwordless/06_passkeys-mobile.mdx Adds OEL shell page for passkeys mobile, importing shared partial and setting canonical to Network.
docs/oel/kratos/passwordless/05_passkeys.mdx Adds OEL shell page for passkeys overview, importing shared partial and setting canonical to Network.
docs/oel/kratos/passwordless/00_overview.mdx Adds OEL shell page for passwordless overview, importing shared partial and setting canonical to Network.
docs/oel/kratos/mfa/30_sms.mdx Adds OEL shell page for SMS/email MFA, importing shared partial and setting canonical to Network.
docs/oel/kratos/mfa/25_lookup-secrets.mdx Adds OEL shell page for lookup secrets, importing shared partial and setting canonical to Network.
docs/oel/kratos/mfa/20_webauthn-fido-yubikey.mdx Adds OEL shell page for WebAuthn MFA, importing shared partial and setting canonical to Network.
docs/oel/kratos/mfa/15_totp.mdx Adds OEL shell page for TOTP MFA, importing shared partial and setting canonical to Network.
docs/oel/kratos/mfa/05_step-up-authentication.mdx Adds OEL shell page for step-up authentication, importing shared partial and setting canonical to Network.
docs/network/kratos/passwordless/07_code.mdx Adds Network shell page for passwordless OTP, importing shared partial and self-canonicalizing.
docs/network/kratos/passwordless/06_passkeys-mobile.mdx Adds Network shell page for passkeys mobile, importing shared partial and self-canonicalizing.
docs/network/kratos/passwordless/05_passkeys.mdx Adds Network shell page for passkeys overview, importing shared partial and self-canonicalizing.
docs/network/kratos/passwordless/00_overview.mdx Adds Network shell page for passwordless overview, importing shared partial and self-canonicalizing.
docs/network/kratos/mfa/30_sms.mdx Adds Network shell page for SMS/email MFA, importing shared partial and self-canonicalizing.
docs/network/kratos/mfa/25_lookup-secrets.mdx Adds Network shell page for lookup secrets, importing shared partial and self-canonicalizing.
docs/network/kratos/mfa/20_webauthn-fido-yubikey.mdx Adds Network shell page for WebAuthn MFA, importing shared partial and self-canonicalizing.
docs/network/kratos/mfa/15_totp.mdx Adds Network shell page for TOTP MFA, importing shared partial and self-canonicalizing.
docs/network/kratos/mfa/05_step-up-authentication.mdx Adds Network shell page for step-up authentication, importing shared partial and self-canonicalizing.
docs/kratos/social-signin/93_upstream-mfa.mdx Updates references to step-up auth to use SameDeploymentLink.
docs/kratos/self-service/flows/verify-email-account-activation.mdx Updates TOTP/WebAuthn links to use SameDeploymentLink list items.
docs/kratos/self-service/flows/user-login.mdx Updates passkey/code links to new deployment-aware targets via SameDeploymentLink.
docs/kratos/passwordless/00_overview.mdx Removes the old co-mingled passwordless overview page after migrating content to shared + deployment shells.
docs/kratos/mfa/01_overview.mdx Removes the old co-mingled MFA overview page after migrating content to shared + deployment shells.
docs/kratos/guides/deploy-kratos-example.mdx Updates MFA guide link to SameDeploymentLink (deployment-aware).
docs/kratos/emails-sms/05_custom-email-templates.mdx Updates one-time-code docs links to SameDeploymentLink.
docs/integrates-with/mfa/yubikey.mdx Updates canonical to Network and replaces direct link with SameDeploymentLink.
docs/integrates-with/mfa/okta-verify.mdx Updates WebAuthn MFA reference to SameDeploymentLink.
docs/integrates-with/mfa/duo-security.mdx Updates WebAuthn MFA reference to SameDeploymentLink.
docs/getting-started/local-development.mdx Updates WebAuthn reference to SameDeploymentLink.
Comments suppressed due to low confidence (2)

src/components/Shared/kratos/mfa/25_lookup-secrets.mdx:60

  • Typo in the admonition text: “secretes” should be “secrets”.
    src/components/Shared/kratos/mfa/30_sms.mdx:14
  • Use “cannot” (one word) and capitalize “SMS” for consistency with the rest of the page.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@coderabbitai

coderabbitai Bot commented Jul 12, 2026

Copy link
Copy Markdown

Review Change Stack

📝 Walkthrough

Walkthrough

Kratos passwordless, MFA, and debug documentation are reorganized under deployment-specific paths, with updated sidebar entries, landing-page links, troubleshooting content, and permanent redirects from legacy URLs.

Changes

Kratos documentation paths

Layer / File(s) Summary
Kratos troubleshooting content
src/components/Shared/kratos/debug/*, docs/kratos/guides/setting-up-password-hashing-parameters.md
Adds Argon2 and general troubleshooting pages and updates the password-hashing guide link to the OEL debug path.
Documentation navigation and landing links
sidebars-network.ts, sidebars-oel.ts, sidebars-oss.ts, src/pages/_assets/welcome-content.tsx
Updates passwordless and MFA sidebar entries, adds OEL authentication navigation, adjusts debug directories, and changes identity-management card URLs.
Legacy Kratos redirects
vercel.json
Maps legacy passwordless, MFA, and debug URLs to corresponding network documentation pages through permanent redirects.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

  • ory/docs#2589: Adds related Kratos MFA navigation entries.
  • ory/docs#2635: Modifies overlapping Kratos MFA and passwordless redirect definitions.

Suggested reviewers: aeneasr, wassimoo, unatasha8, piotrmsc, zepatrik

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title clearly summarizes the main migration of Kratos passwordless, MFA, and debug docs to the deployment structure.
Description check ✅ Passed The description includes the required sections, a related issue, checklist, and detailed notes; it is complete enough for review.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch kratos-auth-deployment-structure

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@vercel.json`:
- Line 1527: Add a Vercel redirect rule for the legacy
`/docs/kratos/passwordless/07_code` path, targeting
`/docs/network/kratos/passwordless/one-time-code`, alongside the existing
passwordless redirect entries in vercel.json.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 8214fd42-f441-4db1-8f8d-8b3a20fa6dd3

📥 Commits

Reviewing files that changed from the base of the PR and between 202e8d6 and a5d57eb.

⛔ Files ignored due to path filters (60)
  • docs/getting-started/local-development.mdx is excluded by !**/*.mdx
  • docs/integrates-with/mfa/duo-security.mdx is excluded by !**/*.mdx
  • docs/integrates-with/mfa/okta-verify.mdx is excluded by !**/*.mdx
  • docs/integrates-with/mfa/yubikey.mdx is excluded by !**/*.mdx
  • docs/kratos/emails-sms/05_custom-email-templates.mdx is excluded by !**/*.mdx
  • docs/kratos/guides/deploy-kratos-example.mdx is excluded by !**/*.mdx
  • docs/kratos/mfa/01_overview.mdx is excluded by !**/*.mdx
  • docs/kratos/passwordless/00_overview.mdx is excluded by !**/*.mdx
  • docs/kratos/self-service/flows/user-login.mdx is excluded by !**/*.mdx
  • docs/kratos/self-service/flows/verify-email-account-activation.mdx is excluded by !**/*.mdx
  • docs/kratos/social-signin/93_upstream-mfa.mdx is excluded by !**/*.mdx
  • docs/network/kratos/mfa/05_step-up-authentication.mdx is excluded by !**/*.mdx
  • docs/network/kratos/mfa/15_totp.mdx is excluded by !**/*.mdx
  • docs/network/kratos/mfa/20_webauthn-fido-yubikey.mdx is excluded by !**/*.mdx
  • docs/network/kratos/mfa/25_lookup-secrets.mdx is excluded by !**/*.mdx
  • docs/network/kratos/mfa/30_sms.mdx is excluded by !**/*.mdx
  • docs/network/kratos/passwordless/00_overview.mdx is excluded by !**/*.mdx
  • docs/network/kratos/passwordless/05_passkeys.mdx is excluded by !**/*.mdx
  • docs/network/kratos/passwordless/06_passkeys-mobile.mdx is excluded by !**/*.mdx
  • docs/network/kratos/passwordless/07_code.mdx is excluded by !**/*.mdx
  • docs/oel/kratos/mfa/05_step-up-authentication.mdx is excluded by !**/*.mdx
  • docs/oel/kratos/mfa/15_totp.mdx is excluded by !**/*.mdx
  • docs/oel/kratos/mfa/20_webauthn-fido-yubikey.mdx is excluded by !**/*.mdx
  • docs/oel/kratos/mfa/25_lookup-secrets.mdx is excluded by !**/*.mdx
  • docs/oel/kratos/mfa/30_sms.mdx is excluded by !**/*.mdx
  • docs/oel/kratos/passwordless/00_overview.mdx is excluded by !**/*.mdx
  • docs/oel/kratos/passwordless/05_passkeys.mdx is excluded by !**/*.mdx
  • docs/oel/kratos/passwordless/06_passkeys-mobile.mdx is excluded by !**/*.mdx
  • docs/oel/kratos/passwordless/07_code.mdx is excluded by !**/*.mdx
  • src/components/Shared/kratos/01_mfa-overview.mdx is excluded by !**/*.mdx
  • src/components/Shared/kratos/mfa/05_step-up-authentication.mdx is excluded by !**/*.mdx
  • src/components/Shared/kratos/mfa/15_totp.mdx is excluded by !**/*.mdx
  • src/components/Shared/kratos/mfa/20_webauthn-fido-yubikey.mdx is excluded by !**/*.mdx
  • src/components/Shared/kratos/mfa/25_lookup-secrets.mdx is excluded by !**/*.mdx
  • src/components/Shared/kratos/mfa/30_sms.mdx is excluded by !**/*.mdx
  • src/components/Shared/kratos/mfa/_static/1.png is excluded by !**/*.png
  • src/components/Shared/kratos/mfa/_static/10.png is excluded by !**/*.png
  • src/components/Shared/kratos/mfa/_static/11.png is excluded by !**/*.png
  • src/components/Shared/kratos/mfa/_static/2.png is excluded by !**/*.png
  • src/components/Shared/kratos/mfa/_static/3.png is excluded by !**/*.png
  • src/components/Shared/kratos/mfa/_static/4.png is excluded by !**/*.png
  • src/components/Shared/kratos/mfa/_static/5.png is excluded by !**/*.png
  • src/components/Shared/kratos/mfa/_static/6.png is excluded by !**/*.png
  • src/components/Shared/kratos/mfa/_static/7.png is excluded by !**/*.png
  • src/components/Shared/kratos/mfa/_static/8.png is excluded by !**/*.png
  • src/components/Shared/kratos/mfa/_static/9.png is excluded by !**/*.png
  • src/components/Shared/kratos/passwordless/00_overview.mdx is excluded by !**/*.mdx
  • src/components/Shared/kratos/passwordless/05_passkeys.mdx is excluded by !**/*.mdx
  • src/components/Shared/kratos/passwordless/06_passkeys-mobile.mdx is excluded by !**/*.mdx
  • src/components/Shared/kratos/passwordless/07_code.mdx is excluded by !**/*.mdx
  • src/components/Shared/kratos/passwordless/_static/ax-login-options.png is excluded by !**/*.png
  • src/components/Shared/kratos/passwordless/_static/ax-login-options2.png is excluded by !**/*.png
  • src/components/Shared/kratos/passwordless/_static/ax-registration-code.png is excluded by !**/*.png
  • src/components/Shared/kratos/passwordless/_static/external-device-choose.png is excluded by !**/*.png
  • src/components/Shared/kratos/passwordless/_static/external-device-verify-identity.png is excluded by !**/*.png
  • src/components/Shared/kratos/passwordless/_static/passkeys/console.png is excluded by !**/*.png
  • src/components/Shared/kratos/passwordless/_static/passwordless-login-flow.png is excluded by !**/*.png
  • src/components/Shared/kratos/passwordless/_static/webauthn/1.png is excluded by !**/*.png
  • src/components/Shared/kratos/passwordless/_static/webauthn/2.png is excluded by !**/*.png
  • src/components/Shared/kratos/passwordless/_static/webauthn/3.png is excluded by !**/*.png
📒 Files selected for processing (4)
  • sidebars-network.ts
  • sidebars-oel.ts
  • src/pages/_assets/welcome-content.tsx
  • vercel.json

Comment thread vercel.json
Add a redirect for the legacy /docs/kratos/passwordless/07_code URL
(orphaned since the page received its explicit one-time-code id) and
fix two typos in the moved MFA partials.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The debug pages were autogenerated into both the OEL and OSS sidebars,
so one deployment always hijacked the other's navigation (#2674). Move
them to shared partials with OEL and OSS shells; OEL is canonical per
the self-hosted exception.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
@hperl hperl changed the title docs: migrate kratos passwordless and mfa docs to deployment structure docs: migrate kratos passwordless, mfa, and debug docs to deployment structure Jul 13, 2026

@unatasha8 unatasha8 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewing... please don't merge yet.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants