docs: add device authentication with PIN and biometrics guide

[hperl]

Documents device authentication end to end and restructures it into a section with per-platform guides.

New structure: kratos/passwordless/deviceauthn/

• Overview (keeps the existing URL): both modes — second-factor device binding and, with first_factor, complete passwordless login via app PIN or platform biometrics (AAL2 in one request). Concepts (three-key model, user_verification levels), configuration (first_factor, pin_max_attempts, ios_biometric_first_factor, app-ID pinning), a byte-exact protocol reference for all flows (enrollment, PIN enrollment with challenge SHA256(nonce ‖ transport_public_key), biometric enrollment, step-up, first-factor login with pin_proof, secret rotation) with sequence diagrams, normative client implementation requirements, recovery/lockout, troubleshooting, and the security model.
• Android / iOS guides: the full per-platform journey — second-factor binding plus PIN and biometric first factor — with complete copy-pasteable reference implementations (Keystore/BouncyCastle HPKE on Android incl. a fail-closed hardware check for the sealing key; App Attest/CryptoKit HPKE/Secure Enclave on iOS). The 2FA-vs-PIN attestation-challenge difference is called out where integrations commonly break.
• Dart/Flutter guide: the native-bridge pattern.

Corrections to existing content

• client_key_id is server-assigned (the lowercase-hex SHA-256 fingerprint of the key's public key); the add-key examples no longer show a client-chosen ID and the guides show how to derive or read it.
• Removed the outdated "can only be used as a second factor" claims.
• Step-up examples now reference the login flow (previously linked the settings flow); sequence diagrams use POST for flow submission.

Deployment structure (added 2026-07-13)

The section ships migrated to the deployment structure from AGENTS.md (#2674): page bodies live in shared partials under src/components/Shared/kratos/passwordless/deviceauthn/, exposed via shell pages under docs/network/... and docs/oel/... with canonicals pointing to the Network URLs. Both the Ory Network and OEL sidebars carry a "Device authentication" category (OEL under a new "Authentication" category), so OEL readers keep their navigation context. The previous public URL /docs/kratos/passwordless/deviceauthn 308-redirects to the Network page; the platform sub-pages are new URLs that only ever exist under the deployment paths.

The cross-page links from the platform guides deep-link into the overview's sections; to support that, SameDeploymentLink's dev-time existence check now strips #fragments before comparing against doc ids (one-line change, no runtime behavior change).

Coordination with #2675 (passwordless + MFA migration, same structure): whichever PR lands second merges the OEL "Authentication" category items and, if #2675 lands first, this branch's docs/kratos/mfa/01_overview.mdx link edit moves into the refreshed shared partial as a SameDeploymentLink with an oss= override.

Related Issue or Design Document

Documentation improvement. The deployment-structure migration addresses #2674 for this section.

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.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Updated documentation navigation to introduce a dedicated “Device authentication” section under Authentication, with an index and platform-specific guides (Android, iOS, Flutter).
  • Added a permanent redirect from the old device-authn docs path to the new network path to keep existing links working.
• Chores
  • Improved Markdown/MDX formatting handling for device-authn related content to avoid parsing issues with long inline components.

[Copilot]

Pull request overview

Adds comprehensive documentation for using the deviceauthn strategy as a first factor via an app PIN or platform biometrics (AAL2 in one submission), and updates the existing device binding page to reflect this and fix flow/verb references. The new page is also wired into the Ory Network and OEL sidebars so it’s discoverable under Passwordless authentication.

Changes:

• Adds a new “Device authentication with PIN and biometrics” page with configuration, protocol details, diagrams, and iOS/Android reference implementations.
• Updates the existing “Device binding” page to remove outdated “second factor only” claims and correct step-up references to the login flow and POST submissions.
• Registers the new page in sidebars-network.ts and sidebars-oel.ts.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
sidebars-oel.ts	Adds the new deviceauthn-pin doc entry to the OEL sidebar.
sidebars-network.ts	Adds the new deviceauthn-pin doc entry to the Network sidebar.
docs/kratos/passwordless/09_deviceauthn-pin.mdx	New guide page with protocol reference, diagrams, and client reference implementations.
docs/kratos/passwordless/08_deviceauthn.mdx	Updates device binding docs to point to first-factor usage and fixes flow/HTTP verb references.

---

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

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 46e47f5e-7daa-41b4-bfb2-a6e9d387cccf

📥 Commits

Reviewing files that changed from the base of the PR and between c2497bd and f25269f.

⛔ Files ignored due to path filters (2)

• src/components/Shared/kratos/01_mfa-overview.mdx is excluded by !**/*.mdx
• src/components/Shared/kratos/passwordless/deviceauthn/flutter.mdx is excluded by !**/*.mdx

📒 Files selected for processing (4)

• .prettierrc.js
• sidebars-network.ts
• sidebars-oel.ts
• vercel.json

🚧 Files skipped from review as they are similar to previous changes (2)

• .prettierrc.js
• sidebars-oel.ts

---

📝 Walkthrough

Walkthrough

Device authentication documentation navigation now exposes an index and Android, iOS, and Flutter pages in both sidebars. The former Kratos passwordless URL permanently redirects to the network path, and Prettier’s MDX override now covers device-authentication partials.

Changes

Device authentication documentation

Layer / File(s)	Summary
Reorganize navigation and redirect legacy URL sidebars-network.ts, sidebars-oel.ts, vercel.json	Replaces standalone device-authentication sidebar entries with platform-specific categories and permanently redirects the previous path to the network documentation path.
Extend deviceauthn MDX formatting .prettierrc.js	Adds device-authentication MDX partials to the Prettier override and documents the related parsing issue.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Possibly related PRs

• ory/docs#2447: Updates navigation around the existing kratos/passwordless/deviceauthn documentation path.
• ory/docs#2636: Also changes documentation redirect behavior in vercel.json.

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

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title matches the main change: adding device authentication documentation with PIN and biometrics.
Description check	✅ Passed	The PR description covers the changes, related issue, checklist items, and deployment notes, with only minor template items left unfilled.
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.

✨ 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 deviceauthn-pin-docs

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install timed out. The project may have too many dependencies for the sandbox.

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[gaultier]

• Did we update the code snippets for mobile to adapt to the latest changes in the API? They might be outdated
• The iOS and Android specific page should reiterate that the app id(s) should be present in the config for better security, with an example
• Small formatting issue with the bullet points:

---

---

[hperl]

Did we update the code snippets for mobile to adapt to the latest changes in the API? They might be outdated

I think so, let me check again. The client_key_id change was reflected, I think that was the big one. Did you notice anything off?

The iOS and Android specific page should reiterate that the app id(s) should be present in the config for better security, with an example

Good idea!

Small formatting issue with the bullet points

Strange, the deployed preview had no such issues (source), and locally I didn't notice that either.