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

[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]

📝 Walkthrough

Walkthrough

The network and Ory Kratos documentation sidebars now include the kratos/passwordless/deviceauthn-pin page.

Changes

Passwordless navigation

Layer / File(s)	Summary
Add deviceauthn-pin sidebar entries sidebars-network.ts, sidebars-oel.ts	Adds kratos/passwordless/deviceauthn-pin to both sidebar item lists near the existing passwordless device authentication documentation.

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

Possibly related PRs

• ory/docs#2447: Adds the related deviceauthn documentation entry to the sidebar.
• ory/docs#2589: Adds Ory Kratos guide entries to sidebars-network.ts.

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

🚥 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 is concise and accurately summarizes the main documentation change for device authentication with PIN and biometrics.
Description check	✅ Passed	The description covers the purpose, related issue, checklist, and deployment notes, so it is mostly complete for this documentation PR.

✨ 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

---

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.}