docs: document passkey advanced configuration options#2519
Open
jhickmanit wants to merge 9 commits into
Open
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds an "Advanced configuration" section to passkey docs that documents WebAuthn options (authenticator attachment, resident key, user verification), attestation preferences and warnings, registration/login ceremony timeouts with Go-duration examples, and cross-deployment example configs (CLI, Ory Network, self-hosted). Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related issues
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/kratos/passwordless/05_passkeys.mdx`:
- Around line 152-163: The second TabItem element (the one with
value="self-hosted" / label="Self-hosted Ory Kratos") should not include the
default attribute because Docusaurus uses the first default in document order;
remove the redundant default from that TabItem and keep default only on the
first TabItem (value="network" / label="Ory Network") so tabs behave correctly.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: ac5a9cff-37cf-4a8c-b4fe-faeab9a4a557
📒 Files selected for processing (1)
docs/kratos/passwordless/05_passkeys.mdx
Contributor
There was a problem hiding this comment.
Pull request overview
Adds documentation for newly introduced “advanced” configuration options for the dedicated passkey strategy in Ory Kratos, focusing on WebAuthn ceremony controls and attestation policy.
Changes:
- Adds an “Advanced configuration” section with an options table covering authenticator selection, attestation policy, and ceremony timeouts.
- Adds a warning admonition describing the practical impact of restricting
attestation.allow_none. - Adds a multi-tab configuration example (CLI / Ory Network / self-hosted Kratos) demonstrating a cross-platform + required user verification setup.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Add an 'Advanced configuration' section under the dedicated passkey strategy that documents: - authenticator_selection (attachment, require_resident_key, user_verification) - attestation (preference, allow_none, allow_self, allow_untrusted) - timeouts (registration, login) Include a warning admonition explaining that disabling attestation.allow_none rejects most consumer passkeys, and add a three-tab example (Ory CLI, Ory Network, self-hosted Kratos) showing cross-platform attachment with required user verification.
jhickmanit
force-pushed
the
jhickmanit/passkey-options-docs
branch
from
6275bf8 to
4536462
Compare
jhickmanit
changed the title
The Kratos PR moved to a simpler API shape after review: - resident_key enum replaces the require_resident_key boolean (values: required, preferred, discouraged; default required) - attestation.policy enum replaces the three allow_* booleans (values: allow_untrusted, allow_self, allow_none; default allow_untrusted) - authenticator_selection.attachment no longer defaults to "platform"; omit it to accept either platform or cross-platform authenticators Rewrite the warning admonition to match the new policy semantics and note that Kratos does not verify attestation certificate chains today, so "allow_self" and "allow_none" are opt-in stricter stances rather than cryptographic validation. Update the self-hosted example to use the new field names.
Policy knob was removed from the Kratos PR because Kratos has no trust-anchor verification, so strict policy levels did not provide cryptographic validation. Docs now only describe the ceremony options that shipped: authenticator_selection, attestation.preference, timeouts.
Adds the missing default-behavior callout (attachment was hardcoded "platform", now defaults to no preference) and clarifies that attestation.preference is request-only — Kratos does not verify or enforce the returned attestation statement. Also corrects the timeouts defaults (5m with user verification, 2m without). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…intro - Note that timeouts.registration/login are browser-enforced; flow lifespans govern server-side validity - Reword section intro so it no longer contradicts the attachment default-change note - Precise wording for the library default timeout values Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
unatasha8
reviewed
Jun 6, 2026
- Fold the timeouts and attestation notes into the options table per
reviewer request; remove the standalone notes
- Use 'Ory Kratos' (not 'Kratos') in the attestation/timeout copy
- Reword intro ('settings', 'All are optional') and add a warning that
changing these settings can lock out existing users (matches Console UI)
- 'register using either platform or cross-platform' wording fix
- Drop redundant default attribute from the duplicate TabItem in the
enable-strategy tabs block
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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
Documents the new passkey configuration options. These options let implementers configure the WebAuthn ceremony and attestation policy for the dedicated passkey strategy.
New
Advanced configurationsection indocs/kratos/passwordless/05_passkeys.mdxthat covers:authenticator_selection— attachment (platform/cross-platform),require_resident_key,user_verificationattestation—preferenceand per-type allow flags (allow_none,allow_self,allow_untrusted)timeouts— registration and login ceremony timeoutsAll options are optional, and defaults match the behavior before they were introduced, so existing deployments need no changes.
Notes for reviewers
attestation.allow_nonerejects most consumer passkeys (iOS does not support attestation).Test plan
make format(prettier) runs cleannpm run buildsucceeds; no new broken links on this pageSummary by CodeRabbit